feat(ui): steer a queued follow-up into the live turn after a 5 s edit window (#19970)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When a person comments on a task while the agent works, the comment
waits in a queue until the current run ends, and only the next run reads
it
> - Measured locally, a comment posted during a Codex tool call waited
54–68 s for a reply (median 64 s)
> - Codex and Pi can take a message into the live turn ("Steer"), but
today the person must click Steer on each queued message
> - Restart recovery now delivers a steered message that a restart
interrupted (#19962), so steering is safe to do automatically
> - This pull request steers a queued follow-up into the live turn on
its own after a 5-second window in which the person can edit or cancel
it
> - The benefit is a faster reply to mid-turn comments on Codex and Pi,
with no new decision for the person

## Linked Issues or Issue Description

**Feature**
Send a queued follow-up into the running turn automatically when the
runner supports steering.

**Problem**
A follow-up comment posted during a running turn waits for the whole
turn to end and for a new run to start. Steering is available for Codex
and Pi, but only as a manual button on each queued message.

**Proposed behavior**
After a 5-second edit window, the queued message is steered into the
live turn. During the window the row shows "Sending in Xs" with Edit and
Cancel. If steering is unavailable, the message stays queued as before.
Claude, OpenCode and Cursor keep the queue. Steer and Interrupt stay
available as buttons.

Refs #19962

## What Changed

- `queued-message-auto-steer.ts`: one constant,
`QUEUED_MESSAGE_AUTO_STEER_DELAY_MS = 5_000`, a deadline helper and an
eligibility check. A message steers automatically only when all of these
are true:
- steering is available for the queue, and it is a `paperclip_runner_v1`
queue with a queue id and a target run;
  - the person can edit the message;
- it is not an interaction response or a response that requires a fresh
session;
- it is not optimistic, cancelled, already attempted, or open in the
editor.
- `TaskChatQueuedMessages`: countdown row "Sending in Xs" with Edit and
Cancel in place of Steer and the "…" menu. The deadline is `max(message
changed, first eligible) + delay`, so an old queued message does not
send the moment its turn becomes steerable, and an edit restarts the
window. When the deadline passes, the row uses the existing Steer
action, so the server path, idempotency and fallback stay the same.
Cancel returns the row to the normal Steer button. The countdown is
announced once to screen readers, not on every tick.
- `TaskChatThread` turns it on with the constant and passes the message
being edited, so an open edit never sends. The prop stays off by default
for other callers.
- Storybook: `AutoSteerCountdown` (with a play test for Cancel) and
`AutoSteerCountdownMobile` in "Composer / Steering and queued messages".
- Restart chaos TTFT driver: a `midturn` phase measures comment-to-reply
for a comment posted during a 40-second tool call, with `--midturn-mode
queue|steer` and `--midturn-fault K1|K2|K6`. It records the reply count,
so exactly-once delivery is checked.

## Verification

- `pnpm --filter @paperclipai/ui vitest run
src/components/task-chat/TaskChatQueuedMessages.test.tsx
src/components/TaskChatThread.test.tsx`: 434 passed. Seven new
auto-steer tests use fake timers: countdown and send, Cancel, Edit
restarts the window, an open edit never sends, ineligible queues stay
manual, no instant send for an old message, one attempt per revision.
They fail with the trigger disabled.
- `node scripts/check-token-gates.mjs`: clean.
- Storybook in the browser, desktop and mobile: the first row counts
down and steers ("Message steered into the active turn."). The cancelled
row shows the normal Steer button. On mobile the text truncates and the
row fits.
- Mid-turn latency, local, Codex, comment during a 40-second tool call:
queue 54–68 s (median 64 s), steer 47–61 s (median 50 s). The steer was
acknowledged in 0.8–0.9 s. The remaining time is the tool call and the
model, not the hand-off.
- Restart chaos, Codex, steer mode, faults K1, K2 and K6, 2 samples
each, on #19962 plus this branch: 6 of 6 messages acknowledged, still
unread at the fault, recovered, and answered exactly once (before
#19962: 0 of 6).

## Risks

- A message now leaves the queue after 5 seconds unless the person edits
or cancels it. The window and the countdown make this visible, and
steering is only automatic where the provider supports it.
- Pi: a steer the model already read before a restart can arrive again
after recovery, because Pi reports no read evidence (see #19962).
Automatic steering makes this a little more likely.
- If steering fails, the message stays queued and is delivered by the
next run, as today.
- UI only and a test harness. No schema, API or server change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file editing, browser checks, test execution).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

tests/restart-chaos/ttft-baseline-stats.ts

@@ -16,7 +16,7 @@ export interface BaselineRun {
   adapter: string;
   environment: string;
   /** Driver intent: a new task, a follow-up comment on the same task, or a run crossed by a restart. */
-  phase: "cold" | "warm" | "restart";
+  phase: "cold" | "warm" | "restart" | "midturn";
   events: BaselineEvent[];
 }
 

tests/restart-chaos/ttft-baseline.ts

@@ -50,6 +50,43 @@ const restartTask = (nonce: string) => [
   "Do not create files, documents or other tasks.",
 ].join("\n");
 
+const MIDTURN_SLEEP_SECONDS = 40;
+const midturnTask = (nonce: string) => [
+  `Baseline mid-turn ${nonce}. First run the shell command \`python3 -c "import time; time.sleep(${MIDTURN_SLEEP_SECONDS})"\` and wait for it to finish.`,
+  `Then reply with a one-line comment that says \`DONE ${nonce}\` and mark this task done.`,
+  "Do not create files, documents or other tasks.",
+].join("\n");
+const midturnFollowUp = (nonce: string) =>
+  `Mid-turn follow-up ${nonce}: also reply with a one-line comment that says \`HELLO ${nonce}\`.`;
+
+/** The agent's replies naming `marker`, oldest first. A failed read throws: it is not a lost reply. */
+async function agentReplies(api: ChaosApi, issueId: string, marker: string): Promise<Json[]> {
+  const comments = await api.get<Json[]>(`/api/issues/${issueId}/comments`, 10_000);
+  return comments.filter(comment => Boolean(comment.authorAgentId) && String(comment.body ?? "").includes(marker))
+    .sort((a, b) => Date.parse(String(a.createdAt)) - Date.parse(String(b.createdAt)));
+}
+
+/**
+ * Steer a queued comment into the live turn once the runner reports steering
+ * available. Returns the acknowledgement time, or the disposition that blocked it.
+ */
+async function steerQueuedComment(api: ChaosApi, issueId: string, commentId: string): Promise<{ acknowledgedAt: string | null; disposition: string }> {
+  const deadline = Date.now() + 60_000;
+  let disposition = "none";
+  while (Date.now() < deadline) {
+    const queue = await api.get<Json>(`/api/issues/${issueId}/queued-comments`, 10_000).catch(() => null);
+    disposition = String(queue?.steeringDisposition ?? "none");
+    if (queue && disposition === "available" && queue.queueId && queue.targetRunId) {
+      await api.post(`/api/issues/${issueId}/queued-comments/${commentId}/steer`,
+        { queueId: queue.queueId, revision: queue.revision, targetRunId: queue.targetRunId });
+      return { acknowledgedAt: new Date().toISOString(), disposition };
+    }
+    if (disposition === "unsupported") break;
+    await delay(500);
+  }
+  return { acknowledgedAt: null, disposition };
+}
+
 async function createTask(api: ChaosApi, lab: ChaosLab, adapter: AdapterId, title: string, description: string) {
   const issue = await api.post<Json>(`/api/companies/${lab.companyId}/issues`, {
     title, description, status: "todo", priority: "medium", assigneeAgentId: lab.agents[adapter].id,
@@ -105,21 +142,21 @@ async function allEvents(api: ChaosApi, runId: string): Promise<BaselineEvent[]>
  * command text (OpenCode's `bash`) counts as inside an open shell call, and the
  * sample is marked `commandUnverified`.
  */
-async function runInShellCall(api: ChaosApi, issueId: string): Promise<{ runId: string; commandUnverified: boolean } | null> {
+async function runInShellCall(api: ChaosApi, issueId: string, marker = RESTART_SLEEP_MARKER): Promise<{ runId: string; commandUnverified: boolean } | null> {
   const active = (await runsFor(api, issueId)).find(run => String(run.status) === "running");
   if (!active) return null;
   const events = await allEvents(api, runIdOf(active)).catch(() => []);
-  const open = openShellExecutions(events, RESTART_SLEEP_MARKER);
+  const open = openShellExecutions(events, marker);
   if (open.some(call => call.matched)) return { runId: runIdOf(active), commandUnverified: false };
   if (open.length && open.every(call => call.unlabelled)) return { runId: runIdOf(active), commandUnverified: true };
   return null;
 }
 
 /** Wait until the run is inside its shell tool call (started, not ended). */
-async function waitForShellCall(api: ChaosApi, issueId: string): Promise<{ runId: string; commandUnverified: boolean } | null> {
+async function waitForShellCall(api: ChaosApi, issueId: string, marker = RESTART_SLEEP_MARKER): Promise<{ runId: string; commandUnverified: boolean } | null> {
   const deadline = Date.now() + 4 * 60_000;
   while (Date.now() < deadline) {
-    const inside = await runInShellCall(api, issueId);
+    const inside = await runInShellCall(api, issueId, marker);
     if (inside) return inside;
     await delay(1_500);
   }
@@ -185,6 +222,10 @@ async function main() {
     // lifecycle, so the server resolves the product default). Absent keeps the
     // catalog profile's setting.
     lifecycle: { type: "string" },
+    // Mid-turn follow-up delivery: queue (default, wait for the turn) or steer (into the live turn).
+    "midturn-mode": { type: "string", default: "queue" },
+    // Fault the control plane right after a steered comment is acknowledged (K1, K2 or K6).
+    "midturn-fault": { type: "string" },
     "idle-ms": { type: "string", default: "600000" },
   } });
   if (values.report) {
@@ -198,6 +239,11 @@ async function main() {
   const restarts = Math.max(0, Number(values.restarts));
   const missing = requested.map(adapter => CREDENTIAL_FOR_ADAPTER[adapter]).filter(key => !process.env[key]);
   if (missing.length) throw new Error(`Missing ${missing.join(", ")}; run: set -a; source ~/.secrets; set +a`);
+  const midturnMode = values["midturn-mode"];
+  if (midturnMode !== "queue" && midturnMode !== "steer") throw new Error("--midturn-mode must be queue or steer");
+  const midturnFault = values["midturn-fault"] as FaultKind | undefined;
+  if (midturnFault !== undefined && !["K1", "K2", "K6"].includes(midturnFault)) throw new Error("--midturn-fault must be K1, K2 or K6");
+  if (midturnFault && midturnMode !== "steer") throw new Error("--midturn-fault applies to --midturn-mode steer");
   const lifecycle = values.lifecycle;
   if (lifecycle !== undefined && lifecycle !== "per_turn" && lifecycle !== "warm" && lifecycle !== "default") {
     throw new Error("--lifecycle must be per_turn, warm or default");
@@ -216,6 +262,7 @@ async function main() {
   const faults: BaselineFault[] = [];
   const runPhase = new Map<string, BaselineRun["phase"]>();
   const agentLifecycles: Record<string, string> = {};
+  const midturn: Json[] = [];
   const timedOutIssues = new Set<string>();
   // One shutdown path for normal completion and for SIGINT/SIGTERM: the server
   // runs in a detached process group and the embedded Postgres has no exit hook.
@@ -272,6 +319,51 @@ async function main() {
       }
     }));
 
+    // Mid-turn follow-up: a comment posted while the agent is inside a long
+    // tool call. Records when the comment landed and every run of the task,
+    // so the wait splits into "rest of the turn" and "hand-off".
+    const runMidturn = async (adapter: (typeof adapters)[number]) => {
+      for (let index = 0; index < samples; index += 1) {
+        const nonce = `${adapter}-m${index}-${Date.now().toString(36)}`;
+        const issueId = await createTask(api, lab, adapter, `TTFT mid-turn ${nonce}`, midturnTask(nonce));
+        tasks.push({ issueId, adapter, phase: "midturn" });
+        const inside = await waitForShellCall(api, issueId, `time.sleep(${MIDTURN_SLEEP_SECONDS})`);
+        if (!inside) {
+          timeline.add("baseline_midturn_sample_skipped", { adapter, issueId });
+          continue;
+        }
+        const comment = await api.post<Json>(`/api/issues/${issueId}/comments`, { body: midturnFollowUp(nonce) });
+        const steer = midturnMode === "steer" ? await steerQueuedComment(api, issueId, String(comment.id)) : null;
+        // Restart right after the steered comment was acknowledged: it must be answered exactly once.
+        const fault = midturnFault && steer?.acknowledgedAt
+          ? await supervisor.fault(midturnFault, 0, `midturn-${index}`) : null;
+        if (fault) faults.push({ kind: midturnFault!, readyAt: fault.readyAt ?? Date.now(), runIds: [inside.runId] });
+        // A steered comment is answered inside the same run; a queued one needs a second run.
+        const settled = await waitForRest(api, supervisor, issueId, steer?.acknowledgedAt ? 1 : 2);
+        if (settled.timedOut) {
+          timedOutIssues.add(issueId);
+          timeline.add("baseline_sample_timeout", { adapter, issueId, phase: "midturn" });
+          continue;
+        }
+        // Read the replies once; a failed read is recorded, not counted as a lost reply.
+        const replies = await agentReplies(api, issueId, `HELLO ${nonce}`)
+          .catch((error: unknown) => ({ error: error instanceof Error ? error.message : String(error) }));
+        midturn.push({ adapter, issueId, mode: midturnMode, interruptedRunId: inside.runId, commentId: String(comment.id),
+          commentCreatedAt: String(comment.createdAt), steer, fault: fault ? midturnFault : null,
+          replyCount: Array.isArray(replies) ? replies.length : null,
+          replyReadError: Array.isArray(replies) ? null : replies.error,
+          replyCreatedAt: Array.isArray(replies) && replies[0] ? String(replies[0].createdAt) : null,
+          runs: settled.runs });
+        timeline.add("baseline_midturn_done", { adapter, issueId, runs: settled.runs.length });
+      }
+    };
+    // Every fault restarts the one shared server, so faulted samples run one
+    // at a time: a restart must never land in another sample's comment or steer.
+    if (phases.has("midturn")) {
+      if (midturnFault) for (const adapter of adapters) await runMidturn(adapter);
+      else await Promise.all(adapters.map(runMidturn));
+    }
+
     // Restart recovery: one in-flight tool call per adapter, then one fault crosses all of them.
     const kinds: FaultKind[] = ["K1", "K2"];
     for (let index = 0; phases.has("restart") && index < restarts * kinds.length; index += 1) {
@@ -321,11 +413,18 @@ async function main() {
       }
     }
     const data = { waveId, lifecycle: lifecycle ?? "catalog", agentLifecycles, adapters, notReady: requested.filter(adapter => !adapters.includes(adapter)),
-      timedOutTasks: timedOutIssues.size, samples, restarts, gitSha: process.env.GIT_SHA ?? null, runs, faults };
+      timedOutTasks: timedOutIssues.size, samples, restarts, midturn, gitSha: process.env.GIT_SHA ?? null, runs, faults };
     await writeFile(path.join(outDir, "baseline-data.json"), `${JSON.stringify(data)}\n`, { mode: 0o600 });
     await writeFile(path.join(outDir, "baseline-report.md"), report(runs, faults), { mode: 0o600 });
     process.stdout.write(report(runs, faults));
     if (timedOutIssues.size) process.stdout.write(`\n${timedOutIssues.size} sample(s) timed out and were left out.\n`);
+    // Every answered mid-turn comment must be answered exactly once.
+    const wrongReplies = midturn.filter(sample => sample.replyCount !== 1);
+    for (const sample of wrongReplies) {
+      process.stdout.write(`\nMid-turn sample ${String(sample.adapter)} ${String(sample.issueId)}: ${sample.replyReadError
+        ? `reply read failed (${String(sample.replyReadError)})` : `${String(sample.replyCount)} replies, expected 1`}\n`);
+    }
+    if (wrongReplies.length) process.exitCode = 1;
     process.stdout.write(`\nWrote ${outDir}\n`);
   } finally {
     // Always stop the wrapper-owned embedded Postgres (SysV shared memory is scarce).