Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach)

[serge-ivo]

Rescoped 2026-08-06. #247 has since shipped — the vestigial tmux naming is gone (engineLabel replaces tmuxSession across the API surface). So the "or finish removing the naming" half of this is done, and what remains is the single question: should tmux come back as a selectable engine backend? Everything below still applies to that question.

Direction check: the proposal below adds backend: "stream-json" | "tmux" — a new closed enum on engine presets — while #160 is explicitly about retiring closed enums (capabilities.workflow) in favour of declarative composition. If tmux does come back, it should probably arrive the declarative way rather than as one more hardcoded alternative.

---

First, the thing that is easy to conflate

tmux is already a platform connector and always has been. lib/connectors/registry.ts:82
declares tmux (tmux_list_sessions, tmux_capture_pane, tmux_run_command), and :72 declares
the generic terminal connector, whose local adapters are tmux, kitty remote control and iTerm2
AppleScript. Both are live, both reach the machine over the runner relay, and the tmux / Terminal /
kitty / iTerm2 Operator agents use them today.

So this ticket is not "add tmux to the platform". It is: restore a tmux-backed engine for
Coder sessions, as a selectable alternative to the stream-json child process — the thing that was
deleted.

What was removed, and when

Commit c94642f, 2026-06-26 — "feat(coding): drive Claude Code via stream-json — one structured
engine, no tmux". It deleted packages/browser-runner/src/coding/session.ts (180 lines) and
session.test.ts (110 lines), and pointed CodingRuntime at the new HeadlessSession.

The deleted CodingSession implemented the same surface CodingRuntime still expects:

method	tmux implementation
start()	createSession(name, workDir), export env vars via sendText, then sendText(cliCommand)
snapshot(lines)	capturePane(target, lines)
input(text)	sendText
interrupt() / stop()	send keys / killSession
runState()	inferred by regex over the captured pane

Every tmux primitive it relied on still exists and is still maintained —
coding/tmux.ts was kept for the terminal connector (createSession, capturePane, sendText,
sendKey, killSession, sessionExists, sanitizeSessionName). So the restore is mostly
re-adding one class, not rebuilding a subsystem.

CodingRuntime.start() (runtime.ts:126) currently constructs new HeadlessSession({…})
unconditionally — no flag, no branch. That single call site is where a backend choice would go.

What the removal traded away, and what has since changed

That commit stated its trade-offs explicitly:

Trade-offs (deliberate): drops the multi-CLI tmux path (gemini/codex/grok) and live-TTY
takeover — both replaced by structured messaging, which fits headless.

One of those has already been reversed by other means: multi-CLI came back. Codex, Grok and
Gemini now run through HeadlessSession as raw spawns with stdout capture (headless.ts, mode: "raw"), so "tmux is needed for non-Claude engines" is no longer true.

What is still genuinely missing without tmux:

• A real PTY. Raw-spawn engines get a pipe, not a TTY. A CLI that requires a terminal (full-screen
  TUI, prompts that need isatty, colour/width detection) cannot work on the current path.
• Live human takeover of the actual terminal — attaching to the same session the agent is driving.
• tmux attach from the user's own machine to watch or intervene directly. Users currently
  expect this, because every session still shows a pags-<engine>-<id> name (Coding sessions no longer use tmux, but the names, diagnostics, kill-tmux control and docs all still say they do #247).
• Survival of a runner crash for non-Claude engines. Claude survives via --resume from
  ~/.claude; a raw spawn dies with the runner, where a tmux session would outlive it.

What it would cost

Honest accounting, since this is re-adding something that was deliberately deleted:

• A second engine implementation to maintain behind one interface, and every coding feature must
  then work on both.
• Run-state goes back to regex over a scraped pane for that backend — the guessing the commit
  message called out, and the source of the premature-finish bugs it fixed.
• The console's terminal view, /capture, takeover, the Pilot loop and the orphan reconciler all
  need to be correct for both backends.

Proposal

• Add backend: "stream-json" | "tmux" to the engine preset (CodingEngine in
  lib/coding-engines.ts, alongside the existing auth field), defaulting to stream-json so
  nothing changes for anyone who does not opt in.
• Restore CodingSession from c94642f behind the CodingRuntime interface and branch at
  runtime.ts:126 on the session's chosen backend.
• Make the runtime kind visible per session (Show which credential a coding session actually used (subscription vs per-token API key) and what the engine really is #248) — a tmux-backed session should say so, and show
  a name you can genuinely tmux attach to.
• Resolve the vestigial naming either way (Coding sessions no longer use tmux, but the names, diagnostics, kill-tmux control and docs all still say they do #247): today the label promises tmux and delivers a pipe.

Decide before building. The value case is a real PTY, real attach, and surviving a runner crash
for non-Claude engines. If those are not wanted, the better outcome is to finish #247 — drop the
tmux naming entirely — rather than carry two engines. This ticket exists to make that a decision
rather than an accident of history.

[serge-ivo]

An A/B is now set up to inform this — with a caveat that limits what it can prove

Two instances, same repository (~/dev/heartfull/platform), different drivers:

• f8ddc272-0390-4826-8812-94989e3d2ebd — Heartfull, Repo Coder: Pilot → Claude Code as a
  child process over stream-json.
• cda75e28-cace-4958-ac3e-6a7528e6b719 — Heartfull (tmux), a tmux Operator instance with
  instructions to drive claude in a tmux session on the same checkout.

What it cannot show: that tmux is cheaper. Same binary, same repo, same context — the
transport does not change what is sent to the API. And the tmux side is completely unmetered
(#348), so it will appear far cheaper by producing no engine rows at all. Any cost conclusion
drawn before #348 lands is an artefact.

What it can show, and is worth measuring: the two differ in who decides when to send the next
turn, and turn count against a long-lived session is the dominant cost driver — the incident in
#343 was 17 turns at ~790K cache-read tokens each.

• The Repo Coder's Pilot fires autonomously, iteration after iteration.
• The tmux Operator has workflow: null — no Pilot — so it sends a turn when its chat reasoning
  decides to.

So the honest framing of this experiment is autonomous Pilot cadence vs chat-driven cadence,
with tmux incidental. That is still a real question about Coder's cost profile, and both sides'
driver spend (BYOK Claude, real money) is fully metered today — it is only the engine half that
is blind on tmux.

Two asymmetries to keep in mind when reading the result:

• The tmux Operator carries a captured pane in context on every turn, which is its own
  ongoing cost and has no equivalent on the stream-json side.
• It has no merge_policy enforcement (migration 0091 applies to coder-repo settings only).
  It is a rule in its instructions instead, which is weaker. Relevant to this ticket beyond cost:
  a tmux backend would need the enforced guards ported, not re-stated as prose.

Suggested sequence: land #348 item 1 (label unmetered rather than showing zero), then run both
against the same objective, then decide here.

[serge-ivo]

Decision memo: no tmux backend for Coder — the two gaps it is standing in for are cheaper to close directly

Recommendation: no. Not "not yet" — the value case as written mostly evaporates on contact with
the current code, and the part that survives is better served by a change to one function than by a
second engine implementation. Below is what a PTY actually buys, what tmux specifically costs (which
is not the same question), and the two things I would build instead.

---

1. What a real PTY + attach actually buys

Three of the four claims in the ticket no longer hold, and the two that do are not PTY-shaped.

"A CLI that requires a terminal cannot work on the current path" — true of the interactive form
of every engine, and already answered. coding-engines.ts:234-246 states the rule and
DEFAULT_ENGINES (:253-267) implements it: codex exec --sandbox danger-full-access,
gemini --approval-mode yolo --skip-trust --prompt, grok --permission-mode bypassPermissions -p,
ollama run llama3. Every mainstream coding CLI ships a non-interactive mode because CI needs one.
To justify a PTY on this ground, someone has to name a CLI a real user wants that has none. I could
not.

"Survival of a runner crash for non-Claude engines" — real, and small. Claude resumes from
~/.claude (headless.ts:44-45, readState/writeState :798-813); a raw engine is one-shot
(:296-314), so a crash costs the turn in flight, not the session. The Pilot is a durable Workflow
and the working tree is on disk. This is minutes, not work.

What genuinely is missing, and neither is fixed by tmux specifically:

• No keystroke path at all. headless.ts:469-471: key() writes
  [ignored keypress … — this session has no terminal attached] into the transcript. The route
  accepts {kind:"keys"} (routes/coding.ts:449-456) and CodingRuntime.takeoverInput forwards it
  (runtime.ts:295-299) — the whole path exists and dead-ends in a no-op. So a takeover can send
  text, never Escape, an arrow, or a y. That is the one honest PTY-shaped gap in the tree.
• Raw engines have no multi-turn memory. runOneShot spawns [...cmdArgs, text] fresh per turn
  (headless.ts:412-417); only Claude gets --resume (buildClaudeArgs:748). So the Pilot's step 7
  instruction reaches a codex process with no recollection of steps 1-6. This is the biggest real
  capability gap on the raw path — and it is a preset string, not an architecture. headless.ts:398-411
  fixes the contract as "the preset command is a prefix, the turn text is the final argument", so an
  engine that offers a resume subcommand gets continuity by editing one text field. No code, no PTY.

tmux attach from the user's own machine is the remaining want, and it is a duplication question,
not a capability one — see §4.

---

2. What it costs — and PTY ≠ tmux

The removal rationale was that scraping a pane makes idle a guess. A PTY does not reintroduce
that; tmux does, by construction. They are separate axes and the old implementation coupled them.
A PTY is an fd — structured output still parses through it. tmux is a screen buffer: the only way
back out is capture-pane -p -S -N -J, ANSI-stripped (coding/tmux.ts:145-148), i.e. post-render
text. You cannot recover a byte stream from tmux. So "structured output plus a PTY" is coherent;
"structured output plus tmux" is not, usefully.

The scraping machinery is still in the tree and provably dead — handlers.ts isReady /
isProcessing / extractResponse / completion have exactly one importer, and it reads
.cliCommand (headless.ts:215). A tmux backend makes pane.includes("ctrl+c to interrupt")
(handlers.ts:66) load-bearing again: a string in a vendor's TUI, one release away from silence.

But the real cost is everything built since June that exists only because the engine is a child
process:

• Metering (Coding Engine spend is invisible in the usage ledger — the largest real cost isn't recorded #267). engine-metering.ts opens with it: recordEngineUsage is fed from exactly
  one source, the stream-json result event (headless.ts:568). [bug] Coding CLIs driven through the terminal connector are completely unmetered — a tmux run reads as $0, not as unknown #348 closed by labelling
  pane-driven work unmetered rather than pretending it was free. A tmux backend puts the flagship
  product's engine back in that category.
• The acts audit (A delegated run records its outcome but not its consequential acts — merging to main is invisible #294). noteAct/settleAct (headless.ts:596-613) read tool_use and
  tool_result blocks. A pane has neither. Run 73ffc073 — the unattended merge to main that
  subordinate_status reported as "done" — becomes invisible again exactly where supervision reads
  it.
• Credential transparency (Show which credential a coding session actually used (subscription vs per-token API key) and what the engine really is #248), and a leak. engine-auth.ts:63-67 derives the resolved
  credential from the same merged env spawn uses, presence-only, never a value (:15-16). The
  deleted CodingSession injected env by typing it into the pane — a sendText of
  export KEY="value" followed by Enter (c94642f^:coding/session.ts:56-65). That
  puts ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN into scrollback that capturePane ships to
  the cloud, into coding_timeline, and into the Pilot's own decision prompt — coding-loop.ts:259
  renders the pane straight into it. Restoring the class as it stood is a credential leak into D1 and
  a model context. Fixable, but it is not "re-adding one class".

---

3. Which engines need it — and the fix they actually need

Claude does not: structured, persistent, metered, audited. So the question reduces to codex / grok /
gemini / ollama, and for those the right fix is not a PTY, it is deleting a heuristic.

headless.ts:262-289 infers idle for raw mode with three rules: output then 1.5s quiet; no output
and 8s elapsed; 15-minute backstop. But a raw engine is one-shot, and its close handler already
sets run = "idle" (:443-457). Process exit is an exact turn boundary — so rule 1 can only ever
fire early. The codebase already knows the consequence; it is written down in a test comment
(headless.test.ts:412-419): "a long build gets judged idle and the brain sends turn 2 while turn 1
is still running." And runOneShot:422-428 kills the in-flight process when the next turn arrives —
correctly, given the alternative is two engines editing one repo. Net effect on codex today: a >1.5s
quiet spell mid-turn (a test run, an install, a slow network fetch) can get the working turn killed
and replaced with the next instruction. That is the premature-finish bug the tmux removal claimed to
end, alive and well on the raw path.

A PTY changes how bytes arrive. It does not tell you when a turn ended. Rule 1 is a leftover from the
era when raw engines were persistent; making exit authoritative and demoting the quiet rule to a
long backstop is a few lines in one function, with the exit path already wired.

---

4. The duplication question

tmux is already a shipped product surface twice over: the tmux connector's six tools
(workers/api/src/lib/connectors/tmux.ts:34-185) and the generic terminal connector across
tmux/kitty/iTerm2 (coding/terminal.ts:34-214). A tmux Coder backend would be a third consumer of
the same coding/tmux.ts primitives, carrying its own consent model (connector writes gate on
instance_connector_consent, migration 0051; a coding session does not) and its own metering story
(noteUnmeteredDrive vs the usage ledger). One mechanism, three governance regimes.

And "watch it work in my own terminal, then take over" is already shipped — it is the Operator agent,
which is what the A/B in this thread is running against the same checkout. This platform's standing
preference is one path per capability: loopDriverFor as the single dispatcher, matchesWhere as
one predicate language for filters and routing, capability as data rather than scattered
conditionals. backend: "stream-json" | "tmux" is one more closed enum, proposed while #160 is
retiring the last one.

The strongest counter-argument, stated fairly: the Operator path is the ungoverned one. It has
no merge_policy enforcement (migration 0091 binds to coder-repo settings; the Operator restates
the rule as prose in its instructions), and its drives are recorded as unmetered by construction. So
"use the Operator agent if you want attach" currently means "use the path with no merge authority and
no ledger". If attach genuinely matters to users, the honest response is to carry the guards to the
Operator agent — not to carry a second engine into Coder.

---

5. Recommendation, and what I would deliberately not build

No tmux backend. Not backend: "stream-json" | "tmux", not a restored CodingSession, not a
second implementation behind the CodingRuntime interface. Every coding feature would then have to
be correct twice, and three of them (usage, acts, resolved credential) cannot be correct at all on
the pane side.

Smallest slices worth building, in order:

1. Make process exit authoritative for one-shot engines (headless.ts:262-289). Demote the 1.5s
   quiet rule to a backstop measured in tens of seconds. This fixes the actual premature-finish bug
   that people would otherwise attribute to "no PTY", and it is the cheapest item here.
2. Continuity as configuration. Change the raw defaults to their resume form where the CLI offers
   one, and document that the preset is a prefix. Zero code.
3. Resolve key() one way or the other. Either the console stops offering keystrokes, or the
   runner stops accepting them silently. Today the route takes them and headless.ts:471 writes them
   into a transcript nobody treats as an error.

If 1-3 leave a real user genuinely stuck, the thing to reach for is a PTY inside HeadlessSession
(node-pty), not tmux — it keeps the spawn env, the usage drain, the act parsing and the resolved
credential, and it is the only option that gives keystrokes without giving up measurement.

What would change my mind: a named CLI a paying user wants that has no non-interactive mode; or
evidence that "attach in my own terminal" is a repeated ask that the Operator agent cannot satisfy.
The second is more likely than the first — and if it lands, the fix is to govern the Operator path,
not to reopen this one.

---

Two housekeeping notes found while reading, both harmless: runtime.ts:12 still describes "live
tmux coding sessions" and :90 "the tmux analogue" — the exact two lines flagged in #247's comment
and missed by the cleanup. And handlers.ts's pane heuristics (isReady/isProcessing/
extractResponse/completion) are unreferenced; only cliCommand is read.

[serge-ivo]

Decision: no. And the ground under the question moved today — three of the memo's own conditions have been met, which settles it rather than deferring it.

The decision memo above argued "no" against main @ d0e4095. I re-verified every load-bearing claim
against main @ 64598dd and against live production state. The memo's recommendation survives, and
one of its three "build this instead" items has shipped. What follows is what changed, what the
remaining gap actually is, and the ADR I would record so this does not have to be re-litigated.

---

What shipped since the memo, all of it today

1. The memo's item 1 is done — #391 (1aa1722). Process exit is now authoritative for one-shot
engines. headless.ts:309-324:

runState(): "idle" | "thinking" | "responding" {
    if (!this.alive) return "idle";
    // A ONE-SHOT engine's turn IS a process, so its exit is an exact end-of-turn signal and no
    // timer may pre-empt it (#391). …
    if (this.oneShot) return this.procAlive ? "thinking" : "idle";

This is the fix that matters most to the value case, because "my codex turn gets killed halfway
through a build" is the symptom a user would most plausibly attribute to "no real terminal". It was
never PTY-shaped, and it is gone.

2. The pane-scraping machinery has been deleted, not merely left unreferenced. The same commit
gutted handlers.ts — isReady / isProcessing / extractResponse / completion are no longer in
the tree, and the file says why:

"They died with the tmux backend (commit c94642f) … keeping them left a live-looking
pane.includes("ctrl+c to interrupt") one vendor release away from being silently wrong — for
anyone who wired it back up believing it worked."

This changes the cost estimate in the original proposal. "Restore CodingSession from c94642f
behind the CodingRuntime interface" is no longer re-adding one class: the run-state layer it
depended on has been removed on purpose, so a tmux backend now means writing new TUI string
matchers from scratch, for four CLIs, and owning them against every vendor release. The two
housekeeping items the memo flagged (runtime.ts's stale "live tmux coding sessions" comments) are
also cleaned — grep -n tmux runtime.ts now returns one line, and it says "NOT tmux panes".

3. #402/#404 gave the operator path a real, enforced ceiling (f3df811, d8eb4f8). A creator
declares capabilities.surfaceOptions.terminal.backends, a subscriber may narrow it and never widen
it (connectorConstraintsForInstance, agent-capabilities.ts:561-582), and runRegistryTool refuses
an out-of-scope backend or a target carrying an out-of-scope prefix before any handler runs.
Verified live: iterm-operator and kitty-operator each carry backends: ["iterm2"] / ["kitty"]
on the agent row.

4. #348's unmetered label now has a number, and it is small. usage_summary(range:"all") returns
unmetered: { drives: 2, aiCliDrives: 0, instances: 1, lastAt: 2026-08-08 03:40 UTC, windowDays: 14 }.
So over the last fortnight, the entire ungoverned-cost exposure of the operator path is two drives on
one instance. That is a real answer to "how much are we flying blind", and it argues against building
anything large to fix it.

---

The value case, re-tested against today's code

claim in the ticket	status now
"A CLI that requires a terminal cannot work on the current path"	Still unsubstantiated. DEFAULT_ENGINES (coding-engines.ts:253-267) ships a non-interactive form for every engine: codex exec --sandbox danger-full-access, gemini --approval-mode yolo --skip-trust --prompt, grok --permission-mode bypassPermissions -p, ollama run llama3. To justify a PTY someone must name a CLI a paying user wants that has none. Nobody has.
"Run-state is a guess for raw engines"	Fixed by #391, not by a PTY.
"Multi-CLI needs tmux"	Already false — raw spawns cover codex/grok/gemini/ollama.
"Survival of a runner crash"	Real and small: a one-shot turn dies, the working tree is on disk, the Pilot is a durable Workflow. Minutes.
Keystrokes	The one genuine PTY-shaped gap, and it is unchanged. headless.ts:555-556: key(keys) { this.push(\[ignored keypress ${keys.slice(0,40)} — this session has no terminal attached]`); }— whileroutes/coding.tsaccepts{kind:"keys"}andruntime.ts:332forwards it. A takeover can send text; it can never send Escape, an arrow, or ay`.

The cost, re-verified — and PTY is still not tmux

Three subsystems built since June exist only because the engine is a child process emitting
structured events, and none of them can be recovered from a screen buffer:

• Metering (Coding Engine spend is invisible in the usage ledger — the largest real cost isn't recorded #267). parseEngineUsage is fed from exactly one place: the stream-json result
  event (headless.ts:654-656). A pane carries rendered text.
• The acts audit (A delegated run records its outcome but not its consequential acts — merging to main is invisible #294). noteAct/settleAct read tool_use / tool_result blocks
  (headless.ts:635-645), and the code states the boundary itself: "This path (and noteAct) is
  reachable ONLY from the structured stream-json handling above" (:699-703). Without it, the
  unattended merge that subordinate_status reported as "done" becomes invisible again exactly where
  supervision reads it.
• Merge authority (migration 0091). readMergePolicyForRun is a step inside
  CodingSessionWorkflow (workflows/coding-session.ts:84) and the breach record is written from the
  same act stream. Two mechanisms, one dependency.

And the credential hazard is not hypothetical — it is what the deleted class actually did
(git show c94642f^:packages/browser-runner/src/coding/session.ts, start()):

for (const [k, v] of Object.entries(this.config.env)) {
    sendText(this.target, `export ${k}=${JSON.stringify(v)}`);
    sendKey(this.target, "Enter");
}

snapshot() on the next line is capturePane(this.target, lines), which the cloud persists to
coding_timeline and renders straight into the Pilot's decision prompt (coding-loop.ts). Restoring
the class as it stood puts ANTHROPIC_API_KEY into D1 and into a model context. Fixable — and the
fact that the obvious restore is a credential leak is precisely why this should be written down rather
than remembered.

The distinction the ticket blurs, restated because it is the crux: a PTY is a file descriptor —
structured output still parses through it. tmux is a screen buffer: the only way out is
capture-pane -p -S -N -J, ANSI-stripped. You cannot recover a byte stream from tmux. "Structured
output plus a PTY" is coherent. "Structured output plus tmux" is not.

---

The governance argument has flipped, and it flipped toward "no"

The memo's fairest counter-argument was: "use the Operator agent if you want attach" currently means
"use the path with no merge authority and no ledger". One of those two is now closed. #402/#404
gave the operator family a creator-declared, dispatch-enforced ceiling on which backend it may touch —
so an operator is a tmux agent by construction, not by name.

But closing it exposed a gap that this decision creates the obligation to fix, and it is the shape this
board keeps producing: two individually-correct decisions composing into a hole.

• [chore] The tmux, kitty and iTerm2 Operators are one agent wearing three names — declare backend-exclusive tools (no code) #403 (correct) moved the published tmux-operator off the generic terminal_* six and onto the
  six backend-exclusive tmux_* tools. Verified live — its capabilities.tools is exactly
  tmux_list_sessions … tmux_kill_session.
• [design] A "tmux Operator" can drive iTerm2 — a creator cannot declare which backend an agent may touch, or that it owns exactly one terminal #402/[design] Capability constraints — declare what an agent may PASS, and enforce it at the tool boundary #404 (correct) put the ceiling in CONNECTOR_CONSTRAINTS — which has exactly one key,
  and says so (lib/surface-options.ts:185-210): "terminal is the first and, today, only entry."

So targets: "single" plus a subscriber-bound target — the part of #402 written for exactly this case
("a named operator ('Heartfull tmux') should be targets: "single". One pane, one job. A
mis-selected target here is a shell command on a real machine") — can be declared on the three
drafted operators and not on the one that is published. Verified live: tmux-operator carries no
surfaceOptions at all, tmux_run_command is scope: "write" arbitrary shell
(connectors/tmux.ts:79-82), and it is gated by one per-connector consent row that also legitimises
its read-only siblings. Two live instances (tmux Operator, Heartfull (tmux)), neither bound.

That is what to build instead of a tmux Coder backend. Add a tmux entry to
CONNECTOR_CONSTRAINTS with a targets binding on the session argument. It is one table entry in a
reviewed table, it reuses narrowConstraintSpec and the dispatch gate unchanged, and it closes the
governance objection to "use the Operator for attach" without carrying a second engine into Coder.

---

Recommendation

No tmux backend for Coder. Not backend: "stream-json" | "tmux", not a restored CodingSession,
not a second implementation behind CodingRuntime. Close #249 as decided.

Build instead, cheapest first:

1. A tmux entry in CONNECTOR_CONSTRAINTS with a targets binding (§above). Closes the real
   governance gap and is the smallest item here. Needs an issue — I have not filed one.
2. Resolve key() one way or the other. Either the console stops offering keystrokes, or the
   runner stops accepting them into a transcript nobody treats as an error. This is the memo's item 3,
   still open, still unfiled. If keystrokes are genuinely wanted, the answer is node-pty inside
   HeadlessSession, which keeps the spawn env, the usage drain, the act parsing and the resolved
   credential — not tmux, which gives up all four.
3. Continuity as configuration. codex exec is one-shot per turn, so the Pilot's step 7
   instruction reaches a process with no memory of steps 1–6. headless.ts fixes the contract as
   "preset command is a prefix, turn text is the final argument", so an engine offering a resume
   subcommand gets continuity by editing one text field. Zero code. Memo item 2, still open.
4. Update [docs] "Can I use tmux for coding?" has no correct answer in the docs — the architecture split is documented, the user-facing choice and its unmetered cost are not #433's doc table to say the split is settled, and point at the ADR below rather than at
   an open decision. [docs] "Can I use tmux for coding?" has no correct answer in the docs — the architecture split is documented, the user-facing choice and its unmetered cost are not #433 explicitly asks for a reference to Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach) #249 "so the split reads as a live
   decision rather than a settled boundary" — once this closes, that line should invert.

What would change my mind: a named CLI a paying user wants that has no non-interactive mode; or
evidence that "attach in my own terminal" is a repeated ask the Operator family cannot satisfy once
item 1 lands. The second is far likelier than the first, and its fix is still to govern the Operator
path, not to reopen this one.

On the A/B in this thread: it can now be read, because #348 landed — but read it as autonomous
Pilot cadence vs chat-driven cadence, with tmux incidental, exactly as the earlier comment warned.
Live: Heartfull (Repo Coder) 9 calls, Heartfull (tmux) 27 calls, and total unmetered drives across
the whole account is 2 in 14 days. There is not enough signal there to overturn anything, and it does
not need to.

---

Proposed ADR 0002 — full text, ready to commit at platform/docs/adr/0002-a-coder-engine-reports-its-own-turns.md

This clears all three of the README's bars. It is a constraint (it forbids a backend class); someone
reading only runtime.ts:185 would violate it (one call site, one interface, and coding/tmux.ts is
still in the tree with a full set of live primitives); and the violation fails no type-check and no
test — a tmux backend satisfies CodingRuntime structurally, and metering, acts and merge authority
would simply produce nothing, which reads as "quiet" rather than "broken". That is the same failure
mode ADR 0001 exists to prevent.

# ADR 0002 — A Coder engine reports its own turns

**Status:** Accepted (2026-08-08) · **Owner decision** · Supersedes nothing.

## Context

Coder drives a coding CLI on the user's machine. Until 2026-06-26 it did so through tmux: the CLI ran
in a pane, `capture-pane` scraped the rendered text, and every question the platform had — is the turn
over, what did it just do, what did it cost — was answered by matching strings the vendor prints in
its TUI. Commit `c94642f` replaced that with a child process driven over Claude Code's structured
`stream-json` interface, where a `result` event ends a turn as a fact.

Three subsystems were then built **on top of that structure**, each answering a question the pane
could not:

- **Usage (#267)** — `parseEngineUsage` reads the `result` event's own token and cost figures. A pane
  carries rendered text; a dollar figure scraped from it would be a guess dressed as a measurement.
- **Consequential acts (#294)** — `noteAct`/`settleAct` read `tool_use` and `tool_result` blocks. This
  exists because run `73ffc073` merged its own PRs to `main` unattended while `subordinate_status`
  reported "done": the delegation model rests on a supervisor being able to review what a subordinate
  did, and without an act record all it can review is the claim.
- **Merge authority (migration 0091)** — `readMergePolicyForRun` runs inside `CodingSessionWorkflow`
  and its breach record is written from that same act stream.

In 2026-08, #249 proposed bringing tmux back as a *selectable* engine backend, for a real PTY,
`tmux attach`, and crash survival. Assessing it produced three findings that are the reason for this
record:

1. The strongest evidence for the proposal — one-shot engines being judged idle and killed mid-turn —
   was **not PTY-shaped**. It was a timer written for a persistent CLI, applied to a process whose exit
   is exact. Fixed in #391 by deleting the timer, not by adding a terminal.
2. **A PTY is not tmux.** A PTY is a file descriptor and structured output parses straight through it.
   tmux is a screen buffer whose only exit is `capture-pane`, i.e. post-render text. The original
   proposal coupled two things that are separable, and only one of them costs anything.
3. The restore is **smaller-looking than it is**. `coding/tmux.ts` is still maintained for the terminal
   connector, `CodingRuntime` is an interface, and `runtime.ts:185` is a single call site — so
   "restore one class" reads as a contained change. It is not: the deleted class injected credentials
   by typing `export KEY="value"` into the pane it later captured and shipped to D1 and into the
   Pilot's prompt.

## Decision

**Every engine backend Coder drives must report its own turns.** Concretely, four rules. A change that
violates any of them is a regression regardless of what it enables.

**E1 — The turn boundary is an event, not an inference.** A backend must signal end-of-turn from the
engine itself: a structured completion event, or process exit for a one-shot engine. A backend whose
idle state is derived by matching text against rendered output is not admissible. Timers are a
backstop against a wedged process, never the primary signal.

**E2 — Usage and consequential acts come from the same stream as the work.** A backend must be able to
report per-turn token/cost usage and `tool_use`/`tool_result`-equivalent act records. A backend that
cannot is one where spend and irreversible actions are structurally invisible — and a missing row on a
page of dollars reads as zero dollars, not as unknown.

**E3 — A credential reaches an engine through the process environment, and nowhere its own output
capture can read.** No backend may place a secret anywhere that its snapshot, transcript or scrollback
can subsequently carry.

**E4 — If a real PTY is required, it goes inside `HeadlessSession`.** `node-pty` preserves E1–E3: the
spawn env, the usage drain, the act parser and the resolved-credential derivation all continue to
work. tmux is not the mechanism for a PTY on this platform.

**Scope.** This governs Coder sessions — `CodingRuntime`, `HeadlessSession`, the Pilot and the Co-pilot.
It does **not** govern the terminal connector family (tmux / kitty / iTerm2 Operators), which is a
different product with a different contract: it drives a pane the user already has, its writes are
recorded as explicitly unmetered (`recordUnmeteredEngineActivity`, #348), and its boundary is a
creator-declared backend ceiling enforced at dispatch (#402/#404). "Watch it work in my own terminal
and take over" is served there, deliberately.

## Consequences

**What this costs.**

- **No `tmux attach` to a Coder session.** A user who wants a pane they can attach to uses an Operator
  agent, and accepts that its drives are unmetered by construction.
- **No keystrokes in a Coder takeover.** `HeadlessSession.key()` is a no-op today. Under E4 the fix is
  node-pty; under no reading of this ADR is the fix tmux. Until then, takeover sends text only, and
  that limitation should be stated in the UI rather than silently swallowed.
- **A one-shot engine loses the turn in flight if the runner dies.** Claude resumes from `~/.claude`;
  a raw engine does not. The working tree is on disk and the Pilot is durable, so the loss is a turn,
  not a session.
- **Multi-turn memory for raw engines is a preset string, not a backend property.** `headless.ts` fixes
  the contract as "preset command is a prefix, turn text is the final argument", so an engine offering
  a resume subcommand gains continuity by editing one text field.

**What it buys.** Every Coder run has a cost row, an act record and an enforceable merge policy, on
every engine, without a second implementation to keep correct. Every coding feature has to be right
once.

## Enforcement

- **What would catch a violation:** nothing automatic today, which is why this ADR exists. A backend
  satisfying `CodingRuntime` type-checks; metering, acts and merge authority degrade to silence rather
  than to failure.
- **The check to add with any second backend:** a runtime assertion that a started session's backend
  reports a usage record and an act record within its first completed turn, and a test that fails when
  a backend is registered without them.
- **The review question, for any change touching `runtime.ts` engine construction, `handlers.ts`, or
  anything importing `coding/tmux.ts` outside `terminal.ts`:** *does this path produce a `result`-class
  event, a usage record, and an act record?* If any answer is no, it is a violation of this ADR and not
  a design choice.
- `coding/tmux.ts` has exactly one production importer — `coding/terminal.ts`. A second one is the
  signal to re-read this record.

## References

#249 (this decision) · #391 (turn boundary) · #402/#404 (operator backend ceiling) · #267 (usage) ·
#294 (acts) · #348 (unmetered labelling) · #247 (naming) · `c94642f` (the removal) · #433 (the docs
that should now describe this split as settled).

Regression risk of closing this

Closing #249 "no" removes a live escape hatch from the record, so the risk is that the four things it
was standing in for get forgotten. Items 1–3 in my recommendation are the mitigation and none of them
is filed — the target binding, key(), and raw-engine continuity all need issues before this closes,
or the ADR becomes the only place they are written down and it is not a backlog.

Verified by reading main @ 64598dd and by live MCP reads. Not verified: I did not start a coding
session, drive an engine, or run a tmux operator — each spends the owner's tokens or writes production
data.