---
phase: 05-mvp-deployment
plan: 03
subsystem: infra
tags: [matrix, attachments, shared-volume, agents, pytest]
requires:
  - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
    provides: direct AgentApi integration and Matrix outgoing file rendering
provides:
  - 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
affects: [matrix, deployment, shared-volume, file-transfer]
tech-stack:
  added: []
  patterns: [relative workspace_path transport, shared-volume root normalization]
key-files:
  created: []
  modified:
    - tests/adapter/matrix/test_files.py
    - tests/platform/test_real.py
    - sdk/real.py
key-decisions:
  - "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."
patterns-established:
  - "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."
requirements-completed: [PH05-04]
duration: 3 min
completed: 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*