@oar-sh/oar 0.9.2 → 0.9.3

package/server/claude-worker/claude-session-process.mjs

@@ -6,8 +6,10 @@ import { buildClaudeUserContent } from './claude-attachments.mjs';
 import {
   compactBoundaryActivityAction,
   createSdkMessageNormalizer,
+  displayToolName,
   formatApiRetryNotice,
   isSubagentToolName,
+  summarizeToolInput,
 } from './sdk-message-normalizer.mjs';
 import { digestFromRunRecord, digestFromJournal } from './workflow-progress-digest.mjs';
 import { createClaudeSessionRootResolver } from '../services/claude-session-root-service.mjs';
@@ -26,8 +28,21 @@ import {
 } from './claude-sdk-adapter.mjs';
 import { parseThinkingDisplay, parseThinkingEnabled } from '../../shared/claude-thinking.mjs';
 import { relocateClaudeTranscriptForCwd } from './claude-transcript-relocator.mjs';
-import { attemptFields, createClaudeTurnPublisher, isStaleAttemptError } from './claude-turn-publisher.mjs';
+import {
+  attemptFields,
+  buildSteerSettleFailure,
+  createClaudeTurnPublisher,
+  isStaleAttemptError,
+} from './claude-turn-publisher.mjs';
 import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
+import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
+import { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT } from '../../shared/steer-settle-markers.mjs';
+import { stripSteerNote, withSteerNoteContent } from '../../shared/steer-note.mjs';
+import {
+  stripSlashCommandGuard,
+  stripSlashCommandGuardContent,
+  withSlashCommandGuardContent,
+} from '../../shared/slash-command-guard.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -42,8 +57,11 @@ function modeAppendClass(relayMode) {
   return mode === 'ask' || mode === 'autopilot' ? mode : 'none';
 }
 
+export { STEER_FOLDED_TEXT, STEER_STOPPED_TEXT };
+
 /** Task types that run a model of their own (vs. bash/monitor/workflow). */
 const AGENT_TASK_TYPES = new Set(['local_agent', 'agent', 'subagent']);
+const MAX_TASK_TOOL_CALL_CHARS = 300;
 
 // ---------------------------------------------------------------------------
 // Workflow progress sources (CLI 2.1.226 on-disk formats)
@@ -265,13 +283,16 @@ function contentText(content) {
 function turnOpeningUserSignature(sdkMessage) {
   if (sdkMessage?.type !== 'user' || sdkMessage?.parent_tool_use_id) return null;
   const content = sdkMessage?.message?.content;
-  if (typeof content === 'string') return content;
+  // A steered push carries the hidden steer note, and a "/x" the slash-command
+  // guard (shared/slash-command-guard.mjs); every comparison is against the
+  // user's own text, so both are stripped here, once, for all of them.
+  if (typeof content === 'string') return stripSteerNote(stripSlashCommandGuard(content));
   if (!Array.isArray(content)) return null;
   if (content.some((block) => block?.type === 'tool_result')) return null;
   // Unlike turnOpeningUserText this keeps '' — an attachment-only message
   // replays with an empty text block, and the absorbed-steering match must
   // still recognize it (expectedText is '' for those too).
-  return contentText(content);
+  return stripSteerNote(contentText(stripSlashCommandGuardContent(content)));
 }
 
 function turnOpeningUserText(sdkMessage) {
@@ -405,6 +426,15 @@ export function createClaudeSessionRunner({
   // the slowest cold start observed; the primary absorbed-steering fix in
   // resolveContext should make this fire only for unknown variants.
   pendingDeliveredTimeoutMs = 5 * 60_000,
+  // How long a STEERED entry (pushed while a turn was already running) may sit
+  // unattached once the process goes idle before it is settled as merged into
+  // the turn it was folded into. The CLI folds a mid-turn push into the running
+  // turn and answers with one result on that turn, without replaying the
+  // steered text — so a short grace after idle (long enough to rule out the CLI
+  // opening its own turn for it, which it does immediately if at all) is all it
+  // takes to distinguish a fold from a queued run. Far below the watchdog so a
+  // folded row settles as answered, not failed with a "resend" error.
+  steeredFoldGraceMs = 2_000,
   // Backstop for the compaction hold. A compaction is announced ONCE by
   // `status: 'compacting'` (the CLI's periodic re-emit is gated on the
   // remote-control client's activity callback, which the plain SDK `query()`
@@ -422,9 +452,38 @@ export function createClaudeSessionRunner({
   // by the first turn to open regardless.
   compactReplayAdoptionMs = 60_000,
   continuationRetryDelayMs = 500,
+  // Backoff between attempts to save a consumed steer's settle marker (~31 s
+  // in all); after the last one the row fails terminally instead.
+  settleRetryDelaysMs = [1_000, 2_000, 4_000, 8_000, 8_000, 8_000],
+  // How many times the terminal failure itself is posted before the worker
+  // stops trying and hands the row to the relay via the heartbeat's
+  // `settleFailed` (a persistent HTTP error — say a 401 after a token change —
+  // would otherwise spin forever).
+  maxTerminalSettleAttempts = 5,
+  // After a Stop that cut off pushed steers, the CLI immediately opens a
+  // follow-up turn for them (a bare init, no user replay) that re-runs the
+  // interrupted tool call before answering (SDK probe 2026-09-24, CLI
+  // 2.1.281). A turn starting within this window of the Stop — or of the
+  // previous suppressed turn's end — is interrupted before it can do anything.
+  stopFollowUpWindowMs = 3_000,
+  // How long a stopped turn's row stays reported to the heartbeat after its
+  // interrupt and final publishes resolved (the abort ack is still landing),
+  // and the hard cap on that linger.
+  stoppedRowLingerMs = 5_000,
+  stoppedRowLingerMaxMs = 60_000,
+  // False while the connected relay does not understand the `steering-held`
+  // hand-back (a worker updated on disk before the relay restarted): a held
+  // delivery is then pushed the legacy way instead of being handed back into
+  // a retry-and-backoff requeue.
+  canHandBackHeldDelivery = () => true,
   workflowPollMs = 2_000,
   resolveWorkflowSessionDirImpl = null,
   askUserBridgeOptions = {},
+  // Called with `true`/`false` whenever the runner flips between accepting
+  // deliveries and holding them (see isDeliveryHeld). The worker wires it to
+  // the socket link: a hold withdraws the relay's readiness, and its end
+  // re-arms it at once so a held message steers into the resumed turn.
+  onDeliveryReadinessChange = () => {},
   dbg = () => {},
 } = {}) {
   const publisher = createClaudeTurnPublisher({
@@ -435,6 +494,35 @@ export function createClaudeSessionRunner({
   const resolveWorkflowSessionDir = resolveWorkflowSessionDirImpl || createDefaultWorkflowSessionDirResolver();
   let claudeNativeSessionId = '';
   let proc = null;
+  // Turn-opening deliveries between entry and push (adaptProcess and a cold
+  // spawn await in between); counted so a second delivery arriving in that
+  // gap is held instead of racing the first into the CLI.
+  let admittingDeliveries = 0;
+  // Settings re-inits (see the init handler). The window opens at
+  // adaptProcess's first control request — never when nothing changes — and
+  // closes when the delivery it serves is registered in pendingDelivered; the
+  // count is how many bare inits inside it are our own. A count, not a flag:
+  // a continuation the CLI opens inside the same window inits the same way,
+  // and ignoring every init there swallowed its boundary and swapped its
+  // answer with the delivered one. Over-counting (a request that never
+  // re-inits) only degrades to that. Some CLI paths merely mark the init
+  // stale and re-init when the pushed input is dequeued; that init lands
+  // after the window, in the delivered-row branch. Known gap: when that
+  // happens AND a continuation inits inside the window, the continuation's
+  // init is taken for ours and its answer attaches to the delivered row —
+  // the same misattribution as a continuation whose init follows the push.
+  let settingsReinitsOwed = 0;
+  let settingsWindowOpen = false;
+  let lastReportedDeliveryReady = true;
+  // Rows whose prompt the CLI consumed and whose settle marker is being saved
+  // (id → relay message). Runner-level, not per process: a process dying
+  // mid-settle must not drop them from the heartbeat's owned set.
+  const settlingMessages = new Map();
+  // id → terminalError for settling rows the worker gave up posting; reported
+  // in the heartbeat's `settleFailed` until the relay confirms it failed them.
+  const settleFailedTerminals = new Map();
+  // Row id → the latest in-flight /api/queue-consumed POST touching it.
+  const consumedMarkChains = new Map();
 
   async function persistNativeSessionId(conversationId, sessionId) {
     const normalized = String(sessionId || '').trim();
@@ -471,22 +559,103 @@ export function createClaudeSessionRunner({
   }
 
   // Every queue row this worker currently owes work for, as { id, attemptId }
-  // entries: the running turn (delivered or continuation) plus any delivered
-  // message queued behind it. The heartbeat reports all of them (id-only — its
-  // call site unwraps) so the server's owner-recovery never replays a row the
-  // process still holds; the crash guard takes the entries whole so its
-  // requeues stay fenced to this attempt.
+  // entries: the running turn (delivered or continuation), any delivered
+  // message queued behind it, and every consumed steer whose settle marker is
+  // still being saved. The heartbeat reports all of them (id-only — its call
+  // site unwraps) so the server's owner-recovery never replays a row the
+  // worker still holds; the crash guard takes the entries whole so its
+  // requeues stay fenced to this attempt — and a settling row carries the
+  // terminal failure the guard must send instead of a requeue, because its
+  // prompt must never run twice.
   function getActiveQueueMessageIds() {
-    if (!proc) return [];
-    return [
-      proc.activeCtx?.message,
-      ...proc.pendingDelivered.map((entry) => entry.ctx.message),
-    ]
-      .map((message) => ({
+    const live = proc
+      ? [proc.activeCtx?.message, ...proc.pendingDelivered.map((entry) => entry.ctx.message)]
+      : [];
+    const entries = live.map((message) => ({
+      id: String(message?.id || '').trim(),
+      attemptId: message?.attemptId || null,
+    }));
+    // A stopped row whose abort ack has not landed yet: the crash guard (and
+    // SIGTERM) must fail it the way the ack would, never requeue it — that
+    // would re-run a prompt the user explicitly stopped.
+    for (const { message } of lingeringStopped.values()) {
+      entries.push({
         id: String(message?.id || '').trim(),
         attemptId: message?.attemptId || null,
-      }))
+        terminalError: buildRelayStopFailure(),
+      });
+    }
+    for (const { message, variant } of settlingMessages.values()) {
+      entries.push({
+        id: String(message?.id || '').trim(),
+        attemptId: message?.attemptId || null,
+        terminalError: buildSteerSettleFailure(message, { variant, agentLabel: 'Claude' }),
+      });
+    }
+    return entries.filter((entry) => entry.id);
+  }
+
+  /**
+   * Claim a consumed row as settling — synchronously, BEFORE whatever detaches
+   * it from pendingDelivered/activeCtx, so no heartbeat can see it unowned.
+   * `variant` picks the terminal wording should its settle never land.
+   */
+  function claimSettling(message, variant = 'folded') {
+    const id = String(message?.id || '').trim();
+    if (id && !settlingMessages.has(id)) settlingMessages.set(id, { message, variant });
+  }
+
+  /**
+   * Mark rows whose prompt the CLI has taken as consumed on the relay, for the
+   * paths where no response carries the mark (a stopped turn, a handoff).
+   * Best-effort: the worker's own settle still owns these rows while it lives;
+   * the mark only protects them when it does not.
+   */
+  function markConsumed(conversationId, entries = [], { consumed = true } = {}) {
+    const rows = entries
+      .map((entry) => ({ id: String(entry?.id || '').trim(), attemptId: entry?.attemptId || null }))
       .filter((entry) => entry.id);
+    if (!rows.length) return Promise.resolve();
+    // Per-row ordering: a stopped turn's mark and the un-mark of a steer that
+    // then runs its own turn are separate fire-and-forget POSTs, and must
+    // reach the relay in the order they were decided.
+    const previous = Promise.allSettled(rows.map((row) => consumedMarkChains.get(row.id)).filter(Boolean));
+    const post = previous.then(() => api('POST', '/api/queue-consumed', {
+      conversationId: String(conversationId || sdkSessionId || ''),
+      entries: rows,
+      ...(consumed ? {} : { consumed: false }),
+    })).catch((error) => {
+      dbg('consumed mark failed', rows.map((entry) => entry.id).join(','), error?.message || String(error));
+    });
+    for (const row of rows) consumedMarkChains.set(row.id, post);
+    post.then(() => {
+      for (const row of rows) if (consumedMarkChains.get(row.id) === post) consumedMarkChains.delete(row.id);
+    });
+    return post;
+  }
+
+
+  /** Release a settled row — unless it was handed to the relay to fail. */
+  function releaseSettling(id) {
+    const key = String(id || '').trim();
+    if (!settleFailedTerminals.has(key)) settlingMessages.delete(key);
+  }
+
+  /** Heartbeat payload: rows whose terminal failure the relay must post. */
+  function getSettleFailed() {
+    return [...settleFailedTerminals.entries()].map(([id, terminalError]) => ({
+      id,
+      attemptId: settlingMessages.get(id)?.message?.attemptId || null,
+      terminalError,
+    }));
+  }
+
+  function acknowledgeSettleFailed(ids = []) {
+    for (const id of ids) {
+      const key = String(id || '').trim();
+      if (!settleFailedTerminals.delete(key)) continue;
+      settlingMessages.delete(key);
+    }
   }
 
   function isTurnActive() {
@@ -524,6 +693,7 @@ export function createClaudeSessionRunner({
       discarded: false,
       registered: kind === 'delivered',
       bufferedActions: [],
+      resultBuffered: false,
       controlState: null,
       finalized: false,
       resolveDone: null,
@@ -547,6 +717,7 @@ export function createClaudeSessionRunner({
     proc.continuationInitPending = false;
     proc.notificationPendingAt = 0;
     proc.taskSettledAt = 0;
+    proc.lastApiRetryAt = 0;
     if (proc.initModel && !ctx.state.responseModel) ctx.state.responseModel = proc.initModel;
     ctx.controlState = controlPoller?.start?.({
       queueMessageId: ctx.message?.id || '',
@@ -580,13 +751,33 @@ export function createClaudeSessionRunner({
    * back to back can replay out of order, and pairing by position alone would
    * answer each with the other's turn.
    */
-  function attachDeliveredContext(index = 0) {
+  function attachDeliveredContext(index = 0, { provisional = false } = {}) {
     const [entry] = proc.pendingDelivered.splice(index, 1);
     entry.ctx.deliveredEntry = entry;
+    // A provisional (post-compaction) attach may still be unwound back onto
+    // the queue; its un-mark waits for the adoption to commit.
+    if (!provisional) unmarkConsumedOnOwnTurn(entry);
     activateContext(entry.ctx);
     return entry.ctx;
   }
 
+  /**
+   * A steer marked consumed by the turn it was pushed into, now running as a
+   * turn of its own: from here it is an ordinary in-flight row, and a worker
+   * death mid-turn must not fail it with "check the reply above".
+   */
+  function unmarkConsumedOnOwnTurn(entry) {
+    if (!entry?.consumedMarked) return;
+    entry.consumedMarked = false;
+    markConsumed(entry.ctx.message?.conversationId, [entry.ctx.message], { consumed: false });
+  }
+
+  /** A provisional post-compaction adoption became final. */
+  function commitAdoption(ctx) {
+    ctx.adoptedFromCompaction = false;
+    unmarkConsumedOnOwnTurn(ctx.deliveredEntry);
+  }
+
   /**
    * Undo a post-compaction adoption: this turn was never the delivered
    * message's, and nothing has published on it (the provisional flag is
@@ -619,6 +810,9 @@ export function createClaudeSessionRunner({
     // not to the row: left set, `finalizeContext` would take its interrupted
     // branch when the row finally runs for real and publish no response at all.
     ctx.interrupted = false;
+    // Nothing will close this context as a stopped turn now, so a Stop guard
+    // armed by that abort opens its window here instead.
+    anchorStopFollowUpWindow();
     controlPoller?.stop?.(ctx.controlState);
     ctx.controlState = null;
     const entry = ctx.deliveredEntry;
@@ -765,6 +959,22 @@ export function createClaudeSessionRunner({
         if (absorbed >= 0) {
           const outgoing = proc.activeCtx;
           const restored = outgoing.adoptedFromCompaction;
+          // A continuation whose turn already ENDED — its result is buffered,
+          // only waiting on its row's registration — was not interrupted by
+          // this replay: the replay opens the delivered message's own turn.
+          // Handing off would discard the continuation and its buffered
+          // answer with it. Let the registration publish that answer on the
+          // continuation row first; the delivered message gets a fresh turn.
+          const finishedContinuation = !restored
+            && outgoing.kind === 'continuation'
+            && !outgoing.registered
+            && !outgoing.discarded
+            && outgoing.resultBuffered === true;
+          if (finishedContinuation) {
+            detachActiveContext(outgoing);
+            proc.handoffSettling = waitForContextRegistration(outgoing);
+            return attachDeliveredContext(absorbed);
+          }
           if (restored) {
             // The outgoing context was only PROVISIONALLY adopted and has
             // published nothing. Settling it as an absorbed turn would tell
@@ -807,7 +1017,7 @@ export function createClaudeSessionRunner({
         // this prompt" — after this replay that premise is false, and putting
         // the row back would fail or re-run a message the CLI already took.
         if (signature !== null && signature === proc.activeCtx.deliveredEntry?.expectedText) {
-          proc.activeCtx.adoptedFromCompaction = false;
+          commitAdoption(proc.activeCtx);
           return proc.activeCtx;
         }
         if (signature !== null && isTaskNotificationReplay(sdkMessage)) {
@@ -839,7 +1049,7 @@ export function createClaudeSessionRunner({
         // lifecycle timer a window to reap a context that is already settling.
         if (!sdkMessage?.parent_tool_use_id
           && (type === 'assistant' || type === 'stream_event' || type === 'result')) {
-          proc.activeCtx.adoptedFromCompaction = false;
+          commitAdoption(proc.activeCtx);
         }
       }
       return proc.activeCtx;
@@ -879,7 +1089,7 @@ export function createClaudeSessionRunner({
         && Date.now() < proc.compactReplayUntil
         && isCompactionReplayCandidate(sdkMessage)
       ) {
-        const ctx = attachDeliveredContext();
+        const ctx = attachDeliveredContext(0, { provisional: true });
         // Provisional: the summary row alone cannot rule out a continuation
         // whose notification replays after it (see the hand-back above).
         ctx.adoptedFromCompaction = true;
@@ -894,7 +1104,12 @@ export function createClaudeSessionRunner({
 
     if (type === 'assistant' || type === 'stream_event' || type === 'user') {
       if (proc.lastBoundary !== 'self-opened') {
-        if (proc.pendingDelivered.length) return attachDeliveredContext();
+        // A background subagent's frames arrive at top level carrying
+        // `parent_tool_use_id` (same marker the adoption commit checks): they
+        // are a LIVE task's chatter, not the delivered message's turn, and
+        // attaching on them would both publish the wrong output and splice the
+        // entry out of the fold reaper's reach.
+        if (proc.pendingDelivered.length && !sdkMessage?.parent_tool_use_id) return attachDeliveredContext();
         // Between-turn chatter — a background subagent's stream, a stray
         // top-level tool_result — is not a turn of its own. Only traffic that
         // follows a self-opened boundary (the CLI's task-notification replay)
@@ -911,7 +1126,9 @@ export function createClaudeSessionRunner({
         proc.lastBoundary = null;
         return null;
       }
-      if (proc.lastBoundary !== 'self-opened' && proc.pendingDelivered.length) return attachDeliveredContext();
+      if (proc.lastBoundary !== 'self-opened' && proc.pendingDelivered.length && !sdkMessage?.parent_tool_use_id) {
+        return attachDeliveredContext();
+      }
       if (proc.lastBoundary === 'self-opened') return openContinuationContext();
       return null;
     }
@@ -932,6 +1149,9 @@ export function createClaudeSessionRunner({
     }
     if (!ctx.registered) {
       ctx.bufferedActions.push(action);
+      // Kept as a flag, not read off the buffer: the registration drain
+      // splices batches out of it while they publish.
+      if (action.channel === 'result') ctx.resultBuffered = true;
       return;
     }
     await publisher.dispatchAction(ctx.message, action, ctx.state);
@@ -946,6 +1166,44 @@ export function createClaudeSessionRunner({
     // and model fallbacks must survive that.
     const turnRef = proc?.turn || null;
     const procModel = proc?.model || null;
+    // Steers pushed into this turn and still unsettled: the CLI has their
+    // prompts, so the relay marks them consumed with this turn's commit and
+    // never re-runs them even if this worker dies before settling them.
+    // Only while this turn is still the active one: a continuation finalizing
+    // late from its registration drain (see the finished-continuation path in
+    // resolveContext) no longer owns the steers pending behind a newer turn.
+    const consumedEntries = (proc?.activeCtx === ctx ? proc.pendingDelivered : []).filter((entry) => entry.steered);
+    for (const entry of consumedEntries) entry.consumedMarked = true;
+    const consumedSteerIds = consumedEntries
+      .map((entry) => ({ id: String(entry.ctx.message?.id || '').trim(), attemptId: entry.ctx.message?.attemptId || null }))
+      .filter((entry) => entry.id);
+
+    if (ctx.interrupted || proc?.aborted) {
+      // A stopped turn closes FIRST and publishes after, off the stream loop:
+      // the CLI opens its follow-up turn for any pushed steers right after
+      // the interrupt, and the Stop guard can only kill that turn at its init
+      // if the loop reaches the init promptly — the usage reads (an
+      // experimental control request with a 10 s timeout) and relay POSTs
+      // would otherwise sit in front of it. Same shape as the per-turn
+      // runner's abort path otherwise: surface what streamed, let the
+      // server-side abort control own the queue row's fate.
+      markConsumed(ctx.message?.conversationId, consumedSteerIds);
+      const publishChain = (async () => {
+        await publisher.publishFinalStream(ctx.message, ctx.state.lastStreamedText);
+        const [contextUsage, planUsage] = await Promise.all([
+          readContextUsageImpl(turnRef, dbg),
+          readPlanUsageImpl(turnRef, dbg),
+        ]);
+        ctx.state.contextUsage = contextUsage;
+        ctx.state.planUsage = planUsage;
+        await publisher.publishContextUsage({ message: ctx.message, state: ctx.state, model: procModel, sdkSessionId });
+        await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId });
+      })().catch((error) => dbg('stopped-turn publish failed', error?.message || String(error)));
+      lingerStoppedRow(ctx, publishChain);
+      closeContext(ctx, true);
+      return;
+    }
+
     // The control transport is alive for the process's whole life now, but
     // the snapshot still belongs to this turn's finalize so the composer
     // indicator updates with each reply.
@@ -959,18 +1217,15 @@ export function createClaudeSessionRunner({
     await publisher.publishContextUsage({ message: ctx.message, state: ctx.state, model: procModel, sdkSessionId });
     await publisher.publishPlanUsage({ message: ctx.message, state: ctx.state, sdkSessionId });
 
-    if (ctx.interrupted || proc?.aborted) {
-      // Same shape as the per-turn runner's abort path: surface what streamed,
-      // let the server-side abort control own the queue row's fate.
-      await publisher.publishFinalStream(ctx.message, ctx.state.lastStreamedText);
-    } else if (ctx.state.result?.isError) {
-      await publisher.publishErrorResult({ message: ctx.message, state: ctx.state, responseModel });
+    if (ctx.state.result?.isError) {
+      await publisher.publishErrorResult({ message: ctx.message, state: ctx.state, responseModel, consumedSteerIds });
     } else {
       await publisher.publishCompletedTurn({
         message: ctx.message,
         state: ctx.state,
         responseModel,
         planBoardPosted: ctx.planBoardPosted,
+        consumedSteerIds,
       });
     }
     closeContext(ctx, true);
@@ -1019,13 +1274,19 @@ export function createClaudeSessionRunner({
     if (proc && proc.activeCtx === ctx) {
       proc.activeCtx = null;
       proc.lastBoundary = null;
+      proc.settleSeqAtTurnEnd = proc.taskSettleSeq;
     }
   }
 
   function closeContext(ctx, handled) {
+    // The Stop guard's window runs from the stopped turn's END: the CLI opens
+    // its follow-up right after the interrupted result, and anything slow in
+    // between must not eat the window.
+    if (ctx.interrupted) anchorStopFollowUpWindow();
     detachActiveContext(ctx);
     ctx.resolveDone?.(handled);
     evaluateLifecycle();
+    syncDeliveryReadiness();
   }
 
   /**
@@ -1033,9 +1294,21 @@ export function createClaudeSessionRunner({
    * active context NOW. The caller attaches the delivered context
    * synchronously; onSdkMessage awaits the returned promise before
    * dispatching the new context's actions so the two rows' publishes stay
-   * ordered.
+   * ordered. That promise resolves after the settle's FIRST publish attempt,
+   * not the whole retry ladder: onSdkMessage runs inside the SDK stream loop,
+   * and waiting out ~30 s of retries there froze the new turn's stream. A
+   * failed first attempt keeps retrying in the background with the row still
+   * owned (settling).
    */
   function handoffAbsorbedTurn(ctx) {
+    // Claimed as settling BEFORE the detach: from the detach on nothing else
+    // reports this row, and a heartbeat landing in between would recover it
+    // and re-run a prompt the CLI already consumed.
+    const delivered = ctx.kind === 'delivered' && Boolean(ctx.message?.id);
+    if (delivered) {
+      claimSettling(ctx.message, 'handoff');
+      markConsumed(ctx.message.conversationId, [ctx.message]);
+    }
     detachActiveContext(ctx);
     if (ctx.kind === 'continuation' && !ctx.registered) {
       // Registration (or its buffered-action drain) is still in flight:
@@ -1049,12 +1322,18 @@ export function createClaudeSessionRunner({
     // so reading it later would see the absorbed turn's text too.
     const fallbackText = String(ctx.state.lastStreamedText || ctx.normalizer.finalStreamText() || '').trim();
     dbg('active turn absorbed a delivered message; handing off', ctx.message?.id || '(unregistered continuation)');
-    return settleHandedOffContext(ctx, fallbackText).catch((error) => {
+    let releaseOrder = () => {};
+    const firstAttempt = new Promise((resolve) => { releaseOrder = resolve; });
+    settleHandedOffContext(ctx, fallbackText, { onFirstAttempt: () => releaseOrder() }).catch((error) => {
       dbg('absorbed-turn handoff settle failed', error?.message || String(error));
+    }).finally(() => {
+      releaseOrder();
+      if (delivered) releaseSettling(ctx.message.id);
     });
+    return firstAttempt;
   }
 
-  async function settleHandedOffContext(ctx, fallbackText) {
+  async function settleHandedOffContext(ctx, fallbackText, { onFirstAttempt = () => {} } = {}) {
     if (ctx.finalized) return;
     ctx.finalized = true;
     controlPoller?.stop?.(ctx.controlState);
@@ -1075,11 +1354,14 @@ export function createClaudeSessionRunner({
       // NEVER requeue an absorbed delivered row: the CLI already consumed
       // the prompt into the running turn — re-delivery would execute it a
       // second time (and the requeue route marks the healthy worker errored).
-      const text = fallbackText
-        ? `${fallbackText}\n\n_(This turn was merged into the next message — the reply continues there.)_`
-        : '_(This turn was merged into the next message — see the following reply.)_';
+      // `absorbed: true` becomes `kind='absorbed'` on the assistant message,
+      // and the transcript renders the reply as continuing through the next
+      // (steered) user message — so the text carries no prose note when
+      // something streamed; the empty case keeps one so an exported or
+      // marker-blind view still explains the stub.
+      const text = fallbackText || '_(Answered together with the next message.)_';
       await publisher.publishFinalStream(ctx.message, text);
-      await publisher.publishResponse(ctx.message, { text, model });
+      await publishSettleMarker(ctx.message, { text, model, kind: 'absorbed', variant: 'handoff', onFirstAttempt });
     } else if (fallbackText) {
       await publisher.publishFinalStream(ctx.message, fallbackText);
       await publisher.publishResponse(ctx.message, { text: fallbackText, model });
@@ -1092,8 +1374,83 @@ export function createClaudeSessionRunner({
     closeContext(ctx, true);
   }
 
-  async function interruptActiveTurn(ctx) {
+  function anchorStopFollowUpWindow() {
+    if (!proc?.stopFollowUp || proc.stopFollowUp.anchored) return;
+    proc.stopFollowUp.anchored = true;
+    proc.stopFollowUp.until = Date.now() + stopFollowUpWindowMs;
+  }
+
+  /**
+   * The stopped turn's row until the Stop has fully landed: the context closes
+   * on the interrupted result, but the row stays `processing` until the
+   * control poller's abort ack reaches the relay — sent only after the
+   * interrupt call resolves, which races that result. Reported to the
+   * heartbeat meanwhile, or an owner-heartbeat recovery in the gap fails a
+   * streamed row with the wrong wording, or requeues (re-runs) one that
+   * produced nothing yet.
+   */
+  const lingeringStopped = new Map();
+
+  function lingerStoppedRow(ctx, publishChain) {
+    const id = String(ctx.message?.id || '').trim();
+    if (!id || ctx.kind !== 'delivered') return;
+    const token = {};
+    lingeringStopped.set(id, { message: ctx.message, token });
+    const release = () => {
+      if (lingeringStopped.get(id)?.token === token) lingeringStopped.delete(id);
+    };
+    const cap = setTimeout(release, stoppedRowLingerMaxMs);
+    cap.unref?.();
+    Promise.allSettled([publishChain, ctx.interruptDone || Promise.resolve()])
+      // The ack POST starts right after the interrupt resolves; give it time.
+      .then(() => new Promise((resolve) => {
+        const timer = setTimeout(resolve, stoppedRowLingerMs);
+        timer.unref?.();
+      }))
+      .then(() => {
+        clearTimeout(cap);
+        release();
+      });
+  }
+
+  function interruptActiveTurn(ctx) {
+    ctx.interruptDone = runInterrupt(ctx);
+    return ctx.interruptDone;
+  }
+
+  async function runInterrupt(ctx) {
     ctx.interrupted = true;
+    // Steers already pushed into the turn being stopped went with it: if the
+    // CLI does not open a turn of its own for one, it settles as 'stopped',
+    // not as handled by the reply the Stop cut short. Still never requeued —
+    // the CLI saw the prompt (2026-09-20 decision).
+    let stoppedSteers = 0;
+    for (const entry of proc?.pendingDelivered || []) {
+      if (!entry.steered) continue;
+      entry.stoppedWithTurn = true;
+      stoppedSteers += 1;
+    }
+    if (proc && stoppedSteers) {
+      // The CLI re-opens a turn for the queued steers right after the
+      // interrupt — re-running the stopped tool call — so the Stop would not
+      // stick. Arm the guard that interrupts those follow-up turns (see
+      // maybeSuppressStopFollowUp). The window opens when the stopped turn
+      // closes (closeContext anchors it). A task that settled before the Stop
+      // may have its continuation queued in the CLI already: then the next
+      // turn is ambiguous and the guard only stands down (it is never killed).
+      proc.stopFollowUp = {
+        settleSeq: proc.taskSettleSeq,
+        until: Number.POSITIVE_INFINITY,
+        anchored: false,
+        remaining: stoppedSteers,
+        standDown: isContinuationImminent(),
+      };
+    }
+    // A late abort (the control poller does not re-check after its GET) can
+    // land on a context that has already closed: nothing will anchor the
+    // window at close, so it opens now.
+    if (ctx.finalized || ctx !== proc?.activeCtx) anchorStopFollowUpWindow();
+    syncDeliveryReadiness();
     try {
       await proc.turn.interrupt();
     } catch (error) {
@@ -1133,7 +1490,8 @@ export function createClaudeSessionRunner({
         // the next publish. Bash & co. get no model at all.
         const agentLike = AGENT_TASK_TYPES.has(String(task.taskType || ''));
         const pinnedModel = (task.toolUseId && processRef.subagentSpawns.get(task.toolUseId)) || '';
-        const model = agentLike ? (pinnedModel || processRef.initModel || null) : null;
+        const activity = (task.toolUseId && processRef.subagentActivity.get(task.toolUseId)) || {};
+        const model = agentLike ? (activity.model || pinnedModel || processRef.initModel || null) : null;
         return {
           taskId,
           taskType: task.taskType,
@@ -1141,11 +1499,12 @@ export function createClaudeSessionRunner({
           startedAt: task.startedAt || null,
           summary: task.summary || null,
           lastToolName: task.lastToolName || null,
+          lastToolCall: (agentLike && activity.lastToolCall) || null,
           totalTokens: task.totalTokens ?? null,
           toolUseId: task.toolUseId || null,
           subagentType: task.subagentType || null,
           model,
-          modelInherited: Boolean(model && !pinnedModel),
+          modelInherited: Boolean(model && !pinnedModel && !activity.model),
           // The workflow digest (poller below) rides the same row; the relay
           // sanitizer whitelists and re-clamps it before storing.
           ...(task.workflowProgress ? { workflowProgress: task.workflowProgress } : {}),
@@ -1450,6 +1809,43 @@ export function createClaudeSessionRunner({
     }
   }
 
+  // A subagent's own assistant frames (parent_tool_use_id = the spawning
+  // tool_use id, the same key as task.toolUseId) carry what the task events
+  // never do: the API model that actually answers (a spawn pin is only an
+  // alias like "opus") and the full input of the tool it is calling now.
+  // Single-lined and capped: the panel crops it to its width.
+  function recordSubagentActivity(sdkMessage) {
+    const parentId = String(sdkMessage?.parent_tool_use_id || '').trim();
+    if (!parentId) return;
+    const entry = proc.subagentActivity.get(parentId) || {};
+    const before = `${entry.model || ''}\n${entry.lastToolCall || ''}`;
+    const model = String(sdkMessage?.message?.model || '').trim();
+    if (model && model !== '<synthetic>') entry.model = model;
+    const blocks = Array.isArray(sdkMessage?.message?.content) ? sdkMessage.message.content : [];
+    for (const block of blocks) {
+      if (block?.type === 'tool_use') {
+        const toolName = displayToolName(block.name) || 'tool';
+        const summary = summarizeToolInput(toolName, block.input).replace(/\s+/g, ' ').trim();
+        entry.lastToolCall = (summary ? `Tool (${toolName}): ${summary}` : `Tool (${toolName})`)
+          .slice(0, MAX_TASK_TOOL_CALL_CHARS);
+      } else if (block?.type === 'text' && String(block.text || '').trim()) {
+        // Writing prose means the last tool call is over; the panel falls
+        // back to the SDK's progress summary instead of a stale command.
+        entry.lastToolCall = null;
+      }
+    }
+    proc.subagentActivity.delete(parentId);
+    proc.subagentActivity.set(parentId, entry);
+    while (proc.subagentActivity.size > 100) {
+      proc.subagentActivity.delete(proc.subagentActivity.keys().next().value);
+    }
+    // Foreground subagents stream the same frames; only a change on a live
+    // background task is worth a publish (and a panel re-render).
+    if (before === `${entry.model || ''}\n${entry.lastToolCall || ''}`) return;
+    const ownsLiveTask = [...proc.liveTasks.values()].some((task) => task.toolUseId === parentId);
+    if (ownsLiveTask) publishBackgroundTasks({ throttled: true });
+  }
+
   // Between-turn notices carried into the next activated context, as either a
   // plain line or a prepared publisher action (a compaction boundary has to
   // keep the structured metadata the transcript's break row is built from —
@@ -1518,6 +1914,7 @@ export function createClaudeSessionRunner({
     const type = String(sdkMessage?.type || '');
     if (type === 'assistant') {
       recordSubagentSpawns(sdkMessage);
+      recordSubagentActivity(sdkMessage);
       return;
     }
     if (type !== 'system') return;
@@ -1550,7 +1947,20 @@ export function createClaudeSessionRunner({
       // of the async stream consumer), so it is correctly excluded here.
       //
       if (!proc.activeCtx && !proc.pendingDelivered.length) {
-        proc.lastBoundary = 'self-opened';
+        // Not a re-init a settings change caused: setModel /
+        // setPermissionMode / applyFlagSettings make the CLI re-init (live
+        // probe, CLI 2.1.281), and adaptProcess issues them BEFORE the
+        // delivery they belong to is registered and pushed. Reading that
+        // init as self-opened routed the whole answer to a continuation row
+        // and stranded the delivered message (conv dad758cd, 2026-09-25,
+        // right after a /model switch). Inside that window an init beyond the
+        // ones owed is a continuation only if a task settled since the last
+        // turn ended — a stray extra re-init must not strand the delivery the
+        // same way.
+        if (settingsReinitsOwed > 0) settingsReinitsOwed -= 1;
+        else if (!settingsWindowOpen || proc.taskSettleSeq !== proc.settleSeqAtTurnEnd) {
+          proc.lastBoundary = 'self-opened';
+        }
       } else if (!proc.activeCtx && !firstInit) {
         // A LATER init, with a delivered row waiting, is the CLI opening a turn
         // of its own — the live-verified continuation shape is a bare init with
@@ -1667,6 +2077,17 @@ export function createClaudeSessionRunner({
           if (typeof last === 'string' && last.startsWith('Anthropic API')) proc.pendingActivities.pop();
           carryPendingActivity(notice);
         }
+        // A retry with no active turn means the CLI is mid-request for a turn
+        // it is about to open — likely for a pending delivered entry. Hold the
+        // fold clock so the entry is not settled as "merged" out from under
+        // the turn that will answer it. The hold must be a freshness window,
+        // not just a clock reset: a 529 backoff routinely exceeds the 2s fold
+        // grace, so a reset alone would re-arm and fire between notices.
+        proc.lastApiRetryAt = Date.now();
+        for (const entry of proc.pendingDelivered) {
+          entry.foldSince = 0;
+          entry.unattachedSince = 0;
+        }
       }
       return;
     }
@@ -1705,6 +2126,7 @@ export function createClaudeSessionRunner({
       for (const taskId of previous.keys()) {
         if (!proc.liveTasks.has(taskId)) {
           proc.taskSettledAt = Date.now();
+          proc.taskSettleSeq += 1;
           break;
         }
       }
@@ -1765,6 +2187,7 @@ export function createClaudeSessionRunner({
       // continuation is coming, so nothing should pin the process for one.
       if (taskId && proc.knownTasks.has(taskId) && sdkMessage.skip_transcript !== true) {
         proc.notificationPendingAt = Date.now();
+        proc.taskSettleSeq += 1;
       }
       if (!activeContextPublishes()) {
         const status = String(sdkMessage.status || '').trim() || 'unknown';
@@ -1778,6 +2201,82 @@ export function createClaudeSessionRunner({
     }
   }
 
+  /**
+   * A turn the CLI opens by itself right now would follow the Stop: the
+   * guard is live, no turn is active, and everything still pending was
+   * stopped with the turn (a message delivered after the Stop is held, never
+   * pushed — and pushing one disarms the guard).
+   */
+  function isStopFollowUpPosition(now = Date.now()) {
+    const guard = proc?.stopFollowUp;
+    if (!guard || guard.remaining <= 0 || now >= guard.until) return false;
+    if (proc.activeCtx) return false;
+    return proc.pendingDelivered.length > 0 && proc.pendingDelivered.every((entry) => entry.stoppedWithTurn);
+  }
+
+  /**
+   * ...and that turn can only be the follow-up for the stopped steers: no
+   * background task has settled since the Stop, and none was about to
+   * continue when it happened (either one's continuation opens the same
+   * bare-init way, and must run).
+   */
+  function isStopFollowUpArmed(now = Date.now()) {
+    if (!isStopFollowUpPosition(now)) return false;
+    const guard = proc.stopFollowUp;
+    // A counter, not the settle timestamps: a settle in the Stop's own
+    // millisecond must still count as after it.
+    return !guard.standDown && proc.taskSettleSeq === guard.settleSeq;
+  }
+
+  function isStopFollowUpPending(now = Date.now()) {
+    return Boolean(proc?.suppressingTurn) || isStopFollowUpArmed(now);
+  }
+
+  /**
+   * Kill the CLI's follow-up turn for steers the user stopped. Without this
+   * the Stop does not stick: the follow-up re-runs the interrupted tool call
+   * and answers the steers on a phantom continuation. Interrupting it at its
+   * init ends it with an error result and no model output (SDK probe
+   * 2026-09-24). Everything that turn emits is swallowed — its error result
+   * must not settle a stopped steer as a failed turn — except process-level
+   * frames (task bookkeeping, background subagents' streams). Returns
+   * 'swallow', 'observe-only', 'continuation' (the guard stood down: the turn
+   * is a task's continuation and must open as one rather than attach to a
+   * stopped steer's row), or null for a message to handle normally.
+   */
+  function maybeSuppressStopFollowUp(sdkMessage) {
+    const type = String(sdkMessage?.type || '');
+    const subtype = String(sdkMessage?.subtype || '');
+    if (proc.suppressingTurn) {
+      // A background subagent's frames belong to a live task, not the turn.
+      if (sdkMessage?.parent_tool_use_id) return 'observe-only';
+      if (type === 'result') {
+        proc.suppressingTurn = false;
+        // Several stopped steers may come back as several turns: the next
+        // one gets its own window from this one's end.
+        if (proc.stopFollowUp) proc.stopFollowUp.until = Date.now() + stopFollowUpWindowMs;
+        dbg('stopped-steer follow-up turn ended');
+        return 'swallow';
+      }
+      return type === 'system' && subtype !== 'init' ? 'observe-only' : 'swallow';
+    }
+    if (type !== 'system' || subtype !== 'init' || !isStopFollowUpPosition()) return null;
+    if (!isStopFollowUpArmed()) {
+      // Stood down for a task continuation: spent, and the turn is the task's.
+      proc.stopFollowUp = null;
+      dbg('stop guard stood down for a task continuation');
+      return 'continuation';
+    }
+    proc.suppressingTurn = true;
+    proc.stopFollowUp.remaining -= 1;
+    dbg('interrupting the CLI follow-up turn for steers the user stopped');
+    const turnRef = proc.turn;
+    Promise.resolve()
+      .then(() => turnRef?.interrupt?.())
+      .catch((error) => dbg('follow-up interrupt failed', error?.message || String(error)));
+    return 'swallow';
+  }
+
   async function onSdkMessage(processRef, sdkMessage) {
     // A superseded process (push-race respawn, mode-recycle timeout) may still
     // be draining its stream; its late messages must not mutate the state of
@@ -1785,7 +2284,13 @@ export function createClaudeSessionRunner({
     // cleanupProcess when the old stream ends.
     if (!proc || proc !== processRef) return;
     proc.lastEventAt = Date.now();
+    const suppressed = maybeSuppressStopFollowUp(sdkMessage);
+    if (suppressed === 'swallow') return;
     observeProcessLevel(sdkMessage);
+    if (suppressed === 'observe-only') return;
+    // Its traffic opens a continuation of its own instead of attaching to the
+    // stopped steer waiting in pendingDelivered (which still settles stopped).
+    if (suppressed === 'continuation') proc.lastBoundary = 'self-opened';
     const ctx = resolveContext(sdkMessage);
     if (proc.handoffSettling) {
       // An absorbed-steering handoff just settled the previous context;
@@ -1816,6 +2321,17 @@ export function createClaudeSessionRunner({
     return fresh(proc.notificationPendingAt) || fresh(proc.taskSettledAt);
   }
 
+  /**
+   * The CLI recently reported an API retry with no turn open: it is
+   * mid-request for a turn it has not opened yet (retry backoffs run tens of
+   * seconds), so the fold/stale reapers must not settle a pending delivered
+   * entry out from under it. Cleared when a turn opens (activateContext).
+   */
+  function isApiRetryPending() {
+    if (!proc) return false;
+    return Boolean(proc.lastApiRetryAt) && Date.now() - proc.lastApiRetryAt < notificationGraceMs;
+  }
+
   function hasLiveWork() {
     if (!proc) return false;
     return Boolean(
@@ -1867,14 +2383,188 @@ export function createClaudeSessionRunner({
     restoreAdoptedContext(ctx);
   }
 
+  /**
+   * Settle steered entries the CLI folded into a turn without replaying them.
+   * A mid-turn push is folded into the running turn and answered by that turn's
+   * single result — the steered entry never gets its own replay, so
+   * resolveContext's absorbed-steering handoff never fires and the entry would
+   * otherwise sit until the 5-minute watchdog fails it with a bogus "resend".
+   * Once nothing turn-shaped could still attach the entry (no active turn, no
+   * control round-trip, no compaction, no imminent task continuation — but
+   * deliberately NOT "no live background tasks", see the gate comment) for the
+   * short fold grace, settle it as merged into the reply it was folded into.
+   */
+  function reapFoldedSteeredEntries(now) {
+    if (!proc || !proc.pendingDelivered.length) return;
+    if (!(steeredFoldGraceMs > 0)) return;
+    if (!proc.sawInit) return;
+    // Live background tasks deliberately do NOT hold the fold clock: a task
+    // can run for an hour and the CLI opens turns for pushed messages
+    // regardless, so a steered entry folded into an already-finished turn
+    // would otherwise sit `processing` — steer slot occupied, worker.ready
+    // suppressed, every later message in the conversation stuck behind it —
+    // until the task exits (live 2026-09-20: a hung 35-minute Bash task
+    // wedged exactly this way). If the CLI is instead going to open a real
+    // turn for the push, it does so within the grace, tasks or no tasks.
+    // A task that just SETTLED is different: its continuation turn is about
+    // to dequeue and may replay the steered text, so that window holds the
+    // clock (isContinuationImminent). So does a fresh API retry notice: the
+    // CLI is mid-request for a turn it has not opened yet.
+    if (proc.activeCtx || proc.pendingControlRequests > 0 || isCompacting() || isContinuationImminent()
+      || isApiRetryPending() || isStopFollowUpPending(now)) {
+      // Not idle: the CLI may still open a turn for it (the ordinary
+      // delivered-attach path), so the fold clock has not started.
+      for (const entry of proc.pendingDelivered) entry.foldSince = 0;
+      return;
+    }
+    const folded = [];
+    proc.pendingDelivered = proc.pendingDelivered.filter((entry) => {
+      // A non-steered entry (pushed with no turn active) is a genuine queued
+      // turn or a real drop — that stays the watchdog's to resolve.
+      if (!entry.steered) return true;
+      if (!entry.foldSince) { entry.foldSince = now; return true; }
+      if (now - entry.foldSince < steeredFoldGraceMs) return true;
+      folded.push(entry);
+      // Moved, not dropped: the row stays in the heartbeat's owned set until
+      // its marker is committed (see publishSettleMarker).
+      claimSettling(entry.ctx.message, entry.stoppedWithTurn ? 'stopped' : 'folded');
+      return false;
+    });
+    if (!folded.length) return;
+    // Settle sequentially, in push order: concurrent publishes could commit a
+    // later steer's merge stub before an earlier one's, and the transcript
+    // order is part of the multi-steer contract.
+    void (async () => {
+      for (const entry of folded) {
+        dbg('steered message folded into the finished turn; settling as merged', entry.ctx.message?.id || '(no id)');
+        try {
+          await settleFoldedSteeredEntry(entry);
+        } catch (error) {
+          dbg('folded-steer settle failed', error?.message || String(error));
+        }
+      }
+    })();
+  }
+
+  async function settleFoldedSteeredEntry(entry) {
+    const ctx = entry.ctx;
+    if (ctx.finalized) {
+      releaseSettling(ctx.message?.id);
+      return;
+    }
+    ctx.finalized = true;
+    controlPoller?.stop?.(ctx.controlState);
+    const model = ctx.state.responseModel || proc?.model || null;
+    // No streamed text of its own — the answer lives on the turn it was folded
+    // into, and kind='folded' renders it as a compact marker on its own
+    // message (never 'absorbed': that says the reply continues through the
+    // NEXT message, and mis-merged the next ordinary turn). A steer pushed
+    // into a turn the user then stopped was never answered: kind='stopped'
+    // says so (and the client offers to resend it) instead of claiming the
+    // stopped reply handled it.
+    const stopped = entry.stoppedWithTurn === true;
+    const text = stopped ? STEER_STOPPED_TEXT : STEER_FOLDED_TEXT;
+    try {
+      await publishSettleMarker(ctx.message, {
+        text,
+        model,
+        kind: stopped ? 'stopped' : 'folded',
+        variant: stopped ? 'stopped' : 'folded',
+      });
+    } finally {
+      // The entry is already spliced out of pendingDelivered, so nothing else
+      // can resolve this delivery — resolveDone must run even if the publish
+      // threw, or handlePendingPayload's `await ctx.done` would hang forever.
+      ctx.resolveDone?.(true);
+    }
+  }
+
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  /**
+   * Save the settle marker of a steered message the CLI already consumed —
+   * at most once. The row stays in `settlingMessages`, and so in every
+   * heartbeat, until the relay commits the marker: reporting it gone first
+   * let owner-heartbeat recovery put the row back to pending (and a heartbeat
+   * between splice and publish nulled its attempt, 409-ing the publish), and
+   * the CLI ran the prompt twice. A marker that cannot be saved within the
+   * retry budget ends as a terminal failure — never a requeue — and if even
+   * that cannot be posted, the heartbeat hands the row to the relay to fail.
+   * `onFirstAttempt` fires once the first publish attempt has returned, for
+   * callers that must order other publishes behind it without waiting out
+   * the retries.
+   */
+  async function publishSettleMarker(message, { text, model, kind, variant = 'folded', onFirstAttempt = () => {} }) {
+    const id = String(message?.id || '').trim();
+    if (!id) {
+      onFirstAttempt();
+      return;
+    }
+    claimSettling(message, variant);
+    let firstAttemptReported = false;
+    const reportFirstAttempt = () => {
+      if (firstAttemptReported) return;
+      firstAttemptReported = true;
+      onFirstAttempt();
+    };
+    // Drained once and reused by every attempt: a digest drained by a failed
+    // attempt would otherwise be lost.
+    const workflowRuns = publisher.drainWorkflowRuns();
+    try {
+      for (let attempt = 0; ; attempt += 1) {
+        const outcome = await publisher.publishResponse(message, { text, model, kind, workflowRuns });
+        reportFirstAttempt();
+        if (outcome !== 'failed') return;
+        if (attempt >= settleRetryDelaysMs.length) break;
+        await sleep(settleRetryDelaysMs[attempt]);
+      }
+      dbg('settle marker could not be saved; failing the row terminally', id);
+      const terminalError = buildSteerSettleFailure(message, { variant, agentLabel: 'Claude' });
+      const retryMs = Math.max(100, Number(settleRetryDelaysMs.at(-1)) || 0);
+      for (let attempt = 0; attempt < Math.max(1, maxTerminalSettleAttempts); attempt += 1) {
+        if (attempt) await sleep(retryMs);
+        const outcome = await publisher.publishResponse(message, {
+          text: terminalError.message,
+          model,
+          terminalError,
+          requeueOnFailure: false,
+          workflowRuns: null,
+        });
+        if (outcome !== 'failed') return;
+        // Second channel: the requeue route fails a row outright when handed
+        // a terminal error.
+        const failedViaRequeue = await api('POST', '/api/requeue', {
+          messageId: id,
+          terminalError,
+          ...attemptFields(message),
+        }).then(() => true, (error) => isStaleAttemptError(error));
+        if (failedViaRequeue) return;
+      }
+      // Still owned (the lease keeps renewing) and reported as settleFailed:
+      // the relay fails it from the next heartbeat that gets through.
+      dbg('terminal settle could not be posted; handing it to the heartbeat', id);
+      settleFailedTerminals.set(id, terminalError);
+    } finally {
+      reportFirstAttempt();
+      releaseSettling(id);
+    }
+  }
+
   function reapStalePendingDelivered(now) {
     if (!proc || !proc.pendingDelivered.length) return;
     if (!(pendingDeliveredTimeoutMs > 0)) return; // 0 = watchdog disabled
     // A silent cold boot (no init yet) is slow, not wedged: a CLI that never
     // inits dies on its own and cleanupProcess rejects the contexts then.
     if (!proc.sawInit) return;
-    if (proc.activeCtx || proc.liveTasks.size || proc.pendingControlRequests > 0 || isCompacting()) {
-      // A turn, task, control round-trip, or compaction may still attach these
+    // Same gate as the fold reaper, for the same reason: a live background
+    // task does not stop the CLI opening turns for pushed messages, so it
+    // must not pin this clock either — a dropped entry under an hour-long
+    // task would otherwise block the conversation for the hour instead of
+    // failing over after the timeout. Just-settled tasks (continuation
+    // imminent) and in-flight API retries still hold it.
+    if (proc.activeCtx || proc.pendingControlRequests > 0 || isCompacting() || isContinuationImminent()
+      || isApiRetryPending() || isStopFollowUpPending(now)) {
+      // A turn, control round-trip, or compaction may still attach these
       // entries — the unattached clock starts over once the process actually
       // goes quiet. A compaction is silent work, not idleness: the CLI replays
       // the turn these entries belong to once it finishes.
@@ -1901,9 +2591,23 @@ export function createClaudeSessionRunner({
   }
 
   function evaluateLifecycle() {
+    runLifecycle();
+    // The reapers and the compaction staleness cap change what a delivery
+    // would meet, and this tick is the backstop for every such change.
+    syncDeliveryReadiness();
+  }
+
+  function runLifecycle() {
     if (!proc || proc.closing) return;
     const now = Date.now();
+    // The Stop guard lives exactly as long as the steers it protects.
+    if (proc.stopFollowUp && !proc.suppressingTurn && !proc.pendingDelivered.some((entry) => entry.stoppedWithTurn)) {
+      proc.stopFollowUp = null;
+    }
     reapSilentProvisionalAdoption(now);
+    // Before the 5-minute watchdog: a folded steered entry settles as merged
+    // within the short fold grace instead of failing over.
+    reapFoldedSteeredEntries(now);
     reapStalePendingDelivered(now);
     if (hasLiveWork()) {
       // Track how long background tasks alone have held the process, for the
@@ -1983,11 +2687,16 @@ export function createClaudeSessionRunner({
         api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks: [] }).catch(() => {});
       }
     }
+    // Steers pushed into a turn the user stopped: if the Stop fell back to
+    // killing the process (no interrupt support), they settle as 'stopped'
+    // here rather than being left processing for recovery to re-run.
+    const stoppedSteers = processRef.pendingDelivered.filter((entry) => entry.stoppedWithTurn && !entry.ctx.finalized);
     const openContexts = [
       ...(processRef.activeCtx ? [processRef.activeCtx] : []),
-      ...processRef.pendingDelivered.map((entry) => entry.ctx),
+      ...processRef.pendingDelivered.filter((entry) => !stoppedSteers.includes(entry)).map((entry) => entry.ctx),
     ];
     processRef.pendingDelivered = [];
+    for (const entry of stoppedSteers) claimSettling(entry.ctx.message, 'stopped');
     processRef.activeCtx = null;
     if (proc === processRef) proc = null;
     for (const ctx of openContexts) {
@@ -2012,6 +2721,12 @@ export function createClaudeSessionRunner({
         model: processRef.model,
       }).catch(() => {});
     }
+    for (const entry of stoppedSteers) {
+      await settleFoldedSteeredEntry(entry).catch((error) => {
+        dbg('stopped-steer settle failed', error?.message || String(error));
+      });
+    }
+    syncDeliveryReadiness();
   }
 
   // ---------------------------------------------------------------------------
@@ -2062,6 +2777,7 @@ export function createClaudeSessionRunner({
       // tool_use id → explicitly pinned model of a subagent spawn block; the
       // task panel's model column resolves through this at publish time.
       subagentSpawns: new Map(),
+      subagentActivity: new Map(),
       initModel: '',
       // Set when the CLI reported a session-scoped refusal fallback; the next
       // delivered turn repins the composer's model instead of trusting
@@ -2079,6 +2795,10 @@ export function createClaudeSessionRunner({
       pendingActivities: [],
       sawInit: false,
       handoffSettling: null,
+      // Stop guard (see maybeSuppressStopFollowUp): armed by a Stop that cut
+      // off pushed steers; suppressingTurn while a follow-up turn is killed.
+      stopFollowUp: null,
+      suppressingTurn: false,
       activeCtx: null,
       pendingDelivered: [],
       lastBoundary: null,
@@ -2086,6 +2806,12 @@ export function createClaudeSessionRunner({
       lastEventAt: Date.now(),
       heldForTasksSince: 0,
       taskSettledAt: 0,
+      // Bumped by every task-settle signal; the Stop guard compares it.
+      taskSettleSeq: 0,
+      // taskSettleSeq when the last turn ended: a settle since then is what
+      // makes an unowed init inside a settings window a continuation.
+      settleSeqAtTurnEnd: 0,
+      lastApiRetryAt: 0,
       tasksExpired: false,
       tasksExpiredAt: 0,
       aborted: false,
@@ -2120,6 +2846,7 @@ export function createClaudeSessionRunner({
       // the human thinks, and an idle shutdown under it would reject the
       // request with "Tool permission stream closed".
       processRef.pendingControlRequests += 1;
+      syncDeliveryReadiness();
       try {
         // A question from a background agent between turns has no active turn
         // to attach to, and /api/relay-question requires a processing queue
@@ -2140,6 +2867,9 @@ export function createClaudeSessionRunner({
       } finally {
         processRef.pendingControlRequests -= 1;
         processRef.lastEventAt = Date.now();
+        // The card was answered (or the prompt resolved): a message held
+        // behind it steers into the resumed turn within one round-trip.
+        syncDeliveryReadiness();
       }
     };
 
@@ -2182,6 +2912,7 @@ export function createClaudeSessionRunner({
       try {
         for await (const sdkMessage of processRef.turn) {
           await onSdkMessage(processRef, sdkMessage);
+          syncDeliveryReadiness();
         }
       } catch (error) {
         if (!processRef.aborted && !abortController.signal.aborted) streamError = error;
@@ -2196,6 +2927,11 @@ export function createClaudeSessionRunner({
     return processRef;
   }
 
+  function expectSettingsReinit() {
+    settingsReinitsOwed += 1;
+    settingsWindowOpen = true;
+  }
+
   async function adaptProcess(message) {
     const relayMode = message.relayMode || 'agent';
     const model = resolvePerTurnModel(message);
@@ -2221,6 +2957,7 @@ export function createClaudeSessionRunner({
 
     const permissionMode = permissionModeForRelayMode(relayMode);
     if (permissionMode !== proc.permissionMode) {
+      expectSettingsReinit();
       await Promise.resolve(proc.turn.setPermissionMode?.(permissionMode)).catch((error) => {
         dbg('setPermissionMode failed', error?.message || String(error));
       });
@@ -2239,6 +2976,7 @@ export function createClaudeSessionRunner({
     // (model '') keeps whatever the CLI chose.
     const repinAfterFallback = Boolean(proc.modelFallback) && Boolean(model);
     if (model !== proc.model || repinAfterFallback) {
+      expectSettingsReinit();
       await Promise.resolve(proc.turn.setModel?.(model || undefined)).catch((error) => {
         dbg('setModel failed', error?.message || String(error));
       });
@@ -2250,6 +2988,7 @@ export function createClaudeSessionRunner({
       // session-scoped ultracode/enableWorkflows flags (with the effort pinned
       // to the xhigh the flag implies); every other change clears those flags
       // alongside the new effortLevel.
+      expectSettingsReinit();
       await Promise.resolve(proc.turn.applyFlagSettings?.(claudeUltracodeFlagSettings(effort))).catch((error) => {
         dbg('applyFlagSettings effort failed', error?.message || String(error));
       });
@@ -2260,6 +2999,7 @@ export function createClaudeSessionRunner({
     // be pushed too or clearing the slider would never take effect.
     const autoCompactWindow = normalizeAutoCompactWindow(getAutoCompactWindow());
     if (autoCompactWindow !== proc.autoCompactWindow) {
+      expectSettingsReinit();
       await Promise.resolve(proc.turn.applyFlagSettings?.(claudeAutoCompactFlagSettings(autoCompactWindow))).catch((error) => {
         dbg('applyFlagSettings autoCompactWindow failed', error?.message || String(error));
       });
@@ -2277,6 +3017,7 @@ export function createClaudeSessionRunner({
         // Enabling applies live. The display MUST be re-sent afterwards, in
         // this order: a session spawned with thinking off carries no display
         // mode, so enabling without it yields visible-but-empty thinking.
+        expectSettingsReinit();
         await Promise.resolve(proc.turn.applyFlagSettings?.(claudeThinkingFlagSettings(true))).catch((error) => {
           dbg('applyFlagSettings thinkingEnabled failed', error?.message || String(error));
         });
@@ -2294,6 +3035,7 @@ export function createClaudeSessionRunner({
       }
     }
     if (thinkingDisplay !== proc.thinkingDisplay || reassertDisplay) {
+      expectSettingsReinit();
       await applyThinkingDisplay(proc.turn, thinkingDisplay, { budget: proc.thinkingBudget, dbg });
       proc.thinkingDisplay = thinkingDisplay;
     }
@@ -2304,11 +3046,161 @@ export function createClaudeSessionRunner({
   // ---------------------------------------------------------------------------
   // Relay contract
 
+  /**
+   * Whether a new delivered message may be pushed into the live turn
+   * (mid-turn steering) instead of waiting in the relay queue for the
+   * result. The CLI dequeues a mid-turn push into the running turn; the
+   * absorbed-steering handoff in resolveContext is the receiving end.
+   * Deliberately narrow — every exclusion here guards an invariant that
+   * already exists:
+   *  - a pending canUseTool round-trip (AskUserQuestion, plan approval)
+   *    holds steering entirely, so the bridge reply and a steered push can
+   *    never race in the CLI (a deliberate product decision, 2026-09-19);
+   *  - a compaction replays the turn when it finishes, and a push into that
+   *    window would land inside the replay;
+   *  - a provisional post-compaction adoption may still be unwound on the
+   *    premise that the CLI never consumed the row's prompt — steering
+   *    another message in would spend that premise for it;
+   *  - a NON-steered pending entry means a turn-opening delivery is still
+   *    mid-flight (pushed with no turn active, replay not yet arrived) — a
+   *    steer would race the very turn that entry is about to open.
+   * The number of steered entries in flight is deliberately unbounded
+   * (Claude Code parity — the CLI queues any number of mid-turn messages and
+   * folds or replays them in push order; attach matches by expectedText,
+   * oldest first, and the fold reaper settles every leftover as merged).
+   */
+  function canAcceptSteering() {
+    if (!proc || proc.closing || proc.aborted) return false;
+    const ctx = proc.activeCtx;
+    if (!ctx || ctx.finalized || ctx.discarded || ctx.interrupted) return false;
+    if (ctx.adoptedFromCompaction) return false;
+    if (proc.pendingDelivered.some((entry) => !entry.steered)) return false;
+    if (proc.pendingControlRequests > 0) return false;
+    if (isCompacting()) return false;
+    return true;
+  }
+
+  /**
+   * The one steering gate. A delivery arriving now is held — handed back to
+   * the queue instead of pushed — when a turn is live (a context, anything
+   * pushed and not yet settled, or an open control round-trip) and that turn
+   * cannot accept a steer. The socket link consults this for its readiness
+   * too, idle or mid-delivery: a continuation holding a question card is not a
+   * delivery, so the link's own in-flight bookkeeping cannot see it.
+   */
+  function isDeliveryHeld() {
+    if (admittingDeliveries > 0) return true;
+    if (!proc || proc.closing || proc.aborted) return false;
+    if (!isTurnActive() && !(proc.pendingControlRequests > 0)) return false;
+    return !canAcceptSteering();
+  }
+
+  function syncDeliveryReadiness() {
+    const ready = !isDeliveryHeld();
+    if (ready === lastReportedDeliveryReady) return;
+    lastReportedDeliveryReady = ready;
+    try {
+      onDeliveryReadinessChange(ready);
+    } catch (error) {
+      dbg('delivery readiness listener failed', error?.message || String(error));
+    }
+  }
+
+  /**
+   * Give a held delivery back to the queue with no retry penalty. The relay
+   * re-delivers it once this worker signals ready again, i.e. when the hold
+   * ends — the message then steers into the resumed turn. Pushing it into the
+   * hold instead would bypass the question card or land inside a compaction's
+   * replay.
+   */
+  async function handBackHeldDelivery(message) {
+    dbg('steering held; handing the delivery back to the queue', message.id || '(no id)');
+    if (!message.id) return false;
+    await api('POST', '/api/requeue', {
+      messageId: message.id,
+      class: 'steering-held',
+      ...attemptFields(message),
+    }).catch((error) => {
+      if (isStaleAttemptError(error)) {
+        dbg('steering-held hand-back refused as stale_attempt', message.id);
+        return;
+      }
+      dbg('steering-held hand-back failed', message.id, error?.message || String(error));
+    });
+    return false;
+  }
+
+  /**
+   * Composer-facing steering snapshot: whether a turn is live, whether a
+   * message typed now would steer into it, and — when it would not — why.
+   * Rides the worker heartbeat to the relay's worker registry, so the client
+   * can disable the Steer button during holds instead of silently queueing.
+   * holdReason is a coarse enum, not a diagnostic: 'question' (a canUseTool
+   * round-trip — question card / plan approval — is open), 'compaction',
+   * 'adoption' (provisional post-compaction adoption), 'delivery' (a
+   * turn-opening delivery is still mid-flight).
+   */
+  function steeringState() {
+    // A closing/aborted process is about to die — nothing about its last turn
+    // should hold the composer of the worker that replaces it.
+    if (!proc || proc.closing || proc.aborted) {
+      return { turnActive: false, canSteer: false, holdReason: null, messageId: null, supported: true };
+    }
+    const ctx = proc.activeCtx || null;
+    const ctxLive = Boolean(ctx && !ctx.finalized && !ctx.discarded && !ctx.interrupted);
+    // A turn-opening delivery in flight (pushed with no active ctx, replay not
+    // yet arrived) reads as an active turn to the user — the row is already
+    // `processing` — so it must report as one here, with a 'delivery' hold.
+    const openingDelivery = proc.pendingDelivered.find((entry) => !entry.steered) || null;
+    const turnActive = ctxLive || Boolean(openingDelivery);
+    const canSteer = canAcceptSteering();
+    let holdReason = null;
+    if (turnActive && !canSteer) {
+      if (proc.pendingControlRequests > 0) holdReason = 'question';
+      else if (isCompacting()) holdReason = 'compaction';
+      else if (ctxLive && ctx.adoptedFromCompaction) holdReason = 'adoption';
+      else if (openingDelivery) holdReason = 'delivery';
+      else holdReason = 'other';
+    }
+    // The turn this snapshot describes, so a client can discard a stale hold
+    // that belongs to a previous turn.
+    const messageId = String(
+      (ctxLive ? ctx.message?.id : '') || openingDelivery?.ctx?.message?.id || '',
+    ).trim() || null;
+    // `supported` is the worker-advertised opt-in the client's composer reads
+    // (the same flag the Copilot SDK worker publishes) — its only steering
+    // gate, so every snapshot carries it, idle ones included.
+    return { turnActive, canSteer, holdReason, messageId, supported: true };
+  }
+
   async function handlePendingPayload(pending) {
     const message = pending?.message || null;
     if (!message) return false;
+    // An older relay (the worker updated on disk before the relay restarted)
+    // treats the hand-back as a failed delivery — retry, backoff, worker
+    // marked errored — so against one the message is pushed the legacy way.
+    if (isDeliveryHeld() && canHandBackHeldDelivery() !== false) return handBackHeldDelivery(message);
+    // A turn-opening delivery awaits (adaptProcess, a draining process, a
+    // spawn) before it pushes; until then it counts as admitting, so nothing
+    // else is let in behind it. A steer pushes synchronously and needs none.
+    let admitting = !(proc && !proc.closing && !proc.aborted && proc.activeCtx);
+    if (admitting) admittingDeliveries += 1;
+    const endAdmission = () => {
+      if (!admitting) return;
+      admitting = false;
+      admittingDeliveries -= 1;
+      syncDeliveryReadiness();
+    };
+    syncDeliveryReadiness();
     try {
-      if (proc && !proc.closing && !proc.aborted) {
+      // A steered delivery (a turn is live) must not run the settings diffs:
+      // setModel/effort/mode against a mid-flight turn would disturb the very
+      // turn the message is steering into, and the mode-change recycle is
+      // refused under live work anyway. The next between-turns delivery
+      // re-runs adaptProcess with the then-current settings, so nothing is
+      // lost — the steered message's own model/mode intent applies from the
+      // next turn on, same as Claude Code.
+      if (proc && !proc.closing && !proc.aborted && !proc.activeCtx) {
         await adaptProcess(message);
       }
       if (!proc || proc.closing || proc.aborted) {
@@ -2338,9 +3230,38 @@ export function createClaudeSessionRunner({
       for (let attempt = 0; attempt < 2; attempt += 1) {
         const procRef = proc;
         const ctx = createDeliveredContext(message);
-        procRef.pendingDelivered.push({ ctx, expectedText: contentText(content), pushedAt: Date.now() });
+        // A message pushed while a turn is already active is a steered
+        // delivery. The CLI folds it into that running turn and answers
+        // everything with ONE result on the turn it was already running —
+        // it does NOT necessarily replay the steered text as a turn-opening
+        // user message, so the absorbed-steering handoff in resolveContext
+        // (which needs that replay) may never fire. Mark the entry so the
+        // fold reaper can settle it as merged once the turn it joined ends,
+        // instead of leaving its queue row stuck `processing` until the
+        // 5-minute watchdog fails it with a bogus "resend" error.
+        const steered = Boolean(procRef.activeCtx);
+        // A steer carries a hidden note that it adds to the running request
+        // rather than replacing it (shared/steer-note.mjs). expectedText stays
+        // the user's own text: the replay signatures strip the note before
+        // any comparison, so matching works whether or not the CLI echoes it.
+        // Not into a continuation: there the running work is the CLI's own
+        // follow-up to a background task, not a request of the user's.
+        // Whatever is left starting with "/" — a "/x" delivered between turns,
+        // on a first turn, or into a continuation — gets the slash-command
+        // guard, or the CLI would run it as a command instead of handing the
+        // model the text the user sent (shared/slash-command-guard.mjs). A
+        // noted steer no longer starts with "/" and is pushed as noted. The
+        // replay signatures strip the guard too, so expectedText stays the
+        // user's own text here as well.
+        const pushedContent = withSlashCommandGuardContent(steered && procRef.activeCtx?.kind !== 'continuation'
+          ? withSteerNoteContent(content)
+          : content);
+        procRef.pendingDelivered.push({ ctx, expectedText: contentText(content), pushedAt: Date.now(), steered });
+        // Registered: from here a later init takes the delivered-row branch.
+        settingsReinitsOwed = 0;
+        settingsWindowOpen = false;
         try {
-          procRef.turn.pushUserMessage(content);
+          procRef.turn.pushUserMessage(pushedContent);
         } catch (pushError) {
           // The stream ended under us (process wound down between the
           // liveness check and the push): retire this context and respawn.
@@ -2353,14 +3274,25 @@ export function createClaudeSessionRunner({
           spawnProcess(message);
           continue;
         }
+        // Pushed: the pending entry now holds the gate on its own.
+        endAdmission();
+        // A genuinely new message reached the CLI (only possible against an
+        // older relay): the next turn may be its, so the Stop guard must not
+        // kill it.
+        if (procRef.stopFollowUp) procRef.stopFollowUp = null;
         return await ctx.done;
       }
       throw new Error('claude session process closed while accepting the message');
     } catch (error) {
+      endAdmission();
+      settingsReinitsOwed = 0;
+      settingsWindowOpen = false;
       const errorText = String(error?.message || error || 'unknown error');
       dbg('claude turn failed', message.id, errorText);
       await publisher.publishTurnException({ message, errorText });
       return true;
+    } finally {
+      endAdmission();
     }
   }
 
@@ -2410,8 +3342,13 @@ export function createClaudeSessionRunner({
 
   return {
     handlePendingPayload,
+    canAcceptSteering,
+    isDeliveryHeld,
+    steeringState,
     getActiveQueueMessageId,
     getActiveQueueMessageIds,
+    getSettleFailed,
+    acknowledgeSettleFailed,
     isTurnActive,
     stopBackgroundTask,
     stopBackgroundTaskByToolUseId,