Execution Log: GET /api/v1/sessions/transcript

Append-only log for issue-209. Ticket: #209.

How this session ran the loop

One cloud session, one pass, no human at the other end — the same posture as issue-208 and issue-211, with the same two consequences a reviewer should hold:

1. phase-selection was not run as a gate. The session was started by the ticket itself; there was nobody to tick the checklist. Phases assumed: the full spec chain, verification, self-review. brainstorming and the opt-in design-critic-review were not taken — the ticket already states the route, the derivation and the open design questions (tail shape, redaction), and no second model was available.
2. The chain was authored before the code, but approved by nobody. The artifacts are a proposal to ratify, not a locked chain; status: draft on all four says so.

Phase transitions

Phase	Entered	Reviewed/approved by	Notes
phase-selection	2026-08-12	—	Not run as a gate; see above
requirements-definition	2026-08-12		requirements.md — 4 requirements, 4 NFRs, 5 abuse cases. Risk tier 3: no schema/sensitive path, but the service's first file-contents route — the read boundary is R2, negatively tested
design	2026-08-12		design.md — one core function, one route, one MCP tool, the UI wiring; the deliberate absences (no CLI verb, no redaction, no Cursor, no streaming)
test-planning	2026-08-12		testing-plan.md — 8 rows in scope, 7 n/a with reasons
tasks-breakdown	2026-08-12		tasks.md — 7 tasks
implementation	2026-08-12		Built. Tasks 1–6 complete
verification	2026-08-12		Testing plan executed: every activity but T11 (needs a human, a workstation, tmux and a spawned session). 1872 tests pass (+23 new); 55 UI tests; lint, format, types, markdown and the UI build clean
needs-review	2026-08-12		Handed to the PR

Pull requests

PR	Scope / tasks	Status
claude/github-issue-209-gkexqr	the whole work item	open, awaiting human approval

Progress entries

2026-08-12 — the shape of the change

Read the seams before writing anything. Three findings shaped the design:

• The UI already wrote the contract — including a bug. issue-207's transcriptPath derives the path with a run-collapsing regex ([^a-zA-Z0-9]+ → one -), but Claude Code's own layout munges per character (verified against a real installation: /home/user/the-loop → -home-user-the-loop; consecutive non-alphanumerics each become a -). The server derives per-character, and R4.4 fixes the UI to match rather than shipping two spellings of one path.
• The registry's endpoint model gives PR transcripts for free. The trace panel's tabs already select PR endpoints; resolving via endpoint_for over the record (closed included, R1.4) serves them with no extra machinery.
• This is the plane's first file-contents route. Everything else on /api/v1 serves records the service itself wrote. That is why R2 spells out the fail-closed boundary (id validation before any filesystem touch, resolve-then-containment, *.jsonl under the projects root only) instead of treating the read as just another lookup.

One scope call, recorded for the reviewer: the ticket lists the UI as the motivation ("becomes live once a route exists") but does not mandate UI work. The same honesty rule as issue-208 applies — the panel's copy says "not served by /api/v1", which this change makes false — so the minimal wiring is in scope as R4 and flagged in the PR briefing as strike-able.

Documentation

Doc	Change
docs/capabilities/control-plane.md	Current behaviour: the transcript read and its fail-closed boundary; the "one disabled surface" note closed out; issue-209 history row
docs/api-specs/openapi/the-loop.v1.yaml	/api/v1/sessions/transcript (sessionTranscript) — the /api/docs page is generated from this
ui/README.md	§ Not yet served rewritten: every approved surface is now served; the section records the pattern historically
docs/decisions/decision-079.md	New — the fail-closed file boundary, and the four deliberate absences (CLI verb, redaction, Cursor, streaming)

README.md, SKILL.md and the CLI docs are untouched: no command, config key or workflow changed; the route is documented where the API is documented (the generated /api/docs and the capability doc).

Capability docs

control-plane.md — updated in this PR (see the table above). No other capability's behaviour changed.

Verification results

In testing-plan.md § Verification results, with evidence in evidence/verification.md.

Review cycles

Cycle	Type (self/critic/security)	Reviewer	Outcome	Link
1	self	the-loop (this session)	new finding — a pull-request endpoint is linked before its first dispatch assigns it a conversation (issue-172), so its empty session id hit the "not a derivable file name" refusal, which misdescribes a perfectly normal state as a bad record. Split into its own 404 ("the session id is assigned on first dispatch"), with a test	core/sessions.py, test_core_sessions.py
2	self	the-loop (this session)	new finding — useAsync keeps stale data across dependency changes and errors, and the trace panel rendered data first: switching trace tabs could draw the previous tab's transcript under the new tab's label until the fetch settled. Reordered to loading → fresh data (!error) → fallback, with the ordering constraint written at the render site	WorkItemDetail.tsx
3	self	the-loop (this session)	requirements trace re-walked (R1–R4 each mechanism → test) — one gap: R3.2's tool registration was asserted nowhere; session_transcript added to the MCP tools-list subset assertion. Docs-altitude sweep for "no transcript route"/"not served" found only historical specs, which stay as written (deltas, not state)	test_mcp_integration.py
4	critic	—	not run. reviews.critics is empty in this repo's harness config and no second harness was available to this session
5	security	—	mechanism-level review against the requirements' 5 abuse cases (each has a mechanism and a negative test — see design.md § Security design); risk tier 3, so no named human sign-off is mandated. The one judgement a human should confirm: this is the plane's first file-contents route, and its containment (id validation → single-segment munge → resolve-then-contain) is the entire boundary between "serves transcripts" and "serves files"	requirements.md § Security considerations