polygram 0.10.0-rc.2 → 0.10.0-rc.21

package/lib/process/tmux-process.js

@@ -40,6 +40,29 @@ const { LogTail } = require('../tmux/log-tail');
 const { sessionLogPath, pipeToParser } = require('../tmux/session-log-parser');
 const { computeCostUsd } = require('../model-costs');
 const { getTopicConfig } = require('../session-key');
+const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
+const { verifyPinnedClaudeBin } = require('../claude-bin');
+const { createAsyncLock } = require('../async-lock');
+
+// ─── Pinned claude CLI version ───────────────────────────────────────
+//
+// The tmux backend reads claude CLI INTERNAL artefacts (JSONL events,
+// queue-operation semantics, TUI banner ASCII art, READY hint
+// strings, MULTILINE_SEPARATOR convention, stop_reason values). None
+// of these are a stable public contract — they can change in any
+// new CLI version. The rc.7→rc.15 saga (May 2026) is direct
+// evidence: every rc shipped fixes for behaviour that drifted in the
+// CLI without polygram logic changing.
+//
+// So polygram pins ONE specific CLI version. Production daemon must
+// run that exact version. Upgrading the pin is a SEPARATE, deliberate
+// process — see AGENTS.md "Pinned claude CLI version" for the full
+// procedure (read release notes → bump → run all spikes → diff
+// JSONL → 24h staging on shumorobot → roll to umi-assistant).
+//
+// Bumping this constant WITHOUT following that procedure is how the
+// rc.7→rc.15 saga got triggered. Don't.
+const CLAUDE_CLI_PINNED_VERSION = '2.1.142';
 
 // Context window per model. All Claude 4.x models are 200k. If
 // Anthropic ships a model with a different window, promote this to
@@ -53,36 +76,91 @@ const DEFAULT_CONTEXT_WINDOW = 200_000;
 // for the next prompt. Under `--permission-mode acceptEdits` (our
 // default), the bottom-of-pane indicator can also read "accept edits
 // on" instead; treat either as ready.
-const READY_HINTS_RE    = /\?\s+for shortcuts|accept edits on/;
+// claude TUI shows a different ready hint depending on permission
+// mode:
+//   - default:           "? for shortcuts"
+//   - acceptEdits:       "accept edits on"
+//   - bypassPermissions: "bypass permissions on (shift+tab to cycle)"
+// All three are valid ready states. Polygram production uses
+// 'default', but the spike harness + tests exercising
+// bypassPermissions need the third matcher (caught by the rc.14
+// autosteer-tui-real.mjs spike).
+const READY_HINTS_RE    = /\?\s+for shortcuts|accept edits on|bypass permissions on/;
 const STREAMING_HINT_RE = /esc to interrupt/;
 
+// L1 fix (spike leftover): the claude TUI shows its welcome banner
+// WITH a ready hint at the bottom during startup — before the user's
+// prompt has been processed:
+//
+//    ▐▛███▜▌   Claude Code v2.1.142
+//   ▝▜█████▛▘  Sonnet 4.6 with low effort · Claude Max
+//     ▘▘ ▝▝    ~/Projects/shumkov/polygram
+//   ...
+//   ? for shortcuts                  ← ready hint already present
+//
+// _awaitTurnComplete's poll sees the ready hint and resolves
+// captureCompleteP. If the agent hasn't emitted any text yet,
+// _extractTurnReply returns the banner text → pm.send returns the
+// banner as result.text → polygram delivers the banner as a Telegram
+// reply. Caught in the 50-scenario spike's baseline-tool-call.
+//
+// Distinctive banner marker — the box-drawing characters in the
+// claude logo. Polygram's prompts / agents never legitimately
+// contain these. While these characters appear in the pane,
+// treat the TUI as NOT YET ready regardless of READY_HINTS_RE.
+const TUI_BANNER_RE = /▐▛███▜▌|▝▜█████▛▘/;
+
 // TUI approval-prompt indicators. When a chat is spawned WITHOUT
 // --permission-mode acceptEdits, claude pauses on risky tools and
 // draws a prompt like:
 //
 //   ⏺ Bash(rm foo.txt)
 //     ⎿  Do you want to do this?
-//          1. Yes
+//        ❯ 1. Yes
 //          2. Yes, allow always for similar commands
 //          3. No, and tell Claude what to do differently
 //
+// The TUI renders a `❯` selection cursor inline before the
+// highlighted option (always option 1 at first paint). Earlier
+// rc.1-rc.4 regex assumed no inline cursor and silently failed to
+// match every approval-gated tool call in production, hanging the
+// session in the TUI until orphan-sweep killed it (see
+// tests/tmux-process-approval.test.js inline-cursor regression).
+//
 // SECURITY (audit H1 fix): require BOTH the question text AND a
 // following numbered menu line ("1. ...") so a malicious assistant
 // message text like "Do you want to proceed?" can't trigger a fake
 // approval card by itself. The menu is part of the TUI's pause
 // state; the assistant can't render it without actually being paused.
-const APPROVAL_PROMPT_RE = /Do you want to (?:proceed|do this|continue)\??[\s\S]{0,400}?(?:^|\n)\s*1\.\s+/im;
+// The optional `❯` cursor in [^\S\n]*(?:❯[^\S\n]+)?1\. is still
+// bounded to the line containing `1.`, so the security property
+// holds — only a real menu line satisfies it.
+const APPROVAL_PROMPT_RE = /Do you want to (?:proceed|do this|continue)\??[\s\S]{0,400}?(?:^|\n)[^\S\n]*(?:❯[^\S\n]+)?1\.\s+/im;
 // Pull the tool name + raw arg snippet from the line preceding the
 // approval prompt. Capture-pane preserves the ⏺ marker.
 const TOOL_INVOCATION_RE = /⏺\s+([A-Za-z_]\w*)\s*\((.*?)\)\s*$/m;
 
 // ─── Defaults — overridable per construction for tests ───────────────
 
-const DEFAULT_READY_TIMEOUT_MS = 30_000;
+// Cold-spawn budget for claude TUI to reach "? for shortcuts" / "accept
+// edits on" state. 30s was enough in dev (interactive shell, warm
+// keychain) but consistently timed out under launchd in production:
+// MCP server starts each have a 30s connection timeout, and the
+// keychain/Aqua context warm-up is slower outside an attached terminal.
+// 120s is generous; the only cost is waiting longer when something is
+// genuinely stuck (we kill + retry in that case anyway).
+const DEFAULT_READY_TIMEOUT_MS = 120_000;
 const DEFAULT_TURN_TIMEOUT_MS  = 5 * 60_000;
 const DEFAULT_POLL_MS          = 250;
 const DEFAULT_QUIESCE_MS       = 500; // require READY for this long before declaring done
 
+// R7: sentinel returned by _awaitTurnComplete when its poll loop is
+// stopped by the caller's absolute-deadline abort (rather than by a
+// real READY quiescence or its own internal timeout). _runTurn maps
+// this to "the capture race did not win" — the absolute turnDeadlineP
+// reject is what fails the turn.
+const ABORT_SENTINEL = Symbol('tmux-await-turn-aborted');
+
 class TmuxProcess extends Process {
   /**
    * @param {object} opts
@@ -111,6 +189,7 @@ class TmuxProcess extends Process {
     lateGraceMs = 1500,
     queueCap = 50,   // P0.1 parity: SDK enforces queueCap=50 too
     pollScheduler = null,   // O1 optimization: shared cross-process tick
+    pasteConfirmMs = 2500,  // Phase 3 §5: paste-gating JSONL-confirm timeout
   } = {}) {
     super({ sessionKey, chatId, threadId, label });
     if (!runner) throw new TypeError('TmuxProcess: runner required');
@@ -149,6 +228,67 @@ class TmuxProcess extends Process {
     // getContextUsage() so polygram's post-turn auto-hint works on
     // the tmux backend just like SDK.
     this._lastUsage = null;
+
+    // ─── 0.10.0 Phase 2: correlation token + turn ledger ──────────
+    //
+    // The four legacy accumulators (_turnState / pendingQueue /
+    // _pendingAutosteers / _extraTurnState) were four partial
+    // projections of ONE missing object: an ordered ledger of turns,
+    // each with a stable id, an owning msgId set, and a state.
+    // Attribution used to be RECONSTRUCTED by content-matching JSONL
+    // — lossy under paste concatenation, substring collisions, and
+    // event reorder. It is now RECORDED: every paste embeds a unique
+    // correlation token in its <polygram-info> block; the JSONL
+    // user-message reproduces the token verbatim; routing is an exact
+    // token→Turn lookup.
+    //
+    // `_ledger` — every Turn, append-ordered. A Turn:
+    //   { turnId, token, msgIds:[], kind:'primary'|'autosteer',
+    //     state:'queued'|'pasted'|'streaming'|'done'|'failed',
+    //     text, toolUses, toolUsedThisTurn, stopReason, resultEvent,
+    //     context, opts, prompt, startedAt, via,
+    //     resolve/reject (primary send() promise),
+    //     settleResult/resultPromise (internal turn-done signal) }
+    //
+    // `pendingQueue` (from the base Process) is kept as the external
+    // contract surface — lib/sdk/callbacks.js reads
+    // pendingQueue[0].context.{streamer,reactor}. It holds the SAME
+    // primary Turn objects as `_ledger`, head-first; `_ledger` is the
+    // authority, `pendingQueue` its primary-only projection.
+    this._ledger = [];
+    this._turnSeq = 0;
+    // The turns currently receiving assistant events. Driven purely
+    // by `user-message` token matches — never by "which accumulator
+    // is non-null". A group with >1 turn is an explicit fold.
+    // `primaryTurnId` records the turnId of the primary turn that owns
+    // this group (null for a NEW-TURN autosteer group, which has no
+    // primary). R11: `_finishTurn` uses it to retire ONLY the group
+    // its finishing primary owns — never a fresh NEW-TURN autosteer
+    // group that started after that primary already flushed.
+    this._activeGroup = {
+      turns: [], text: '', pendingSteerCausesNewBubble: false,
+      primaryTurnId: null,
+    };
+    // Turns whose paste the TUI has parked in its input queue
+    // (`queue-operation enqueue`), oldest first — a FIFO mirror of the
+    // TUI's own queue. `remove`/`dequeue` are bare (no token), so they
+    // are resolved positionally; the list must therefore mirror EVERY
+    // queued paste, primary OR autosteer (R2 — a primary paste that
+    // gets queued must be tracked too, or the FIFO desyncs). A `remove`
+    // folds the head autosteer into the running turn; a `dequeue`
+    // releases the head to run as a fresh turn (its user-message
+    // follows and _routeUserMessage handles it).
+    this._enqueuedTurns = [];
+
+    // ─── 0.10.0 Phase 3 §5: paste gating ──────────────────────────
+    // A paste does not release the next paste until the JSONL tail
+    // confirms it landed (its token surfaced in a user-message /
+    // queue-operation), bounded by `pasteConfirmMs`. Converts the
+    // 50ms post-Enter drain guess into a real barrier — two pastes
+    // can no longer concatenate into one TUI input.
+    this._pasteLock = createAsyncLock();
+    this._pasteConfirms = new Map();   // token → resolve fn
+    this.pasteConfirmMs = pasteConfirmMs;
   }
 
   get cost() { return 3; }
@@ -216,31 +356,93 @@ class TmuxProcess extends Process {
       }
       args.push('--debug-file', this.debugLogPath);
       if (agent) args.push('--agent', agent);
+      // Cross-backend parity: SDK appends polygram's Telegram display
+      // hint to every agent's systemPrompt (lib/sdk/build-options.js).
+      // Without this, the spawned claude session has no idea it's
+      // replying through a Telegram bot — shumorobot 2026-05-15 caught
+      // the model emitting shell-style canned strings ("No response
+      // requested.") as actual Telegram replies for that reason.
+      // `--append-system-prompt` is preserved by claude CLI in
+      // addition to (not in place of) the agent's own prompt.
+      args.push('--append-system-prompt', POLYGRAM_DISPLAY_HINT);
+
+      // Pin: spawn the ABSOLUTE pinned-version binary, never the
+      // bare `claude` on $PATH. The claude CLI auto-updater
+      // re-points the ~/.local/bin/claude symlink whenever a new
+      // version lands, so a $PATH spawn silently drifts off the
+      // pinned version the tmux backend was validated against
+      // (shumorobot 2026-05-16: CLI drifted 2.1.142 → 2.1.143
+      // between deploys). The versioned binary at
+      // ~/.local/share/claude/versions/<v> is immutable — the
+      // updater only adds new files, never overwrites.
+      const binCheck = verifyPinnedClaudeBin(CLAUDE_CLI_PINNED_VERSION);
+      if (!binCheck.ok) {
+        throw Object.assign(new Error(binCheck.reason), { code: 'CLAUDE_BIN_MISSING' });
+      }
 
       // R2-F8: spawn errors must fail loud, not silent-catch.
       await this.runner.spawn({
         name: this.tmuxName,
         cwd,
-        command: 'claude',
+        command: binCheck.path,
         args,
         envExtras: ctx.envExtras || {},
       });
 
-      // v9: tail the per-session JSONL file (the REAL structured-event
-      // channel — v9 probe showed --debug-file emits only infra noise).
-      // Path is deterministic once we have cwd + sessionId. The file
-      // may not exist for ~100ms after spawn; LogTail tolerates ENOENT.
-      this._cwd = cwd;
-      this._armSessionLogTail({ resuming: Boolean(ctx.existingSessionId) });
-
-      // G6 — block until TUI is responsive.
-      await this._waitForReady();
-      this.emit('init', {
-        session_id: this.claudeSessionId,
-        label: this.label,
-        backend: 'tmux',
-        tmux_name: this.tmuxName,
-      });
+      // SPAWN-LIFECYCLE FIX (shumorobot 2026-05-17 22:03, topic :3):
+      // `spawn()` resolving means the tmux session NAME now exists on
+      // the host. From here on, ANY failure — readiness timeout, a
+      // wedged capture-pane, an `init` listener throwing — must tear
+      // that session down before propagating, or the orphan lingers
+      // and every retry's `tmux new-session -s <same-name>` fails
+      // "duplicate session". A transient first-spawn failure would
+      // otherwise become a PERMANENT wedge for the chat/topic until a
+      // human kills the orphan. `_sessionCreated` is the seam that
+      // distinguishes "spawn() itself failed (no session — nothing to
+      // kill)" from "session created, a later step failed (must
+      // kill)". This is a spawn-lifecycle bug, independent of the
+      // turn-ledger concurrency rewrite.
+      const sessionCreated = true;
+
+      try {
+        // v9: tail the per-session JSONL file (the REAL structured-
+        // event channel — v9 probe showed --debug-file emits only
+        // infra noise). Path is deterministic once we have cwd +
+        // sessionId. The file may not exist for ~100ms after spawn;
+        // LogTail tolerates ENOENT.
+        this._cwd = cwd;
+        this._armSessionLogTail({ resuming: Boolean(ctx.existingSessionId) });
+
+        // G6 — block until TUI is responsive.
+        await this._waitForReady();
+        this.emit('init', {
+          session_id: this.claudeSessionId,
+          label: this.label,
+          backend: 'tmux',
+          tmux_name: this.tmuxName,
+        });
+      } catch (err) {
+        // Post-spawn failure — the session exists but is unusable.
+        // Kill it so a retry gets a clean name. Best-effort: the
+        // runner's killSession already swallows its own errors, but
+        // guard anyway so a kill failure can never mask the real
+        // spawn error. Also tear down the just-armed JSONL tail so it
+        // doesn't leak a watcher against a dead session.
+        if (sessionCreated) {
+          if (this._sessionLogTail) {
+            try { this._sessionLogTail.close(); } catch { /* swallow */ }
+            this._sessionLogTail = null;
+          }
+          try {
+            await this.runner.killSession(this.tmuxName);
+          } catch (killErr) {
+            this.logger.warn?.(
+              `[${this.label}] start() cleanup killSession failed: ${killErr.message}`,
+            );
+          }
+        }
+        throw err;
+      }
     })();
 
     try {
@@ -277,143 +479,216 @@ class TmuxProcess extends Process {
       // Match SdkProcess contract: send() on closed Process REJECTS
       // rather than returning an error result. Callers (polygram
       // dispatch) already wrap pm.send in try/catch for this case.
-      // Runtime turn errors (paste fail, timeout) still surface as
-      // an error-shaped PmSendResult — that's the other path below.
       throw Object.assign(new Error('No process for session'), { code: 'PROCESS_CLOSED' });
     }
-    // P0.1 fix: enforce queueCap (parity with SDK). Without this a
-    // misbehaving caller could grow pendingQueue unbounded.
+    // queueCap parity with SDK — bound the ledger's queued primaries.
     if (this.inFlight && this.pendingQueue.length >= this.queueCap) {
       throw Object.assign(
         new Error(`queue overflow: queueCap ${this.queueCap}`),
         { code: 'QUEUE_OVERFLOW' },
       );
     }
-    if (this.inFlight) {
-      // For Phase 2 MVP we serialize: queue the prompt locally and
-      // await the in-flight turn. Include `context` so polygram's
-      // streamer/reactor lookups via pendingQueue[N].context work
-      // when this pending becomes the head.
-      return new Promise((resolve, reject) => {
-        this.pendingQueue.push({
-          prompt, opts,
-          context: opts.context || {},
-          resolve, reject,
-        });
-      });
-    }
 
-    this.inFlight = true;
-    const turnTimeoutMs = opts.timeoutMs || this.turnTimeoutMs;
-    const startedAt = this._now();
-
-    // P0.1 fix: push a HEAD pending with the caller's `context` so
-    // polygram's onStreamChunk / onToolUse / onAssistantMessageStart
-    // callbacks (which read entry.pendingQueue[0].context.streamer
-    // and entry.pendingQueue[0].context.reactor) work for tmux too.
-    // Without this, live bubble updates and reactor heartbeats
-    // silently no-op on tmux. Shape mirrors SdkProcess pendings.
-    const headPending = {
-      prompt, opts,
+    // Register a primary Turn. Its correlation token is embedded into
+    // the paste; the JSONL `user-message` reproduces it verbatim; the
+    // event router then attributes by exact token lookup.
+    const turn = this._makeTurn({
+      kind: 'primary',
+      prompt: String(prompt ?? ''),
+      opts,
       context: opts.context || {},
-      streamText: '',
-    };
-    this.pendingQueue.unshift(headPending);
-
-    // v9: prime turn-scoped event collection. Assistant chunks and
-    // tool-uses arriving via the JSONL tail accumulate into _turnState;
-    // the 'result' event resolves the turn.
-    this._turnState = {
-      text: '',
-      toolUses: 0,
-      resolveResult: null,
-      resultEvent: null,
-      pendingSteerCausesNewBubble: false,
-    };
-    const turnResultP = new Promise((resolve) => {
-      this._turnState.resolveResult = resolve;
+      msgIds: opts.context && opts.context.sourceMsgId != null
+        ? [opts.context.sourceMsgId] : [],
+    });
+    turn.callerPromise = new Promise((resolve, reject) => {
+      turn.resolve = resolve;
+      turn.reject = reject;
     });
+    this._ledger.push(turn);
+    // pendingQueue holds primary Turn objects head-first — it is the
+    // external contract surface (lib/sdk/callbacks.js reads
+    // pendingQueue[0].context.{streamer,reactor}). The running turn
+    // is always pendingQueue[0].
+    this.pendingQueue.push(turn);
+    if (this.pendingQueue[0] === turn) {
+      // Nothing ahead — run immediately. (Not awaited; _runTurn
+      // settles turn.callerPromise and drains the next queued turn.)
+      this._runTurn(turn);
+    }
+    // else: queued. _finishTurn() runs it when the head completes.
+    return turn.callerPromise;
+  }
+
+  /**
+   * Run one primary Turn end-to-end: embed its token, paste, race the
+   * JSONL terminal `result` against capture-pane quiescence, build the
+   * PmSendResult, settle the caller, and drain the next queued turn.
+   */
+  async _runTurn(turn) {
+    this.inFlight = true;
+    turn.state = 'pasted';
+    turn.startedAt = this._now();
+    const turnTimeoutMs = turn.opts.timeoutMs || this.turnTimeoutMs;
+    // Internal turn-done signal — settled by _flushActiveGroup when
+    // this turn's group is flushed on a terminal `result`.
+    turn.resultPromise = new Promise((resolve) => { turn.settleResult = resolve; });
 
     try {
-      // R2-F1: sanitization happens inside runner.pasteText; we also
-      // log when chars get stripped.
-      const result = await this.runner.pasteText(this.tmuxName, prompt);
+      // rc.13.1: pasteAndEnter holds a per-session async lock around
+      // paste + Enter so a concurrent injectUserMessage paste cannot
+      // interleave keystrokes with this primary prompt.
+      const result = await this._pasteAndEnter(this._embedToken(turn.prompt, turn.token));
       if (result.stripped > 0) {
         this.logger.warn?.(
           `[${this.label}] stripped ${result.stripped} control chars from prompt`,
         );
         this.emit('prompt-sanitized', { stripped: result.stripped, source: 'send' });
       }
-      await this.runner.sendControl(this.tmuxName, 'Enter');
 
-      // Race: JSONL result event vs capture-pane quiescence fallback
-      // vs hard timeout. JSONL is the primary signal (carries structured
-      // text); capture-pane wins for old claude versions or if JSONL
-      // file write lags behind UI quiescence.
-      const captureAtStart = await this.runner.captureWide(this.tmuxName);
+      // R7: an ABSOLUTE timeout wrapping the whole race. The
+      // capture-pane completion detector re-checks its deadline only
+      // BETWEEN `captureWide` subprocess calls — if a single `tmux
+      // capture-pane` wedges (its promise never resolves), the poll
+      // loop is parked on the await and neither the capture-complete
+      // promise nor the JSONL `resultPromise` ever settle, so `send()`
+      // hangs forever and starves the turn queue.
+      //
+      // One setTimeout drives two things: an `abortP` (resolves — fed
+      // to _awaitTurnComplete so its poll loop can break out of a
+      // wedged capture and release the scheduler), and a
+      // `turnDeadlineP` (rejects — the third racer below, guaranteeing
+      // _runTurn ALWAYS settles within turnTimeoutMs). `unref` so the
+      // timer never keeps the process alive on its own; cleared in the
+      // `finally` so a turn that ends early leaves no dangling timer.
+      let turnDeadlineTimer = null;
+      let signalAbort = null;
+      const abortP = new Promise((resolve) => { signalAbort = resolve; });
+      const turnDeadlineP = new Promise((_resolve, reject) => {
+        turnDeadlineTimer = setTimeout(() => {
+          signalAbort();
+          reject(Object.assign(
+            new Error('TmuxProcess: turn did not complete in time'),
+            { code: 'TMUX_TURN_TIMEOUT', tmuxName: this.tmuxName },
+          ));
+        }, turnTimeoutMs);
+        turnDeadlineTimer.unref?.();
+      });
+
+      // Race: JSONL terminal result vs capture-pane quiescence vs the
+      // hard turn timeout. 0.10.0 Phase 4 §6: JSONL is the SOLE source
+      // of reply text. capture-pane is a LIVENESS signal only — it
+      // detects "the turn is done" so we never wait forever for a
+      // `result` that never arrives, but it NEVER delivers text.
       const captureCompleteP = this._awaitTurnComplete({
-        captureAtStart, timeoutMs: turnTimeoutMs,
+        timeoutMs: turnTimeoutMs, abortP,
       });
+      // The capture-pane loop may end via the absolute-deadline abort
+      // (it returns the abort sentinel). Swallow that branch — the
+      // turnDeadlineP reject below is what actually fails the turn.
+      const captureRaceP = captureCompleteP.then((buf) => (
+        buf === ABORT_SENTINEL ? new Promise(() => {}) : { kind: 'capture' }
+      ));
 
-      // Whichever resolves first wins.
       let resolvedVia = 'jsonl';
-      const winner = await Promise.race([
-        turnResultP.then((ev) => ({ kind: 'jsonl', ev })),
-        captureCompleteP.then((cap) => ({ kind: 'capture', cap })),
-      ]);
+      let winner;
+      try {
+        winner = await Promise.race([
+          turn.resultPromise.then((ev) => ({ kind: 'jsonl', ev })),
+          captureRaceP,
+          turnDeadlineP,
+        ]);
+
+        // If capture-pane won but the turn used a tool, the agent is
+        // still working — the "ready" hint was a transient idle between
+        // tool calls. Wait for the real terminal result from JSONL, but
+        // keep the absolute deadline armed so a JSONL `result` that
+        // never arrives still fails the turn rather than hanging it.
+        if (winner.kind === 'capture' && turn.toolUsedThisTurn) {
+          winner = await Promise.race([
+            turn.resultPromise.then((ev) => ({ kind: 'jsonl', ev })),
+            turnDeadlineP,
+          ]);
+        }
+      } finally {
+        if (turnDeadlineTimer) clearTimeout(turnDeadlineTimer);
+        // Ensure the capture-pane loop is released even when the JSONL
+        // race won — otherwise it would poll on until its own internal
+        // deadline (and, with a shared PollScheduler, hold a refcount).
+        signalAbort();
+      }
 
       let text;
       let resultSubtype = 'success';
       let stopReason = null;
       if (winner.kind === 'jsonl') {
-        text = this._turnState.text || winner.ev.text || '';
+        text = turn.text || winner.ev.text || '';
         resultSubtype = winner.ev.subtype || 'success';
         stopReason = winner.ev.stopReason || null;
-        // Update sessionId from the result if claude assigned a fresh one
         if (winner.ev.sessionId) this.claudeSessionId = winner.ev.sessionId;
+        // R10: a genuinely-empty terminal `result` — end_turn, no
+        // reply text, AND no tool ran this turn — is the agent
+        // producing literally nothing (a thinking-only terminal
+        // message). Pre-fix this resolved as { error:null, text:'' },
+        // a silent empty SUCCESS, and polygram delivered the canned
+        // "No response generated." apology classified as a successful
+        // turn. Match the §6 fail-loud contract (capture-won/no-JSONL
+        // also fails loud): surface a real error with an explicit
+        // subtype. NOT triggered for a tool-only completion (a tool
+        // ran → side effects the user saw → polygram's
+        // numToolUses>0 branch handles it) nor for a non-success
+        // terminal stop (max_tokens / stop_sequence / refusal carry
+        // their own already-surfaced subtype).
+        if (text.trim() === ''
+          && turn.toolUses === 0
+          && resultSubtype === 'success') {
+          throw Object.assign(
+            new Error('turn produced an empty JSONL result (end_turn, no text, no tools)'),
+            { code: 'TMUX_EMPTY_JSONL_RESULT' },
+          );
+        }
       } else {
-        // Capture-pane won, but for short turns claude may flush JSONL
-        // AFTER the TUI shows ready. Wait briefly for the structured
-        // event so we can use its (clean) text over capture-pane diff.
-        //
-        // OPTIMIZATION: if JSONL has ALREADY delivered assistant text
-        // by the time capture-pane resolves, we already have the
-        // structured text — skip the late-grace wait entirely. Saves
-        // ~1.5s on every short reply where the JSONL streamed in
-        // during the turn.
-        if (this._turnState.text) {
+        // Capture-pane quiescence judged the turn complete. Force the
+        // JSONL aggregator to finalize any buffered message so the
+        // structured `result` settles turn.resultPromise now.
+        this._sessionLogTail?.flushParser?.();
+        if (turn.text) {
           resolvedVia = 'jsonl-streamed';
-          text = this._turnState.text;
+          text = turn.text;
         } else {
           const lateGraceMs = this.lateGraceMs ?? 1500;
           const late = await Promise.race([
-            turnResultP.then((ev) => ({ kind: 'jsonl-late', ev })),
+            turn.resultPromise.then((ev) => ({ kind: 'jsonl-late', ev })),
             new Promise((r) => setTimeout(() => r({ kind: 'no-jsonl' }), lateGraceMs)),
           ]);
           if (late.kind === 'jsonl-late') {
             resolvedVia = 'jsonl-late';
-            text = this._turnState.text || late.ev.text || '';
+            text = turn.text || late.ev.text || '';
             resultSubtype = late.ev.subtype || 'success';
             stopReason = late.ev.stopReason || null;
             if (late.ev.sessionId) this.claudeSessionId = late.ev.sessionId;
           } else {
-            resolvedVia = 'capture-pane';
-            text = this._turnState.text || this._extractTurnReply(captureAtStart, winner.cap);
+            // §6: capture-pane judged the turn done, but JSONL
+            // produced NO reply text within the grace window. FAIL
+            // LOUD — never fall back to capture-pane diff text. That
+            // fallback WAS the echoed-input failure (the pane diff
+            // returned the user's own echoed prompt) and the
+            // banner-as-reply failure (L1). The error result clears
+            // the reactor explicitly instead of delivering garbage.
+            throw Object.assign(
+              new Error('turn produced no JSONL reply text within grace window'),
+              { code: 'TMUX_NO_JSONL_TEXT' },
+            );
           }
         }
       }
 
-      const duration = this._now() - startedAt;
+      const duration = this._now() - turn.startedAt;
       this.emit('result', { subtype: resultSubtype, resolvedVia }, { streamText: text, stopReason });
 
-      // Token + cost telemetry from the latest JSONL usage snapshot.
-      // claude doesn't write cost into JSONL; we compute from token
-      // counts × `lib/model-costs.js` rate table. The result populates
-      // turn_metrics so cost dashboards work the same as SDK.
       const u = this._lastUsage;
       const cost = u ? computeCostUsd(u, u.model) : null;
-
-      const pmResult = {
+      turn.state = 'done';
+      turn.resolve({
         text,
         sessionId: this.claudeSessionId,
         cost,
@@ -425,35 +700,170 @@ class TmuxProcess extends Process {
           cacheCreationTokens: u?.cacheCreationTokens ?? null,
           cacheReadTokens: u?.cacheReadTokens ?? null,
           numAssistantMessages: 1,
-          numToolUses: this._turnState.toolUses,
+          numToolUses: turn.toolUses,
           resultSubtype,
           stopReason,
           resolvedVia,
         },
-      };
-      this._completeTurn();
-      return pmResult;
+      });
     } catch (err) {
-      this._completeTurn();
-      return this._errorResult(err.code || 'tmux_send_error', err.message || String(err));
+      turn.state = 'failed';
+      turn.resolve(this._errorResult(err.code || 'tmux_send_error', err.message || String(err)));
+    } finally {
+      this._finishTurn(turn);
     }
   }
 
-  _completeTurn() {
-    this.inFlight = false;
-    // Shift the HEAD pending (just-completed turn). After this, the
-    // queue contains only items queued while inFlight (each carrying
-    // their own resolve/reject pair). If any, re-enter send() on the
-    // next one — send() will push its own fresh head pending.
-    this.pendingQueue.shift();
-    const next = this.pendingQueue.shift();
-    if (next && next.resolve) {
-      this.send(next.prompt, next.opts).then(next.resolve, next.reject);
+  /**
+   * Retire a finished primary turn and drain the next queued one.
+   */
+  _finishTurn(turn) {
+    // Finalize any assistant message still buffered in the JSONL
+    // aggregator BEFORE the next turn starts, so a turn that ended
+    // without a terminal `result` (e.g. turnTimeoutMs) cannot leak
+    // its buffered message into turn N+1.
+    this._sessionLogTail?.flushParser?.();
+    const qi = this.pendingQueue.indexOf(turn);
+    if (qi >= 0) this.pendingQueue.splice(qi, 1);
+    this._dropFromActiveGroup(turn);
+    // R1: if this primary turn ended WITHOUT its active group being
+    // flushed by a terminal `result` (it timed out or errored), the
+    // autosteer turns folded into that group would otherwise strand
+    // as `streaming` forever — leaking in the ledger AND keeping
+    // `_activeGroup` non-empty, which silently swallows the next
+    // autonomous assistant message. Retire the leftovers + reset the
+    // group.
+    //
+    // R11: retire the group ONLY when it is the group THIS finishing
+    // primary owns (`primaryTurnId === turn.turnId`). The old code
+    // retired whatever was in `_activeGroup` unconditionally — but in
+    // the window between the primary's `result` (which
+    // `_flushActiveGroup` used to reset the group) and `_runTurn`
+    // reaching `_finishTurn`, a NEW-TURN autosteer's dequeued
+    // `user-message` can route a FRESH group into place. That group
+    // belongs to the autosteer, not this primary; retiring it marked
+    // the autosteer `failed` and its chunks then leaked as an
+    // `autonomous-assistant-message` instead of an `extra-turn-reply`.
+    // A NEW-TURN autosteer group has `primaryTurnId: null`, so the
+    // guard leaves it untouched. (On a successful primary turn
+    // `_flushActiveGroup` already reset the group, so `turns` is empty
+    // and this is a no-op either way.)
+    if (this._activeGroup.turns.length > 0
+      && this._activeGroup.primaryTurnId === turn.turnId) {
+      for (const t of this._activeGroup.turns) {
+        if (t.state !== 'done' && t.state !== 'failed') t.state = 'failed';
+      }
+      this._activeGroup = {
+        turns: [], text: '', pendingSteerCausesNewBubble: false,
+        primaryTurnId: null,
+      };
+    }
+    this._sweepStaleTurns();
+    const next = this.pendingQueue[0];
+    if (next && next.state === 'queued') {
+      this._runTurn(next);
     } else {
+      this.inFlight = false;
       this.emit('idle');
     }
   }
 
+  // ─── token + ledger helpers (0.10.0 Phase 2) ─────────────────────
+
+  /** Mint a unique correlation token. `[a-z0-9-]` only — newline-free,
+   *  no XML metacharacters — so it survives paste -> MULTILINE_SEPARATOR
+   *  -> JSONL verbatim (validated by scripts/spikes/correlation-token-tui). */
+  _mintToken() {
+    return `pgm-corr-${crypto.randomBytes(12).toString('hex')}`;
+  }
+
+  /** Build a fresh Turn record. */
+  _makeTurn({ kind, prompt = '', opts = {}, context = {}, msgIds = [] }) {
+    this._turnSeq += 1;
+    return {
+      turnId: this._turnSeq,
+      token: this._mintToken(),
+      msgIds: [...msgIds],
+      kind,                      // 'primary' | 'autosteer'
+      state: 'queued',           // queued | pasted | streaming | done | failed
+      text: '',
+      toolUses: 0,
+      toolUsedThisTurn: false,
+      stopReason: null,
+      resultEvent: null,
+      via: null,                 // autosteer: 'fold' | 'new-turn'
+      context, opts, prompt,
+      startedAt: 0,
+      resolve: null, reject: null, callerPromise: null,
+      settleResult: null, resultPromise: null,
+    };
+  }
+
+  /**
+   * Embed a correlation token into a prompt's <polygram-info> block as
+   * a `corr-id` attribute. The agent is already instructed to ignore
+   * that block, so the token is invisible to the conversation. If the
+   * prompt has no <polygram-info> block (non-standard paste), prepend
+   * a minimal carrier — the agent ignores empty <polygram-info> too.
+   */
+  _embedToken(prompt, token) {
+    const p = String(prompt ?? '');
+    if (/<polygram-info[\s>]/.test(p)) {
+      return p.replace(/<polygram-info([\s>])/, `<polygram-info corr-id="${token}"$1`);
+    }
+    return `<polygram-info corr-id="${token}"></polygram-info>\n\n${p}`;
+  }
+
+  /** Extract every correlation token present in a JSONL line.
+   *  Matches the EXACT minted shape (`pgm-corr-` + 24 hex from
+   *  randomBytes(12)) — `{24}` instead of `+` so a token followed by
+   *  adjacent hex still extracts exactly the 24-char token (R6). */
+  _extractTokens(text) {
+    if (typeof text !== 'string') return [];
+    const m = text.match(/pgm-corr-[0-9a-f]{24}/g);
+    return m ? [...new Set(m)] : [];
+  }
+
+  /** Drop done/failed turns — token uniqueness means a stale match is
+   *  impossible, so retired turns are pure memory overhead. */
+  _pruneLedger() {
+    this._ledger = this._ledger.filter(
+      (t) => t.state !== 'done' && t.state !== 'failed',
+    );
+  }
+
+  /**
+   * 0.10.0 Phase 4 §7: stale-turn sweep. An autosteer turn whose
+   * paste the TUI never correlated (no enqueue / remove / dequeue /
+   * user-message) within a grace window is dead — fail it loud so it
+   * cannot leak in the ledger. A primary turn that produces no JSONL
+   * text already fails loud via §6 in `_runTurn`, so the sweep only
+   * targets stuck autosteers. Runs at every turn completion.
+   */
+  _sweepStaleTurns() {
+    const now = this._now();
+    const graceMs = this.turnTimeoutMs;
+    for (const turn of this._ledger) {
+      if (turn.kind !== 'autosteer' || turn.state !== 'pasted') continue;
+      if (!turn.startedAt || (now - turn.startedAt) < graceMs) continue;
+      turn.state = 'failed';
+      this._enqueuedTurns = this._enqueuedTurns.filter((t) => t !== turn);
+      this.emit('autosteer-match-miss', {
+        phase: 'stale-sweep',
+        msgId: turn.msgIds[0] ?? null,
+        turnId: turn.turnId,
+        ageMs: now - turn.startedAt,
+        sessionId: this.claudeSessionId,
+        backend: 'tmux',
+      });
+    }
+    this._pruneLedger();
+  }
+
+  _dropFromActiveGroup(turn) {
+    this._activeGroup.turns = this._activeGroup.turns.filter((t) => t !== turn);
+  }
+
   _errorResult(code, message) {
     return {
       text: '',
@@ -476,11 +886,9 @@ class TmuxProcess extends Process {
    * Open a tail on `~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl`
    * and forward parsed events to Process listeners.
    *
-   * Events forwarded:
-   *   - assistant-chunk → emit 'stream-chunk' (matches SdkProcess shape)
-   *   - tool-use        → emit 'tool-use'
-   *   - result          → resolve current turn's _turnState.resolveResult
-   *   - last-prompt     → fallback turn-complete signal
+   * Events are routed by `_handleSessionEvent` through the Phase 2
+   * turn ledger — `user-message` tokens attribute each event to its
+   * Turn; `result` flushes the active group.
    */
   _armSessionLogTail({ resuming = false } = {}) {
     if (this._sessionLogTail) return; // idempotent
@@ -514,30 +922,33 @@ class TmuxProcess extends Process {
 
   _handleSessionEvent(ev) {
     if (ev.type === 'assistant-chunk') {
-      if (this._turnState) {
-        // If a mid-turn steer just happened, the NEXT assistant message
-        // should start a fresh Telegram bubble — otherwise the post-steer
-        // reply visually appends to the pre-steer text bubble, making the
-        // user's follow-up look unanswered. Mirror SdkProcess's logic:
-        // emit 'assistant-message-start', reset the accumulator, clear
-        // the flag. Subsequent chunks within THIS new assistant message
-        // continue to accumulate in the fresh bubble.
-        if (this._turnState.pendingSteerCausesNewBubble) {
-          this._turnState.pendingSteerCausesNewBubble = false;
-          this._turnState.text = '';
+      // Assistant text belongs to whatever turn(s) the latest
+      // `user-message` token routed into the active group. The
+      // handler never guesses from "which accumulator is non-null".
+      const group = this._activeGroup;
+      if (group.turns.length > 0) {
+        // A mid-turn steer asks the NEXT assistant message to open a
+        // fresh Telegram bubble so the post-steer reply doesn't
+        // visually append to the pre-steer text.
+        if (group.pendingSteerCausesNewBubble) {
+          group.pendingSteerCausesNewBubble = false;
+          group.text = '';
           this.emit('assistant-message-start');
         }
-        // In-flight turn: accumulate text + forward as stream-chunk so
-        // pm consumers can render incremental output.
-        this._turnState.text = this._turnState.text
-          ? `${this._turnState.text}\n\n${ev.text}`
-          : ev.text;
-        this.emit('stream-chunk', this._turnState.text);
+        group.text = group.text ? `${group.text}\n\n${ev.text}` : ev.text;
+        // Keep every turn in the group current — a fold shares one
+        // reply across its members.
+        for (const t of group.turns) t.text = group.text;
+        // stream-chunk drives the live Telegram bubble via
+        // pendingQueue[0].context.streamer — only the primary turn
+        // owns that surface. Autosteer NEW-TURN replies are delivered
+        // whole via extra-turn-reply, never streamed.
+        if (group.turns.some((t) => t.kind === 'primary')) {
+          this.emit('stream-chunk', group.text);
+        }
       } else {
-        // No turn in flight — this is an autonomous assistant message
-        // (claude self-initiated; typically ScheduleWakeup firing).
-        // Mirror SdkProcess.onAutonomousAssistantMessage routing so
-        // pm consumers receive these the same way regardless of backend.
+        // No active turn — autonomous assistant message (claude
+        // self-initiated; typically ScheduleWakeup firing).
         this.emit('autonomous-assistant-message', {
           text: ev.text,
           sessionId: this.claudeSessionId,
@@ -545,7 +956,13 @@ class TmuxProcess extends Process {
         });
       }
     } else if (ev.type === 'tool-use') {
-      if (this._turnState) this._turnState.toolUses++;
+      for (const t of this._activeGroup.turns) {
+        t.toolUses++;
+        // The `tool-use` event is the earliest proof a tool ran — set
+        // the flag here so a transient capture-pane "ready" between
+        // tool calls cannot resolve a still-working turn.
+        t.toolUsedThisTurn = true;
+      }
       this.emit('tool-use', ev.name);
     } else if (ev.type === 'usage') {
       // Token-usage snapshot from JSONL. Cache for getContextUsage().
@@ -584,31 +1001,293 @@ class TmuxProcess extends Process {
       }
       this._lastUsage = ev;
     } else if (ev.type === 'result') {
-      if (this._turnState && this._turnState.resolveResult) {
-        this._turnState.resultEvent = ev;
-        this._turnState.resolveResult(ev);
+      // Only a TERMINAL stop_reason ends a turn. The JSONL aggregator
+      // emits a `result` per assistant message — `tool_use` is
+      // NON-terminal (the agent paused for a tool; more messages
+      // follow). Terminal: 'success' (end_turn), 'max_tokens',
+      // 'stop_sequence', 'refusal'.
+      if (ev.subtype === 'tool_use') return;
+      this._flushActiveGroup(ev);
+    } else if (ev.type === 'user-message') {
+      this._routeUserMessage(ev);
+    } else if (ev.type === 'queue-operation') {
+      // The live queue-activity signal — the real fold mechanism
+      // (verified against claude 2.1.142 JSONL):
+      //   enqueue {content} — a paste was parked in the TUI's input
+      //     queue; content carries the correlation token.
+      //   remove           — the oldest queued paste was FOLDED into
+      //     the running turn. NO user-message follows — the autosteer
+      //     MUST be resolved here or it leaks forever.
+      //   dequeue          — the oldest queued paste was released to
+      //     run as a fresh turn; its user-message follows and
+      //     _routeUserMessage resolves it (NEW-TURN).
+      if (ev.operation === 'enqueue' && ev.content) {
+        const tokens = this._extractTokens(ev.content);
+        this._confirmPaste(tokens);   // §5: enqueue proves the paste landed
+        for (const tok of tokens) {
+          // R2: track ANY queued turn — primary OR autosteer. A
+          // primary paste that lands while the TUI is busy is also
+          // queued; if it is not mirrored here, the later positional
+          // `remove`/`dequeue` shift pops the wrong turn and the FIFO
+          // desyncs.
+          const turn = this._ledger.find(
+            (t) => t.token === tok
+              && t.state !== 'done' && t.state !== 'failed',
+          );
+          if (turn && !this._enqueuedTurns.includes(turn)) {
+            this._enqueuedTurns.push(turn);
+          }
+        }
+      } else if (ev.operation === 'remove') {
+        // The head queued turn was FOLDED into the running turn. Only
+        // an autosteer folds — a primary never does; if a primary is
+        // somehow at the head it is just dropped from tracking.
+        const turn = this._enqueuedTurns.shift();
+        if (turn && turn.kind === 'autosteer'
+          && turn.state !== 'done' && turn.state !== 'failed') {
+          this._foldAutosteer(turn);
+        }
+      } else if (ev.operation === 'dequeue') {
+        // The head queued turn was released to run as a fresh turn —
+        // drop tracking; its user-message follows and _routeUserMessage
+        // resolves it (primary → its own turn; autosteer → NEW-TURN).
+        this._enqueuedTurns.shift();
       }
-      // If no turn in flight, the result event simply marks the end of
-      // an autonomous message segment — already handled by the
-      // assistant-chunk branch above.
+    } else if (ev.type === 'queue-folded') {
+      // Dead path: `attachment.queued_command` does not appear in
+      // real claude 2.1.142 JSONL. Kept inert for parser parity.
     } else if (ev.type === 'last-prompt') {
-      // Fallback complete signal. If 'result' didn't fire (rare; some
-      // claude versions may write last-prompt instead of stop_reason),
-      // synthesize a success result.
-      if (this._turnState && this._turnState.resolveResult && !this._turnState.resultEvent) {
-        const synthetic = {
+      // `last-prompt` fires when a prompt is REGISTERED, not when a
+      // turn ends. The JSONL aggregator already fires a proper
+      // `result` on the message's terminal stop_reason; this is only
+      // a safety net for a turn whose terminal stop_reason never
+      // wrote. Fire it ONLY when the active group has a primary turn
+      // with accumulated text — never hijack a turn that has not
+      // started replying.
+      const group = this._activeGroup;
+      if (group.turns.some((t) => t.kind === 'primary')
+        && group.text && group.text.length > 0) {
+        this._flushActiveGroup({
           type: 'result',
           subtype: 'success',
-          text: this._turnState.text,
+          text: group.text,
           stopReason: 'last-prompt',
           sessionId: this.claudeSessionId,
-        };
-        this._turnState.resultEvent = synthetic;
-        this._turnState.resolveResult(synthetic);
+        });
+      }
+    }
+  }
+
+  /**
+   * Route a JSONL `user-message` to the turn(s) its correlation
+   * token(s) identify. This is the heart of recorded (not
+   * reconstructed) attribution: each token is an exact id lookup.
+   *
+   * A user-message's matched turns join the active group:
+   *   - if the group will contain a primary turn, an autosteer turn
+   *     is a FOLD — the primary's reply covers it (autosteer-
+   *     resolution via:fold; no separate delivery);
+   *   - otherwise the autosteer is a NEW-TURN — it gets its own
+   *     reply via extra-turn-reply on the group's terminal result.
+   * N tokens in ONE user-message (a concatenated paste) is an
+   * explicit, unambiguous fold of N turns.
+   */
+  _routeUserMessage(ev) {
+    const tokens = this._extractTokens(ev.text);
+    // Phase 3 §5: a user-message proves its pastes landed — release
+    // the paste gate for those tokens.
+    this._confirmPaste(tokens);
+    let matched = [];
+    for (const tok of tokens) {
+      const t = this._ledger.find(
+        (x) => x.token === tok && x.state !== 'done' && x.state !== 'failed',
+      );
+      if (t && !matched.includes(t)) matched.push(t);
+    }
+    if (matched.length === 0) {
+      // No token matched. A token-less user-message can still be a
+      // primary turn we pasted whose token failed to round-trip —
+      // claim the oldest such 'pasted' primary as a fallback.
+      if (tokens.length === 0) {
+        const orphan = this._ledger.find(
+          (x) => x.kind === 'primary' && x.state === 'pasted',
+        );
+        if (orphan) matched = [orphan];
+      }
+      if (matched.length === 0) {
+        // Genuinely unrecognised — diagnostic, then ignore. (A
+        // resumed-session historic user-message lands here; harmless.)
+        this.emit('autosteer-match-miss', {
+          phase: 'user-message',
+          text_head: (ev.text || '').slice(0, 80),
+          token_count: tokens.length,
+          ledger_size: this._ledger.length,
+          sessionId: this.claudeSessionId,
+          backend: 'tmux',
+        });
+        return;
+      }
+    }
+    const group = this._activeGroup;
+    const willHavePrimary = group.turns.some((t) => t.kind === 'primary')
+      || matched.some((t) => t.kind === 'primary');
+    for (const t of matched) {
+      if (group.turns.includes(t)) continue;
+      // R4: idempotency guard — a turn that already has a `via` was
+      // already classified (e.g. folded via `queue-operation remove`).
+      // Never route or resolve it twice.
+      if (t.via) continue;
+      t.state = 'streaming';
+      group.turns.push(t);
+      // R11: a primary turn joining the group makes it that primary's
+      // group — record the owner so `_finishTurn` retires only the
+      // group its finishing primary owns. A NEW-TURN autosteer never
+      // sets this, so its fresh group keeps `primaryTurnId: null` and
+      // survives an unrelated primary's `_finishTurn`.
+      if (t.kind === 'primary') group.primaryTurnId = t.turnId;
+      if (t.kind !== 'autosteer') continue;
+      t.via = willHavePrimary ? 'fold' : 'new-turn';
+      if (t.via === 'new-turn') {
+        for (const msgId of t.msgIds) {
+          this.emit('extra-turn-started', {
+            msgId, sessionId: this.claudeSessionId, backend: 'tmux',
+          });
+        }
+      }
+      for (const msgId of t.msgIds) {
+        this.emit('autosteer-resolution', {
+          msgId, via: t.via, sessionId: this.claudeSessionId, backend: 'tmux',
+        });
+      }
+    }
+  }
+
+  /**
+   * Resolve an autosteer turn the TUI folded into the running turn
+   * (a `queue-operation remove`). A fold shares the primary turn's
+   * reply — autosteer-resolution(via:fold) tells polygram the message
+   * is covered; no separate extra-turn-reply is delivered. The turn
+   * joins the active group so the terminal-result flush retires it.
+   */
+  _foldAutosteer(turn) {
+    turn.via = 'fold';
+    turn.state = 'streaming';
+    if (!this._activeGroup.turns.includes(turn)) {
+      this._activeGroup.turns.push(turn);
+    }
+    for (const msgId of turn.msgIds) {
+      this.emit('autosteer-resolution', {
+        msgId, via: 'fold', sessionId: this.claudeSessionId, backend: 'tmux',
+      });
+    }
+  }
+
+  /**
+   * Flush the active turn group on a terminal `result`: settle the
+   * primary turn's send() race, deliver each NEW-TURN autosteer's
+   * reply, and clear the group.
+   */
+  _flushActiveGroup(ev) {
+    const group = this._activeGroup;
+    if (group.turns.length === 0) return; // autonomous segment end
+    const turns = group.turns;
+    const text = group.text;
+    this._activeGroup = {
+      turns: [], text: '', pendingSteerCausesNewBubble: false,
+      primaryTurnId: null,
+    };
+    if (ev.sessionId) this.claudeSessionId = ev.sessionId;
+    for (const t of turns) {
+      t.state = 'done';
+      t.text = text;
+      t.stopReason = ev.stopReason || null;
+      t.resultEvent = ev;
+    }
+    // Primary turn — settle its _runTurn race so send() resolves.
+    const primary = turns.find((t) => t.kind === 'primary');
+    if (primary && typeof primary.settleResult === 'function') {
+      primary.settleResult(ev);
+    }
+    // Autosteer NEW-TURN turns — deliver the shared reply once per
+    // owning msgId. FOLD autosteers already emitted autosteer-
+    // resolution(via:fold); the primary's reply covers them.
+    for (const t of turns) {
+      if (t.kind !== 'autosteer' || t.via !== 'new-turn') continue;
+      for (const msgId of t.msgIds) {
+        this.emit('extra-turn-reply', {
+          msgId, text, sessionId: this.claudeSessionId, backend: 'tmux',
+        });
       }
     }
   }
 
+  /**
+   * Paste a prompt body + press Enter, then GATE the next paste on
+   * JSONL confirmation (0.10.0 Phase 3 §5).
+   *
+   * rc.13.1: the runner's `pasteAndEnter` holds a per-session lock so
+   * the paste+Enter pair is atomic (no interleaved keystrokes).
+   *
+   * Phase 3 §5 adds the outer barrier: `_pasteLock` is held until the
+   * JSONL tail confirms THIS paste landed — its correlation token
+   * surfaced in a `user-message` or `queue-operation` event — bounded
+   * by `pasteConfirmMs`. The next `_pasteAndEnter` therefore cannot
+   * start until the previous paste is a distinct TUI input, so two
+   * pastes can no longer concatenate. The lock is released
+   * asynchronously (on confirm/timeout) so it gates only the NEXT
+   * paste, never delays this caller.
+   */
+  async _pasteAndEnter(text) {
+    const token = this._extractTokens(text)[0] || null;
+    const release = await this._pasteLock.acquire(this.tmuxName);
+    let result;
+    try {
+      if (typeof this.runner.pasteAndEnter === 'function') {
+        result = await this.runner.pasteAndEnter(this.tmuxName, text);
+      } else {
+        result = await this.runner.pasteText(this.tmuxName, text);
+        await this.runner.sendControl(this.tmuxName, 'Enter');
+      }
+    } catch (err) {
+      release();
+      throw err;
+    }
+    // Hold the paste lock until JSONL confirms this paste — gating
+    // the NEXT paste, not this caller (which gets `result` now).
+    if (token) {
+      this._awaitPasteConfirm(token).then(release, release);
+    } else {
+      release();
+    }
+    return result;
+  }
+
+  /**
+   * Resolve once `token` surfaces in a JSONL user-message /
+   * queue-operation, or after `pasteConfirmMs` (bounded barrier).
+   */
+  _awaitPasteConfirm(token) {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        this._pasteConfirms.delete(token);
+        resolve();
+      };
+      this._pasteConfirms.set(token, finish);
+      setTimeout(finish, this.pasteConfirmMs).unref?.();
+    });
+  }
+
+  /** Mark the given correlation tokens as JSONL-confirmed (Phase 3 §5). */
+  _confirmPaste(tokens) {
+    for (const t of tokens) {
+      const finish = this._pasteConfirms.get(t);
+      if (finish) finish();
+    }
+  }
+
   // ─── completion detection (§4.A capture-pane diff path — fallback) ──
 
   /**
@@ -624,22 +1303,32 @@ class TmuxProcess extends Process {
 
   async _waitForReady() {
     const deadline = this._now() + this.readyTimeoutMs;
+    let lastBuf = '';
     if (this.pollScheduler) this.pollScheduler.acquire();
     try {
       while (this._now() < deadline) {
         // OPTIMIZATION: ready hint lives in the bottom ~5 lines of the
         // pane. Polling 1000 lines each tick is wasteful — cap at 80
         // for a ~12× cheaper tmux subprocess.
-        const buf = await this.runner.captureWide(this.tmuxName, { lines: 80 });
-        if (READY_HINTS_RE.test(buf)) return;
+        lastBuf = await this.runner.captureWide(this.tmuxName, { lines: 80 });
+        if (READY_HINTS_RE.test(lastBuf)) return;
         await this._waitForNextTick();
       }
     } finally {
       if (this.pollScheduler) this.pollScheduler.release();
     }
+    // On timeout, surface what the TUI was actually showing so the
+    // operator can diagnose whether it was hung, on a setup prompt,
+    // or just slow to render the ready hint. capture the last ~40
+    // lines for the error event payload + log.
+    const tail = lastBuf.split('\n').slice(-40).join('\n');
+    this.logger.warn?.(
+      `[${this.label}] TUI did not signal ready in ${this.readyTimeoutMs}ms; last pane tail:\n${tail}`,
+    );
     throw Object.assign(new Error('TmuxProcess: TUI did not signal ready'), {
       code: 'TMUX_READY_TIMEOUT',
       tmuxName: this.tmuxName,
+      paneTail: tail,
     });
   }
 
@@ -652,17 +1341,29 @@ class TmuxProcess extends Process {
    * hint at the bottom). For the FINAL capture used to extract reply
    * text, we fall back to the default 1000-line wide capture.
    */
-  async _awaitTurnComplete({ timeoutMs }) {
+  async _awaitTurnComplete({ timeoutMs, abortP = null }) {
     const deadline = this._now() + timeoutMs;
     let firstReadyAt = null;
     let lastBuf = '';
     let prevBufLen = -1;
     let cachedReady = false;
     let cachedStreaming = false;
+    // R7: when the caller supplies `abortP`, every blocking await in
+    // the loop (the `captureWide` subprocess AND the inter-tick wait)
+    // is raced against it. A wedged `tmux capture-pane` would
+    // otherwise park the loop forever — neither completing the turn
+    // nor releasing the PollScheduler refcount. `abortP` resolves
+    // with ABORT_SENTINEL; any await that loses the race to it yields
+    // the sentinel, and the loop exits via the `finally` (releasing
+    // the scheduler) so _runTurn's absolute deadline fails the turn.
+    const raceAbort = abortP
+      ? (p) => Promise.race([p, abortP.then(() => ABORT_SENTINEL)])
+      : (p) => p;
     if (this.pollScheduler) this.pollScheduler.acquire();
     try {
     while (this._now() < deadline) {
-      lastBuf = await this.runner.captureWide(this.tmuxName, { lines: 200 });
+      lastBuf = await raceAbort(this.runner.captureWide(this.tmuxName, { lines: 200 }));
+      if (lastBuf === ABORT_SENTINEL) return ABORT_SENTINEL;
 
       // OPTIMIZATION: skip the three regex tests when the capture
       // buffer is identical (by length) to the previous tick. claude
@@ -675,7 +1376,16 @@ class TmuxProcess extends Process {
       const bufLenChanged = lastBuf.length !== prevBufLen;
       if (bufLenChanged) {
         prevBufLen = lastBuf.length;
-        cachedReady = READY_HINTS_RE.test(lastBuf);
+        // L1 fix: ignore READY hint while the startup banner is
+        // still the LATEST thing on the pane. After the agent has
+        // emitted content, the banner ends up in scrollback far
+        // above the bottom — at that point we DO want READY to
+        // count. Check only the last ~10 lines for the banner:
+        // if the bottom of the pane is still banner+ready, the
+        // agent hasn't produced output yet, so the ready hint is
+        // a startup artifact, not the end of a real turn.
+        const bottomTail = lastBuf.slice(-2000);  // ~10-20 lines of pane bottom
+        cachedReady = READY_HINTS_RE.test(lastBuf) && !TUI_BANNER_RE.test(bottomTail);
         cachedStreaming = STREAMING_HINT_RE.test(lastBuf);
         // Approval-prompt detection ONLY runs on changed captures.
         // It's the heaviest regex (`[\s\S]{0,400}?` non-greedy) so
@@ -683,7 +1393,9 @@ class TmuxProcess extends Process {
         if (APPROVAL_PROMPT_RE.test(lastBuf)) {
           await this._handleApprovalPrompt(lastBuf);
           firstReadyAt = null;     // approval pause resets ready clock
-          await this._waitForNextTick();
+          if (await raceAbort(this._waitForNextTick()) === ABORT_SENTINEL) {
+            return ABORT_SENTINEL;
+          }
           continue;
         }
       }
@@ -696,7 +1408,9 @@ class TmuxProcess extends Process {
       } else {
         firstReadyAt = null;
       }
-      await this._waitForNextTick();
+      if (await raceAbort(this._waitForNextTick()) === ABORT_SENTINEL) {
+        return ABORT_SENTINEL;
+      }
     }
     throw Object.assign(new Error('TmuxProcess: turn did not complete in time'), {
       code: 'TMUX_TURN_TIMEOUT',
@@ -777,20 +1491,9 @@ class TmuxProcess extends Process {
     }
   }
 
-  /**
-   * Best-effort: text between the start-of-turn snapshot and the
-   * post-completion snapshot. The capture-pane diff strategy is
-   * intentionally crude in MVP — Phase 3 will switch to --debug-file
-   * for structured assistant-message extraction.
-   */
-  _extractTurnReply(captureAtStart, captureAtEnd) {
-    if (!captureAtEnd) return '';
-    if (captureAtStart && captureAtEnd.startsWith(captureAtStart)) {
-      return captureAtEnd.slice(captureAtStart.length).trim();
-    }
-    // Fallback: return whatever's after the user's last prompt marker.
-    return captureAtEnd.trim();
-  }
+  // 0.10.0 Phase 4 §6: `_extractTurnReply` (capture-pane diff text
+  // extraction) is GONE. Reply text comes exclusively from JSONL
+  // keyed to a turn. capture-pane is liveness-only — see `_runTurn`.
 
   // ─── interrupts / control ────────────────────────────────────────
 
@@ -933,57 +1636,97 @@ class TmuxProcess extends Process {
   // ─── HOT-PATH sync — must NOT throw (R1-F1) ──────────────────────
 
   /**
-   * Reject all local pendings with the supplied code. Returns count.
-   * No-throw contract — autosteer's call site has no try/catch.
+   * Reject every QUEUED primary turn with the supplied code. The
+   * running head turn (pendingQueue[0], state 'pasted'/'streaming')
+   * is left alone — it settles normally via its own _runTurn flow.
+   * Returns the count drained. No-throw contract — autosteer's call
+   * site has no try/catch.
    */
   drainQueue(code = 'INTERRUPTED') {
-    const drained = this.pendingQueue.length;
-    if (drained === 0) return 0;
+    // Drain every pendingQueue entry EXCEPT the running head (a Turn
+    // in state 'pasted'/'streaming' — it settles via its own _runTurn
+    // flow). Queued turns ('queued') are drained; so are stateless
+    // entries (test fakes), which are never the running head.
+    const toDrain = this.pendingQueue.filter(
+      (t) => t.state !== 'pasted' && t.state !== 'streaming',
+    );
+    if (toDrain.length === 0) return 0;
     const err = Object.assign(new Error(`drained:${code}`), { code });
-    while (this.pendingQueue.length > 0) {
-      const p = this.pendingQueue.shift();
-      // Head pending (currently-running turn) has no resolve/reject —
-      // it returns directly via send()'s promise chain. Skip rejection
-      // for those; the send() flow handles errors via _errorResult.
-      if (p && typeof p.reject === 'function') {
-        try { p.reject(err); } catch (e) {
+    for (const t of toDrain) {
+      const qi = this.pendingQueue.indexOf(t);
+      if (qi >= 0) this.pendingQueue.splice(qi, 1);
+      if (t.state) t.state = 'failed';
+      if (typeof t.reject === 'function') {
+        try { t.reject(err); } catch (e) {
           this.logger.error?.(`[${this.label}] drainQueue reject: ${e.message}`);
         }
       }
     }
-    this.emit('queue-drop', drained);
-    return drained;
+    this._pruneLedger();
+    this.emit('queue-drop', toDrain.length);
+    return toDrain.length;
   }
 
   /**
-   * Inject text into the in-flight turn. Fire-and-forget paste; errors
-   * surface via 'inject-fail' event, never as a thrown exception.
+   * Inject text into the in-flight turn (autosteer). Fire-and-forget
+   * paste; errors surface via 'inject-fail', never as a throw.
+   *
+   * Registers an autosteer Turn in the ledger with a fresh
+   * correlation token embedded in the paste. When the TUI surfaces
+   * the paste as a JSONL `user-message`, the token routes it — FOLD
+   * (a primary turn shares the group) or NEW-TURN (it does not).
    *
+   * @param {object} [opts.msgId]  — Telegram msgId; when present, a
+   *   NEW-TURN autosteer's reply is routed back via 'extra-turn-reply'.
    * @returns {boolean} false if no live turn (caller falls through to
-   *   pm.send queue path) OR if content sanitized to empty.
+   *   the pm.send queue path) OR if content sanitized to empty.
    */
-  injectUserMessage({ content, priority = 'next', shouldQuery } = {}) {
+  injectUserMessage({ content, priority = 'next', shouldQuery, msgId } = {}) {
     if (!this.inFlight || this.closed) return false;
-    // Mirror R2-F1: sanitize even though pasteText also sanitizes.
-    // We need to detect empty-after-sanitize here so caller can fall
-    // through (pasteText would happily send the empty string).
+    // Detect empty-after-sanitize here so the caller can fall through.
     const safe = String(content || '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
     if (!safe) return false;
 
-    Promise.resolve()
-      .then(() => this.runner.pasteText(this.tmuxName, safe))
-      .then(() => this.runner.sendControl(this.tmuxName, 'Enter'))
-      .catch((err) => this.emit('inject-fail', { err: err.message }));
-
-    // Tell the next assistant-chunk to open a fresh Telegram bubble
-    // so the post-steer reply visually follows the user's mid-turn
-    // message instead of appending to the pre-steer bubble. Mirrors
-    // SdkProcess's pendingSteerCausesNewBubble flag.
-    if (this._turnState) {
-      this._turnState.pendingSteerCausesNewBubble = true;
-    }
+    const turn = this._makeTurn({
+      kind: 'autosteer',
+      prompt: safe,
+      msgIds: msgId != null ? [msgId] : [],
+    });
+    turn.state = 'pasted';
+    turn.startedAt = this._now();   // Phase 4 §7: staleness clock
+    this._ledger.push(turn);
+
+    // The next assistant message after a mid-turn steer opens a fresh
+    // Telegram bubble so the post-steer reply doesn't append to the
+    // pre-steer text.
+    this._activeGroup.pendingSteerCausesNewBubble = true;
+
+    // pasteAndEnter holds the per-session lock so this autosteer's
+    // paste+Enter cannot interleave keystrokes with an in-flight
+    // primary paste.
+    //
+    // R8: if the paste rejects the autosteer never reached the TUI —
+    // it will never correlate to a JSONL user-message, so the
+    // stale-turn sweep would otherwise be the ONLY thing that catches
+    // it, `turnTimeoutMs` later. Fail the ledger turn immediately and
+    // emit `inject-fail` WITH the msgId so the wired onInjectFail
+    // handler can clear the ✍ reaction promptly instead of leaving it
+    // stuck for minutes.
+    this._pasteAndEnter(this._embedToken(safe, turn.token))
+      .catch((err) => {
+        if (turn.state !== 'done' && turn.state !== 'failed') {
+          turn.state = 'failed';
+        }
+        this._enqueuedTurns = this._enqueuedTurns.filter((t) => t !== turn);
+        this.emit('inject-fail', {
+          err: err.message,
+          msgId: msgId ?? null,
+          turnId: turn.turnId,
+          backend: 'tmux',
+        });
+      });
 
-    this.emit('inject-user-message', { text_len: safe.length, priority, shouldQuery });
+    this.emit('inject-user-message', { text_len: safe.length, priority, shouldQuery, msgId });
     return true;
   }
 
@@ -1003,6 +1746,13 @@ class TmuxProcess extends Process {
     this._killing = true;
     this.closed = true;
     this.drainQueue('KILLED');
+    // R5: release any pending paste-confirm waiters so a `_pasteAndEnter`
+    // blocked on JSONL confirmation settles instead of waiting out
+    // pasteConfirmMs against a dead session. Each `finish` resolves
+    // its promise and deletes its own Map entry.
+    for (const finish of [...this._pasteConfirms.values()]) {
+      try { finish(); } catch { /* swallow */ }
+    }
     if (this._sessionLogTail) {
       try { this._sessionLogTail.close(); } catch { /* swallow */ }
       this._sessionLogTail = null;
@@ -1019,4 +1769,5 @@ class TmuxProcess extends Process {
 
 module.exports = {
   TmuxProcess,
+  CLAUDE_CLI_PINNED_VERSION,
 };