[yw0nam]

Summary

The SessionStart hook keeps completed handoffs off the list that invites continuing work. in_progress and blocked handoffs stay under the "ask to continue one" header; completed ones become one counted line.

GET /messages?purpose=handoff&scope=<repo>&limit=100        (was limit=10)
        │
        ▼
format_handoffs(rows)
  ├─ status != completed → at most HANDOFF_LIMIT (10) lines under HANDOFF_HEADER
  └─ status == completed → counted, never listed
        │
        ▼
Memory: pending handoffs for this repo. Nothing is claimed; ask to continue one to claim it.
- 2026-10-21  stuck work  (status: blocked, id: …)
- 2026-10-21  open work  (status: in_progress, id: …)
Memory: completed handoffs delivered for this repo: 12. Claim one to read it; list_messages names their ids.

The hook fetches up to the server's /messages maximum (100) before it splits, so completed handoffs never push open ones out of the ten shown. The hook still never claims. Plugin version 0.2.0 → 0.3.0. The plugin README row and docs/data-flow.md describe the new block.

Owner decision: completed handoffs go on a separate line rather than out of the block.

Review notes:

• Two-axis review (standards, spec), a fix round, and a final two-axis review. The first review found that slicing ten rows before the split let completed handoffs crowd out open ones; the fix round fetches 100 and caps only the open lines.
• Not changed: past 100 pending handoffs in one repo scope the count and the open list stop at what was fetched. A new snapshot supersedes the pending one with the same subject, so a scope rarely holds that many.
• Not changed: HANDOFF_HEADER still says "pending", which is the server's term for unclaimed.

Related issues

Closes #385

Runtime evidence (required for ingest / retrieval / serving behavior)

The hook's run_hook against the real REST app and the throwaway Postgres container (a temporary integration test, not committed). It seeded 12 completed, 1 in_progress, and 1 blocked handoff in one repo scope:

<memory-context>
Memory: your directions could not be fetched.

Session: claude_code evidence (pass it as session_id with origin claude_code when a note is distilled from this session)

Memory: pending handoffs for this repo. Nothing is claimed; ask to continue one to claim it.
- 2026-10-21  stuck work  (status: blocked, id: bb197be5-bdc4-415c-86b4-093aa6f17e23)
- 2026-10-21  open work  (status: in_progress, id: 44908038-20b4-44eb-a81c-a721cb7cffd8)
Memory: completed handoffs delivered for this repo: 12. Claim one to read it; list_messages names their ids.
</memory-context>
still pending after the hook: 14

(The card line fails because the throwaway DB has no claude-code entity.)

RED before each fix: 2 failed at 4074d85 (completed rows printed as - … (status: completed …)), 4 failed at 718e714 (ValueError: '<HANDOFF_HEADER>' is not in list for 12 completed + 1 open).

Verification

• uv run pytest passes — tests/integrations unit: 161 passed
• uv run ruff format --check . and uv run ruff check . pass
• docker compose build mcp passes (Dockerfile / dependency changes) — N/A, no dependency change
• Runtime evidence attached above, or N/A justified

Checklist (core principles)

• Selective storage — notes stay distilled; verbatim text lives only in doc_rows and the turns lane
• Source-specific logic stays out of the source-agnostic core (ingest pipeline, retrieval, serving)
• No hardcoded endpoints/models — configuration lives in .env
• New/changed behavior ships a test in this PR (or skip-tests label justified)