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

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
05-mvp-deployment	03	execute	1		adapter/matrix/files.py sdk/real.py tests/adapter/matrix/test_files.py tests/platform/test_real.py	true	PH05-04	truths artifacts key_links Incoming Matrix attachments are written into a room-safe shared-volume path and passed upstream as relative workspace paths. Agent-emitted files can be returned to Matrix users without inventing a separate file proxy. The shared-volume contract works with the Phase 05 `/agents` deployment shape. path provides adapter/matrix/files.py Room-safe shared-volume path building and path resolution path provides sdk/real.py Attachment path passthrough and send-file normalization path provides tests/adapter/matrix/test_files.py Regression coverage for shared-volume path construction from to via pattern adapter/matrix/files.py sdk/real.py relative `workspace_path` transport workspace_path from to via pattern sdk/real.py adapter/matrix/bot.py OutgoingMessage attachments rendered back to Matrix MsgEventSendFile

Harden the Matrix attachment path contract around the shared deployment volume instead of custom transport shims.

Purpose: Phase 05 file handling must survive real deployment with room-safe paths and outbound file delivery through the existing shared-volume model. Output: Attachment-path regressions and any targeted runtime fixes needed for /agents-backed shared volume behavior.

<execution_context> @/Users/a/.codex/get-shit-done/workflows/execute-plan.md @/Users/a/.codex/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/05-mvp-deployment/05-RESEARCH.md @.planning/phases/05-mvp-deployment/05-VALIDATION.md @docs/deploy-architecture.md @docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md @adapter/matrix/files.py @sdk/real.py @tests/adapter/matrix/test_files.py @tests/platform/test_real.py From `adapter/matrix/files.py`:

def build_workspace_attachment_path(
    *,
    workspace_root: Path,
    matrix_user_id: str,
    room_id: str,
    filename: str,
    timestamp: str | None = None,
) -> tuple[str, Path]: ...

From sdk/real.py:

@staticmethod
def _attachment_paths(attachments: list[Attachment] | None) -> list[str]: ...

@staticmethod
def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: ...

Task 1: Add shared-volume file contract tests for `/agents` deployment tests/adapter/matrix/test_files.py, tests/platform/test_real.py tests/adapter/matrix/test_files.py, tests/platform/test_real.py, adapter/matrix/files.py, sdk/real.py, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md - Test 1: incoming Matrix files land under a room-safe `surfaces/matrix/.../inbox/...` path that remains relative to the agent workspace contract. - Test 2: upstream file events normalize `/workspace/...` and `/agents/...`-style absolute paths into relative `workspace_path` values. - Test 3: attachment forwarding never switches to inline blobs or HTTP shim URLs (per PH05-04). - `tests/adapter/matrix/test_files.py` asserts the path namespace includes sanitized user and room components. - `tests/platform/test_real.py` contains explicit coverage for send-file path normalization. - The automated test command in `` exercises both inbound and outbound sides of the shared-volume contract. Expand the file-flow regressions around the real deployment contract described in research and `docs/deploy-architecture.md`. Keep the tests centered on relative `workspace_path` transport and room-safe on-disk layout. Do not introduce proxy URLs, base64 payload transport, or new platform endpoints. pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v Phase 05 has direct test coverage for `/agents`-backed shared-volume behavior across inbound and outbound file paths. Task 2: Tighten attachment path handling for the shared volume contract adapter/matrix/files.py, sdk/real.py adapter/matrix/files.py, sdk/real.py, tests/adapter/matrix/test_files.py, tests/platform/test_real.py, docs/deploy-architecture.md - Test 1: inbound attachment helpers keep returning relative paths even when the bot writes into `/agents`. - Test 2: outbound file normalization accepts absolute paths from the agent runtime but strips them back to relative workspace paths for Matrix rendering. - Test 3: no code path emits non-relative attachment references to the upstream agent API. - `sdk/real.py` only forwards relative attachment paths to the agent API. - `sdk/real.py` normalizes both `/workspace` and `/agents` absolute roots if present in send-file events. - `adapter/matrix/files.py` remains the single source of truth for room-safe attachment path construction. Implement only the minimum runtime changes needed to satisfy the shared-volume tests. Keep `adapter/matrix/files.py` as the single place that builds surface-owned attachment paths, and keep `sdk/real.py` responsible only for attachment passthrough and send-file normalization. Do not widen this plan into compose edits, registry redesign, or bot command changes. pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v Incoming and outgoing file references stay compatible with the real shared-volume deployment contract, and the targeted file/path regressions pass. Run the Matrix file helper, real platform client, and outgoing-send slices together so the shared-volume contract is validated from write path through return-to-user rendering.

<success_criteria> The Matrix bot and agent runtime can exchange file references through the shared volume using only relative workspace paths and room-safe storage layout. </success_criteria>

After completion, create `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`