---
phase: 05-mvp-deployment
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
  - adapter/matrix/files.py
  - sdk/real.py
  - tests/adapter/matrix/test_files.py
  - tests/platform/test_real.py
autonomous: true
requirements:
  - PH05-04
must_haves:
  truths:
    - "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."
  artifacts:
    - path: "adapter/matrix/files.py"
      provides: "Room-safe shared-volume path building and path resolution"
    - path: "sdk/real.py"
      provides: "Attachment path passthrough and send-file normalization"
    - path: "tests/adapter/matrix/test_files.py"
      provides: "Regression coverage for shared-volume path construction"
  key_links:
    - from: "adapter/matrix/files.py"
      to: "sdk/real.py"
      via: "relative `workspace_path` transport"
      pattern: "workspace_path"
    - from: "sdk/real.py"
      to: "adapter/matrix/bot.py"
      via: "OutgoingMessage attachments rendered back to Matrix"
      pattern: "MsgEventSendFile"
---

<objective>
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.
</objective>

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

<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

<interfaces>
From `adapter/matrix/files.py`:

```python
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`:

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

@staticmethod
def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: ...
```
</interfaces>
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Add shared-volume file contract tests for `/agents` deployment</name>
  <files>tests/adapter/matrix/test_files.py, tests/platform/test_real.py</files>
  <read_first>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</read_first>
  <behavior>
    - 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).
  </behavior>
  <acceptance_criteria>
    - `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 `<verify>` exercises both inbound and outbound sides of the shared-volume contract.
  </acceptance_criteria>
  <action>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.</action>
  <verify>
    <automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v</automated>
  </verify>
  <done>Phase 05 has direct test coverage for `/agents`-backed shared-volume behavior across inbound and outbound file paths.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Tighten attachment path handling for the shared volume contract</name>
  <files>adapter/matrix/files.py, sdk/real.py</files>
  <read_first>adapter/matrix/files.py, sdk/real.py, tests/adapter/matrix/test_files.py, tests/platform/test_real.py, docs/deploy-architecture.md</read_first>
  <behavior>
    - 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.
  </behavior>
  <acceptance_criteria>
    - `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.
  </acceptance_criteria>
  <action>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.</action>
  <verify>
    <automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v</automated>
  </verify>
  <done>Incoming and outgoing file references stay compatible with the real shared-volume deployment contract, and the targeted file/path regressions pass.</done>
</task>

</tasks>

<verification>
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.
</verification>

<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>

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