surfaces/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
05-mvp-deployment	03	infra	matrix attachments shared-volume agents pytest	phase provides 04-matrix-mvp-shared-agent-context-and-context-management-comma direct AgentApi integration and Matrix outgoing file rendering	shared-volume attachment path regressions for /agents deployment relative workspace-path normalization for upstream attachment transport send-file event normalization for Matrix outbound file rendering	matrix deployment shared-volume file-transfer	added patterns relative workspace_path transport shared-volume root normalization	created modified tests/adapter/matrix/test_files.py tests/platform/test_real.py sdk/real.py	Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary. Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events.	Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths. Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs.	PH05-04	3 min	2026-04-27

Phase 05 Plan 03: Shared-volume attachment path hardening Summary

Room-safe Matrix inbox paths and relative shared-volume attachment normalization for /agents deployment

Performance

• Duration: 3 min
• Started: 2026-04-27T22:02:34Z
• Completed: 2026-04-27T22:05:41Z
• Tasks: 2
• Files modified: 3

Accomplishments

• Added regression coverage for room-safe surfaces/matrix/.../inbox/... attachment layout under /agents workspaces.
• Added explicit tests for /workspace/... and /agents/... attachment-path normalization on both upstream send and downstream send-file rendering.
• Tightened RealPlatformClient so only relative workspace_path values are forwarded to the agent API.

Task Commits

Each task was committed atomically:

1. Task 1: Add shared-volume file contract tests for /agents deployment - cafb0ec (test)
2. Task 2: Tighten attachment path handling for the shared volume contract - 9a03160 (fix)

Files Created/Modified

• tests/adapter/matrix/test_files.py - covers room-safe shared-volume inbox paths under an /agents workspace root.
• tests/platform/test_real.py - covers relative attachment forwarding and send-file normalization for /workspace and /agents paths.
• sdk/real.py - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary.

Decisions Made

• Kept adapter/matrix/files.py unchanged so path construction remains centralized there.
• Reused one normalization helper in sdk/real.py for both _attachment_paths() and _attachment_from_send_file_event() to keep inbound and outbound behavior aligned.

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment

• Found during: Task 2 (Tighten attachment path handling for the shared volume contract)
• Issue: The plan's raw pytest command collected with an interpreter missing PyYAML, which blocked tests/adapter/matrix/test_send_outgoing.py before runtime assertions could execute.
• Fix: Re-ran verification with UV_CACHE_DIR=/tmp/uv-cache uv run pytest ..., matching the repo's CLAUDE.md guidance and the project .venv.
• Files modified: None
• Verification: UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v
• Committed in: None (verification-environment adjustment only)

---

Total deviations: 1 auto-fixed (1 blocking) Impact on plan: No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment.

Issues Encountered

• The ambient pytest resolved to a different virtualenv than the project .venv, so direct verification was unreliable for dependency-backed Matrix tests.

User Setup Required

None - no external service configuration required.

Next Phase Readiness

• Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering.
• Phase 05 compose and deployment work can assume the /agents contract without adding file proxy infrastructure.

Self-Check: PASSED

• Found .planning/phases/05-mvp-deployment/05-03-SUMMARY.md
• Verified commit cafb0ec exists in git history
• Verified commit 9a03160 exists in git history

---

Phase: 05-mvp-deployment Completed: 2026-04-27