Decide how a Turn's history grows mid-Turn in the Run Projection and headless --json

[Sandstorm831]

Question

How does the Run Projection carry a Turn whose history grows while it runs, instead of one replaceable preview, so assistant text settles in place and durable rows arrive mid-Turn? Decide message identity, which rows become durable when, how Steer state, Turn duration and the interrupted mark, Entry Turn authorship, and Agent-call rows reach the Projection, and which of these facts headless gains within its frozen --json shapes.

Also settle per-call live command preview budgets and coalescing, retention of supplied partial output when a Turn is interrupted or lost, reconciliation with final native output, placement of Turn-scoped cumulative diffs, and exposure of reported-only context and usage. Keep terminal facts distinct from replaceable previews and command panels bounded by default.

[Sandstorm831]

Starting context

Input	Why it matters	Authority
Decide the Harness Seam's tool, command, diff, and reasoning-summary events — resolution	Fixes identified typed tool facts, bounded optional native command previews, unconfirmed outcomes, supplied call/Turn diffs, inherited summary settings and reported-only context. Retention, final reconciliation and headless exposure are delegated here	Canonical
ADR 0038	Accepted semantic tool, command-preview, diff, summary and reported-context contract, with ownership and the explicit hand-off to this decision	Canonical
ADR 0036 and ADR 0024	Appending transcript, ten-line shell collapse, one row changing in place, deep shared Projection Port, and distinct durable/live/preview data	Canonical; read Thought duration and context with the accepted amendment above
Run lifecycle glossary, ADR 0033, ADR 0034, and ADR 0035	Turn, Entry Turn, Agent call, Model choice, Steer delivery/dropping, and Interrupt settlement semantics that the Projection must carry	Canonical
Projection Interface, live overlay, and Run Projection	Current scalar preview/activity lane, state-bound generation, transcript references and durable timeline derivation; identify what changes behind the Port	Canonical (current behaviour)
Turn drive and event recording, Turn records, and live Run control	Three admitted Turn writes, current durable tool-event append, live-only previews and delayed durable fan-out; prevents persisting each output chunk by accident	Canonical (current behaviour and invariants)
Headless guidance, Run commands, and headless parity	Frozen JSON shapes, transcript page/export references, existing live approval follower, and deliberate parity gaps	Canonical
Module design, topology, and Application guidance	Keep native interpretation below the Harness Seam, per-call reconciliation in Application, canonical writes with their owner, and clients behind the shared Port	Canonical
OpenCode tool output and lifecycle and T3 Code tool output and lifecycle	Source-pinned investigations of bounded live shell previews, identified lifecycle updates, coalescing and unknown outcomes; source and existing tests inspected, not live qualification runs	Research

Required methods

• /grilling and /domain-modeling.
• /codebase-design for Projection ownership and Interface shape.

Reading rule

Read the accepted Harness-event resolution first, then ADR 0036's transcript/truncation paragraphs and ADR 0024's shared Port invariants. Compare the current Projection Interface, event recorder and live overlay before opening implementation details. Read the glossary/ADR paragraphs only for the Steer, Entry Turn, duration/model and Agent-call fields being decided, then the frozen headless contract.

ADR 0038, ADR 0036's clarifications and the extended source notes are pinned above at the human's signed, GitHub-verified commit. The documentation PR is merged into main at merge commit 16fb18e; the human-approved resolution remains the decision record.

This is a planning decision. Set the retention/coalescing budget for per-call previews, preservation of supplied partial output when a Turn is interrupted or lost, reconciliation with final native output, publication of durable rows during a Turn, Turn-scoped cumulative diff placement, and exposure through current headless shapes. Preserve the agreed ten-line default command panel and native-only facts. Do not reopen Harness summary settings, infer tool success from Turn success, derive context percentages, or implement the feature here.

[Sandstorm831]

Resolution

The human agreed the decisions below in a grilling session. They resolve how a Turn's history is stored, identified, bounded, and read; production implementation stays in the milestone loop.

The contract is recorded in ADR 0039: Grow a Turn's history in place through a per-Session history Projection, with amendments to ADR 0024 and ADR 0036, a note in Application guidance, and new rows in headless parity. The documentation PR is merged into main at merge commit 10f7412.

Storage and identity

1. When rows are stored: at item start and at settle, never per chunk. Tool calls, Agent calls, and Steers get a start row; text and Thoughts are stored when they settle. Every stored row reaches open clients during the Turn through the existing admitted appendTurnEvent, so there are still three admitted Turn writes and the Turn's durable history no longer waits for publishAttempt.
2. Identity: opaque, Turn-scoped item identity from the Adapter (text, Thoughts, tool calls) and from Secant (Steers, Agent calls). The Projection issues its own opaque row id at the Port; the Seam's id never reaches a client. A row keeps the position where its item first appeared. Checked against /codebase-design: opacity like RecoveryCoordinate, native correlation stays in each Adapter (deletion test), two real Adapters plus the fake.
3. Steer: stored when sent; becomes delivered, not delivered (Interrupt), or delivery not confirmed (lost Turn).
4. Agent call: one row carrying the call and reason, then Secant's reply (accepted / held for review / refused), then applied or not applied when the Turn ends (ADR 0032).
5. Interrupt: streaming text and Thoughts are stored as they stand, marked incomplete; a running command keeps its last retained preview labelled "live output, may be incomplete", outcome unconfirmed.
6. Lost Turn: start rows remain unconfirmed; in-flight live text is gone. No repair, no periodic saving.
7. One record: transcript_entry retires. The Turn's input is its first row, settleTurn stops appending a final assistant copy, transcript pages and exports are built from Turn rows, and previous-release databases migrate at open.

Output, diffs, and Turn facts

8. Budget: each call retains the last 30,000 characters of output, live and stored alike (OpenCode's shell preview), with a Secant omission marker distinct from any Harness truncation. Live previews coalesce to at most one push per 50 ms per Run; terminal facts never coalesce.
9. Reconciliation: supplied final output replaces the preview without appending; no final output keeps the labelled preview; failure or decline shows the error with any preview below.
10. Turn diff: one row collapsed to changed files with lines added/removed, expanding to the full diff; per-call patches are not cut (ADR 0036 amended).
11. Closing line: duration = settled − admitted (Secant's own times), none for lost/not-started; interrupted or lost from the result kind; effective model else requested (ADR 0034); Turn origin shown, so the Entry Turn reads that Secant started the Step.
12. Context and usage: live only, replaced per report, never stored, not in headless.

Projection Port and Workbench

13. History family: a new per-Session openProjection family (ADR 0024 amended). Stored changes arrive as the whole page through durable, so clients never reduce stored rows; one new live variant carries a single row's preview. The Application owns reconciliation, coalescing, stale-preview removal, and liveness. The run family's Run-wide preview/activity strings and the preview update kind retire; RunView.timeline keeps its frozen shape.
14. Window: the Workbench holds a Session's newest 200 rows, as OpenCode holds its newest 100 messages. Nothing older loads; a row that falls off the top is no longer shown or updated; the top reads that earlier conversation is not shown. The whole conversation opens on demand from the details panel's existing Session transcript entry, for live and previous Runs alike (ADR 0036 amended). Paging older rows into the Workbench was rejected for the render and memory cost.

Headless

15. No live stream: headless stays stored-only; mid-Turn stored rows make polling show progress.
16. Additive fields: run read --transcript --json entries keep session, role, content and gain optional kind (message / Steer / Entry prompt), turn, steer, incomplete; they list each settled assistant message. run show --json is unchanged. Live history, waiting Steers, tool/Thought/diff/Agent-call rows, and context/usage are recorded headless parity gaps.

Investigation assets: OpenCode source at local commit 228e909 — shell preview MAX_METADATA_LENGTH = 30_000 (packages/opencode/src/tool/shell.ts:27, 220-223), 100-message window with oldest-drop and no older loading (packages/tui/src/context/sync.tsx:341-350, 603), a new assistant message per loop step (packages/opencode/src/session/prompt.ts:1186-1201), and dropped-message updates ignored or orphaned (sync.tsx:378-402). T3 Code's 50 ms live coalescing window (ThreadLiveEventCoalescer.ts:18-19, local de251fc). Source inspected, not executed.

Unknowns carried to implementation (none block this decision): Claude shell exit-code shape still needs native fixture qualification; whether Claude Code's direct stream supplies live command output is unverified (optional per ADR 0038); stable per-text-block identity from Claude Code is assumed and should be qualified on a recording (the Adapter mints one otherwise); Claude Code's final result versus its last text block is unverified and no longer matters once the duplicate record retires.

Hand-off: no new decision tickets or fog surface. Approve the second pre-public-release Amendment: the decided redesigns stays blocked by Decide how typed commands work in the Run Workbench compose; nothing is newly unblocked.