From 43a572f3f7e87dbab30640577081921eba88b676 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Thu, 3 Sep 2026 20:46:22 +0000
Subject: [PATCH] strip ANSI from headless agent output so a slow run stops
 looking wedged
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A public-review Stage 3 run reported as stuck. It was not: the OpenCode child
was nine minutes into prefilling a ~100K-token prompt on a local 27B model. The
card gave no way to tell, for two reasons, both fixed here.

`opencode run` wraps its status line in bare SGR resets. Those bytes reached
output.txt and the live tail verbatim, and the browser drops only the ESC — so
the only thing on the card was `[stderr] [0m`. Both headless spawners now
decolor per stream through the shared `createStreamingAnsiStripper`, before the
fallback-signal detector and the codex stderr formatter (each matches provider
prose that an SGR pair would otherwise split). The runner in `cos-runner` is a
twin of `spawnDirectly`'s handlers and had the identical bug, so it gets the
same treatment; a stream-json stdout is NDJSON with no raw ESC and skips the
scan. A chunk that decolors to nothing is dropped instead of emitting a blank
`[stderr]` line per progress redraw.

Second, the card had no "Open Shell" link and said nothing about why. A
public-review stage is forced headless even when configured onto a TUI provider
(`spawnHeadless = publicReview || !isTui`), but `agent.metadata` is a
hand-picked projection that carried no trace of that posture, so the card was
indistinguishable from one whose PTY failed to attach. `publicReviewPosture` is
now projected and the card shows a "No shell" chip explaining it. Scoped to that
case only: an ordinary headless CLI agent gets no chip, and neither does a TUI
run still waiting on its session id — every healthy TUI spawn passes through
that state, so a chip there would put the noise straight back.

The prompt size that made the run slow in the first place is #6117.
---
 client/src/components/cos/tabs/AgentCard.jsx  |  18 ++++
 .../components/cos/tabs/AgentCard.test.jsx    |  48 +++++++++
 server/cos-runner/index.js                    |  25 ++++-
 server/cos-runner/index.test.js               |  37 +++++++
 server/services/agentCliSpawning.js           |  35 +++++-
 server/services/agentCliSpawning.test.js      | 101 ++++++++++++++++++
 server/services/agentLifecycle.js             |   7 ++
 server/services/agentLifecycle.test.js        |  10 ++
 8 files changed, 272 insertions(+), 9 deletions(-)

diff --git a/client/src/components/cos/tabs/AgentCard.jsx b/client/src/components/cos/tabs/AgentCard.jsx
index 4ee8eb15ff..50cf738c58 100644
--- a/client/src/components/cos/tabs/AgentCard.jsx
+++ b/client/src/components/cos/tabs/AgentCard.jsx
@@ -329,6 +329,15 @@ export default function AgentCard({ agent, onPause, onKill, onDelete, onResume,
   ), [inactive, fullOutput, liveOutput, agent.output]);
   const lastOutput = output.length > 0 ? output[output.length - 1]?.line : null;
 
+  // Why this run has NO "Open Shell" link. Scoped to the one case where the user
+  // configured a TUI provider and got no shell anyway: a public-review stage is
+  // forced headless regardless (`spawnHeadless = publicReview || !isTui`). An
+  // ordinary headless CLI agent gets no chip — nobody expected a shell there, and
+  // one on every card would be the noise this exists to remove.
+  const noShellReason = !agent.metadata?.tuiSessionId && agent.metadata?.publicReviewPosture
+    ? 'No shell: a public-review stage always runs headless, even when you configure it onto a TUI provider — the screened PR content stays inside the sandboxed child. Watch the live output below to see what it is doing.'
+    : null;
+
   // Extract recent tool activity (last few tool lines) for live display
   const recentActivity = useMemo(() => {
     if (inactive || output.length === 0) return [];
@@ -616,6 +625,15 @@ export default function AgentCard({ agent, onPause, onKill, onDelete, onResume,
               <span className="font-mono text-[10px] text-port-on-success">{agent.metadata.tuiSessionId.slice(0, 6)}</span>
             </Link>
           )}
+          {!inactive && noShellReason && (
+            <span
+              className="flex items-center gap-1 px-2 py-0.5 rounded bg-port-border/40 text-gray-400 whitespace-nowrap"
+              title={noShellReason}
+            >
+              <Terminal size={10} aria-hidden="true" className="shrink-0" />
+              <span>No shell</span>
+            </span>
+          )}
           {!remote && (
             <button
               onClick={openPromptModal}
diff --git a/client/src/components/cos/tabs/AgentCard.test.jsx b/client/src/components/cos/tabs/AgentCard.test.jsx
index b7a0bb282d..6089ab6c18 100644
--- a/client/src/components/cos/tabs/AgentCard.test.jsx
+++ b/client/src/components/cos/tabs/AgentCard.test.jsx
@@ -368,3 +368,51 @@ describe('AgentCard task description (#4170)', () => {
     expect(screen.queryByRole('button', { name: /Show more/ })).not.toBeInTheDocument();
   });
 });
+
+describe('AgentCard missing shell explanation', () => {
+  const running = (metadata) => ({
+    ...agent,
+    status: 'running',
+    completedAt: null,
+    metadata: { ...agent.metadata, ...metadata },
+  });
+
+  const renderCard = (a) => render(
+    <MemoryRouter>
+      <AgentCard agent={a} />
+    </MemoryRouter>
+  );
+
+  it('says why a public-review stage has no shell instead of leaving the card silent', () => {
+    // These stages are forced headless even on a TUI provider, so the "Open
+    // Shell" link never appears. Silence made a slow run look wedged with
+    // nowhere to look.
+    renderCard(running({ publicReviewPosture: 'sandboxed-actions', executionMode: 'direct' }));
+
+    expect(screen.queryByText('Open Shell')).not.toBeInTheDocument();
+    expect(screen.getByText('No shell')).toBeInTheDocument();
+    expect(screen.getByTitle(/public-review stage always runs headless/)).toBeInTheDocument();
+  });
+
+  it('stays silent on a TUI run that has not registered its session yet', () => {
+    // `executionMode` is stamped at registration but `tuiSessionId` only lands
+    // once the PTY attaches, so every healthy TUI spawn passes through this
+    // state — a chip here would put the "looks wedged" noise straight back.
+    renderCard(running({ executionMode: 'tui', phase: 'initializing' }));
+
+    expect(screen.queryByText('No shell')).not.toBeInTheDocument();
+  });
+
+  it('adds no chip to an ordinary headless CLI agent — none was ever expected', () => {
+    renderCard(running({ executionMode: 'direct' }));
+
+    expect(screen.queryByText('No shell')).not.toBeInTheDocument();
+  });
+
+  it('links to the live shell, with no explanation chip, once a session exists', () => {
+    renderCard(running({ executionMode: 'tui', tuiSessionId: 'sess-abcdef123' }));
+
+    expect(screen.getByText('Open Shell')).toBeInTheDocument();
+    expect(screen.queryByText('No shell')).not.toBeInTheDocument();
+  });
+});
diff --git a/server/cos-runner/index.js b/server/cos-runner/index.js
index fb6e84ca97..a0c6a61d86 100644
--- a/server/cos-runner/index.js
+++ b/server/cos-runner/index.js
@@ -24,6 +24,7 @@ import { commandExists } from '../lib/commandExists.js';
 import { adoptNpmGlobalBinDir } from '../lib/npmGlobalBin.js';
 import { findCommandOnPath } from '../lib/processEnv.js';
 import { createCodexStderrFormatter } from '../lib/codexCliOutput.js';
+import { createStreamingAnsiStripper } from '../lib/ansiStrip.js';
 import { createStreamJsonParser } from './streamJsonParser.js';
 import { loadState, saveState, withState } from './runnerState.js';
 import { getProcessStats, checkProcessRunning } from './processStats.js';
@@ -504,6 +505,13 @@ app.post('/spawn', async (req, res) => {
     rawStreamBuffer: '',
     streamParser,
     codexStderrFormatter,
+    // Per-stream ANSI strippers, mirroring spawnDirectly's headless path — the
+    // same providers land here when the run is dispatched through the runner, so
+    // without these the `[stderr] [0m` noise reproduces on that half of the
+    // dispatch matrix. Stateful: each buffers an escape split across two chunks.
+    // A stream-json stdout is NDJSON with no raw ESC byte, so it skips the scan.
+    stripStdoutAnsi: isStreamJson ? (text) => text : createStreamingAnsiStripper(),
+    stripStderrAnsi: createStreamingAnsiStripper(),
     workspacePath: cwd
   });
 
@@ -518,8 +526,8 @@ app.post('/spawn', async (req, res) => {
 
   // Handle stdout
   claudeProcess.stdout.on('data', (data) => {
-    const text = data.toString();
     const agent = activeAgents.get(agentId);
+    const text = agent?.stripStdoutAnsi ? agent.stripStdoutAnsi(data.toString()) : data.toString();
 
     if (agent?.streamParser) {
       // Parse stream-json and emit extracted text lines (cap buffer at 512KB for error analysis)
@@ -533,7 +541,11 @@ app.post('/spawn', async (req, res) => {
         emitToServer('agent:output', { agentId, text: line + '\n' });
       }
     } else {
-      // Non-stream providers: emit raw stdout as before
+      // Non-stream providers: emit stdout as-is once decolored. A chunk that was
+      // purely terminal control has nothing left to show. Unlike stderr below,
+      // whitespace is NOT dropped here — a blank line is legitimate formatting
+      // when it isn't wearing an `[stderr]` tag.
+      if (!text) return;
       if (agent) {
         agent.outputBuffer += text;
       }
@@ -544,8 +556,9 @@ app.post('/spawn', async (req, res) => {
   // Handle stderr
   claudeProcess.stderr.on('data', (data) => {
     const agent = activeAgents.get(agentId);
+    const decolored = agent?.stripStderrAnsi ? agent.stripStderrAnsi(data.toString()) : data.toString();
     if (agent?.codexStderrFormatter) {
-      const lines = agent.codexStderrFormatter.processChunk(data.toString());
+      const lines = agent.codexStderrFormatter.processChunk(decolored);
       for (const line of lines) {
         agent.outputBuffer += line + '\n';
         emitToServer('agent:output', { agentId, text: line + '\n' });
@@ -553,7 +566,11 @@ app.post('/spawn', async (req, res) => {
       return;
     }
 
-    const text = `[stderr] ${data.toString()}`;
+    // A chunk that decolors down to whitespace was pure terminal control
+    // (`opencode run` emits a bare reset per progress redraw). Tagging it
+    // `[stderr]` would add one blank noise line to the tail per redraw.
+    if (!decolored.trim()) return;
+    const text = `[stderr] ${decolored}`;
     if (agent) agent.outputBuffer += text;
     emitToServer('agent:output', { agentId, text });
   });
diff --git a/server/cos-runner/index.test.js b/server/cos-runner/index.test.js
index 040a68ec50..0424ed6134 100644
--- a/server/cos-runner/index.test.js
+++ b/server/cos-runner/index.test.js
@@ -188,3 +188,40 @@ describe('cos-runner durable TUI ownership (#3202)', () => {
     expect(RUNNER_SRC).toMatch(/io\.emit\('tui:exit',[\s\S]{0,350}?\.\.\.\(outputTail \? \{ outputTail \} : \{\}\)/);
   });
 });
+
+// The runner is the second headless spawner: the same providers land here when a
+// task is dispatched with `useRunner`, and its stdout/stderr handlers are a twin
+// of spawnDirectly's. `opencode run` colors its progress line, and those raw
+// escapes reached the agent card as `[stderr] [0m` noise — a working agent read
+// as a wedged one. The behavioral coverage lives in agentCliSpawning.test.js
+// against the real handlers; this pins that the runner twin was not left behind.
+describe('cos-runner output — ANSI decoloring parity with spawnDirectly', () => {
+  it('imports the shared streaming stripper rather than rolling its own regex', () => {
+    expect(RUNNER_SRC).toMatch(
+      /import\s*\{[^}]*\bcreateStreamingAnsiStripper\b[^}]*\}\s*from\s*'\.\.\/lib\/ansiStrip\.js';/
+    );
+  });
+
+  it('gives each agent its own stdout/stderr strippers, skipping NDJSON stdout', () => {
+    // Per agent, not per module: the stripper buffers an escape split across two
+    // chunks, so one shared instance would interleave two agents' tails.
+    expect(RUNNER_SRC).toMatch(
+      /stripStdoutAnsi:\s*isStreamJson\s*\?\s*\(text\)\s*=>\s*text\s*:\s*createStreamingAnsiStripper\(\)/
+    );
+    expect(RUNNER_SRC).toMatch(/stripStderrAnsi:\s*createStreamingAnsiStripper\(\)/);
+  });
+
+  it('decolors both streams before they reach the buffer, formatter, or socket', () => {
+    expect(RUNNER_SRC).toMatch(/agent\?\.stripStdoutAnsi\s*\?\s*agent\.stripStdoutAnsi\(data\.toString\(\)\)/);
+    expect(RUNNER_SRC).toMatch(/agent\?\.stripStderrAnsi\s*\?\s*agent\.stripStderrAnsi\(data\.toString\(\)\)/);
+    // The codex formatter must see the decolored text too — it matches prose that
+    // an SGR pair would otherwise split.
+    expect(RUNNER_SRC).toMatch(/codexStderrFormatter\.processChunk\(decolored\)/);
+    // And the `[stderr]` tag is built from the decolored chunk, never the raw one.
+    expect(RUNNER_SRC).toMatch(/const text = `\[stderr\] \$\{decolored\}`/);
+  });
+
+  it('drops a chunk that was only terminal control instead of emitting a blank line', () => {
+    expect(RUNNER_SRC).toMatch(/if \(!decolored\.trim\(\)\) return;/);
+  });
+});
diff --git a/server/services/agentCliSpawning.js b/server/services/agentCliSpawning.js
index 7696c1f3e3..0b80299e67 100644
--- a/server/services/agentCliSpawning.js
+++ b/server/services/agentCliSpawning.js
@@ -26,6 +26,7 @@ import { normalizeReviewers } from '../lib/validation.js';
 import { resolveReviewLoopOptions } from './codeReview.js';
 import { safeJSONParse, PATHS } from '../lib/fileUtils.js';
 import { createCodexStderrFormatter } from '../lib/codexCliOutput.js';
+import { createStreamingAnsiStripper } from '../lib/ansiStrip.js';
 import { PROVIDER_TYPES } from '../lib/aiToolkit/constants.js';
 import { createImmediateFallbackSignalDetector } from '../lib/aiToolkit/errorDetection.js';
 import { prepareCliPrompt } from '../lib/cliProviderArgs.js';
@@ -533,6 +534,18 @@ export async function spawnDirectly({
   const isStreamJson = cliConfig.streamFormat === 'stream-json';
   const streamParser = isStreamJson ? createStreamJsonParser() : null;
   const codexStderrFormatter = provider.id === 'codex' ? createCodexStderrFormatter(prompt) : null;
+  // A headless CLI still colors its progress output: `opencode run` emits bare
+  // `\x1B[0m` resets around its status line. Those bytes reached output.txt and
+  // the live tail verbatim, and the browser drops only the ESC itself — so the
+  // card rendered `[stderr] [0m` and a working agent was indistinguishable from
+  // a wedged one. Strip per stream (each stripper is stateful, buffering an
+  // escape split across two `data` chunks) BEFORE the fallback-signal detector,
+  // which matches on provider text that color codes would otherwise break up.
+  // A stream-json stdout is NDJSON, which escapes an ESC into its six-character
+  // JSON form and never carries the raw byte — so the busiest stdout stream in
+  // the system skips the scan entirely.
+  const stripStdoutAnsi = isStreamJson ? (text) => text : createStreamingAnsiStripper();
+  const stripStderrAnsi = createStreamingAnsiStripper();
   let immediateFallbackAnalysis = null;
   const detectImmediateFallbackSignal = createImmediateFallbackSignalDetector();
 
@@ -610,7 +623,8 @@ export async function spawnDirectly({
 
   handleStdout = (data) => {
     try {
-      const text = data.toString();
+      const raw = data.toString();
+      const text = stripStdoutAnsi(raw);
       // Detect fallback signals SYNCHRONOUSLY, before enqueuing any transcript
       // mutation — a blocked earlier write must never delay killing the provider
       // on a usage-limit signal (#2384).
@@ -618,7 +632,9 @@ export async function spawnDirectly({
       // Serialize the transcript body so two `data` events can't interleave their
       // awaits and reorder output.txt / the batched live tail.
       enqueueTranscriptWrite(async () => {
-        await recordFirstOutput('cli-stdout', text.length);
+        // Raw length, not stripped: a chunk that was ONLY color codes is still
+        // proof the child is alive, and reporting 0 would read as "no output yet".
+        await recordFirstOutput('cli-stdout', raw.length);
         if (!hasStartedWorking) {
           hasStartedWorking = true;
           await updateAgent(agentId, { metadata: { phase: 'working' } });
@@ -636,7 +652,11 @@ export async function spawnDirectly({
           outputBatcher.push(lines);
           await writeFile(outputFile, outputBuffer).catch(() => {});
         } else {
-          // Non-stream providers: emit raw stdout as before
+          // Non-stream providers: emit stdout as-is once decolored. A chunk that
+          // was purely terminal control has nothing left to show. Unlike stderr
+          // below, whitespace is NOT dropped here — a blank line is legitimate
+          // formatting when it isn't wearing an `[stderr]` tag.
+          if (!text) return;
           outputBuffer += text;
           await writeFile(outputFile, outputBuffer).catch(() => {});
           outputBatcher.push(text);
@@ -649,11 +669,12 @@ export async function spawnDirectly({
 
   handleStderr = (data) => {
     try {
-      const text = data.toString();
+      const raw = data.toString();
+      const text = stripStderrAnsi(raw);
       // Synchronous fallback detection before the serialized write (see stdout).
       stopForImmediateFallbackSignal(`[stderr] ${text}`);
       enqueueTranscriptWrite(async () => {
-        await recordFirstOutput('cli-stderr', text.length);
+        await recordFirstOutput('cli-stderr', raw.length);
         // Codex stderr: show thinking + tool names, skip config dump and command output
         if (codexStderrFormatter) {
           const lines = codexStderrFormatter.processChunk(text);
@@ -662,6 +683,10 @@ export async function spawnDirectly({
           await writeFile(outputFile, outputBuffer).catch(() => {});
           return;
         }
+        // A chunk that decolors down to whitespace was pure terminal control
+        // (`opencode run` emits a bare reset per progress redraw). Tagging it
+        // `[stderr]` would add one blank noise line to the tail per redraw.
+        if (!text.trim()) return;
         outputBuffer += `[stderr] ${text}`;
         await writeFile(outputFile, outputBuffer).catch(() => {});
         outputBatcher.push(`[stderr] ${text}`);
diff --git a/server/services/agentCliSpawning.test.js b/server/services/agentCliSpawning.test.js
index 6b5655af3b..b4da378c21 100644
--- a/server/services/agentCliSpawning.test.js
+++ b/server/services/agentCliSpawning.test.js
@@ -929,6 +929,107 @@ describe('stream error containment', () => {
     expect(usageIdx).toBeGreaterThan(firstIdx);
   });
 
+  // A headless CLI still colors its progress feed. `opencode run` wraps its
+  // status line in bare SGR resets, and those bytes used to reach the transcript
+  // verbatim — the browser drops only the ESC, so the agent card rendered
+  // `[stderr] [0m` and a working agent read as a wedged one.
+  describe('ANSI decoloring of headless CLI output', () => {
+    const textArgs = () => ({
+      ...minimalArgs,
+      cliConfig: { command: 'opencode', args: ['run'], stdinMode: 'prompt', streamFormat: 'text' },
+    });
+
+    const emittedLines = () =>
+      agentStateMocks.appendAgentOutputLines.mock.calls.flatMap(([, batch]) => batch);
+
+    // The shared mock accumulates across the whole file; these assertions are
+    // about the exact transcript ONE run produced.
+    beforeEach(() => agentStateMocks.appendAgentOutputLines.mockClear());
+
+    it('strips color codes from stdout and stderr instead of leaking them into the transcript', async () => {
+      const spawnPromise = spawnDirectly(textArgs());
+      await new Promise((r) => setTimeout(r, 10));
+
+      fakeProcess.stdout.emit('data', Buffer.from('\x1B[32mbuilding\x1B[0m\n'));
+      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m> build · some-model\n'));
+      await new Promise((r) => setTimeout(r, 30));
+
+      fakeProcess.emit('close', 0);
+      await spawnPromise.catch(() => {});
+
+      const lines = emittedLines();
+      expect(lines).toContain('building\n');
+      expect(lines).toContain('[stderr] > build · some-model\n');
+      expect(lines.join('')).not.toMatch(/\x1B|\[0m|\[32m/);
+    });
+
+    it('reassembles an escape sequence split across two chunks rather than leaking its tail', async () => {
+      const spawnPromise = spawnDirectly(textArgs());
+      await new Promise((r) => setTimeout(r, 10));
+
+      // The reset straddles the chunk boundary: a per-chunk strip would emit `2m…`.
+      fakeProcess.stdout.emit('data', Buffer.from('ready\x1B['));
+      await new Promise((r) => setTimeout(r, 20));
+      fakeProcess.stdout.emit('data', Buffer.from('32mgreen\n'));
+      await new Promise((r) => setTimeout(r, 20));
+
+      fakeProcess.emit('close', 0);
+      await spawnPromise.catch(() => {});
+
+      expect(emittedLines().join('')).toBe('readygreen\n');
+    });
+
+    it('drops a chunk that was ONLY terminal control rather than tagging a blank [stderr] line', async () => {
+      const spawnPromise = spawnDirectly(textArgs());
+      await new Promise((r) => setTimeout(r, 10));
+
+      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
+      fakeProcess.stdout.emit('data', Buffer.from('\x1B[0m'));
+      await new Promise((r) => setTimeout(r, 30));
+
+      fakeProcess.emit('close', 0);
+      await spawnPromise.catch(() => {});
+
+      expect(emittedLines()).not.toContain('[stderr] ');
+      expect(emittedLines().some((line) => line.trim() === '')).toBe(false);
+    });
+
+    it('still records a colors-only chunk as run output — it is proof the child is alive', async () => {
+      // Counting the DECOLORED length would report zero bytes and file a run that
+      // was steadily redrawing its progress line as having produced nothing.
+      appendRunEvent.mockClear();
+      const spawnPromise = spawnDirectly(textArgs());
+      await new Promise((r) => setTimeout(r, 10));
+
+      fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
+      await new Promise((r) => setTimeout(r, 30));
+
+      const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].data).toMatchObject({ source: 'cli-stderr' });
+
+      fakeProcess.emit('close', 0);
+      await spawnPromise.catch(() => {});
+    });
+
+    it('detects a fallback signal that the CLI printed with color codes inside it', async () => {
+      // The detector matches provider prose; an SGR pair mid-sentence used to
+      // split the phrase and let a usage-limit signal through unnoticed.
+      killProcessTree.mockClear();
+      const spawnPromise = spawnDirectly(textArgs());
+      await new Promise((r) => setTimeout(r, 10));
+
+      fakeProcess.stdout.emit('data', Buffer.from('\x1B[33mNow using \x1B[1mextra usage\x1B[0m\n'));
+
+      expect(killProcessTree).toHaveBeenCalledTimes(1);
+      fakeProcess.killed = true;
+
+      await new Promise((r) => setTimeout(r, 20));
+      fakeProcess.emit('close', 143);
+      await spawnPromise.catch(() => {});
+    });
+  });
+
   it('routes the CLI command through prepareCliSpawn and spawns its resolved+wrapped result (#2243)', async () => {
     // The reported bug: on Windows a bare `opencode`/`claude` .cmd shim can't be
     // spawned directly under shell:false → ENOENT (-4058) → startup-failure.
diff --git a/server/services/agentLifecycle.js b/server/services/agentLifecycle.js
index 28a6363c67..9d067d01a6 100644
--- a/server/services/agentLifecycle.js
+++ b/server/services/agentLifecycle.js
@@ -763,6 +763,13 @@ async function runAgentSpawn(task) {
       phase: 'initializing',
       useRunner: dispatchUseRunner,
       executionMode,
+      // The public-review posture this run executes under (null for an ordinary
+      // task). Projected beside `executionMode` because the UI cannot otherwise
+      // explain why the card has no "Open Shell" link: a public-review stage is
+      // forced headless (`spawnHeadless = publicReview || !isTui` above) even
+      // when the user configured it onto a TUI provider, so without this the
+      // card is indistinguishable from an agent whose PTY failed to attach.
+      publicReviewPosture,
       taskAnalysisType: task.metadata?.analysisType || null,
       taskReviewType: task.metadata?.reviewType || null,
       taskApp: task.metadata?.app || null,
diff --git a/server/services/agentLifecycle.test.js b/server/services/agentLifecycle.test.js
index e0899cbe61..4343002f1e 100644
--- a/server/services/agentLifecycle.test.js
+++ b/server/services/agentLifecycle.test.js
@@ -737,6 +737,16 @@ describe('runAgentSpawn source — instance provenance + claim ordering (#1563)'
     expect(metaSlice).toContain('configClaimFlow: isClaimFlowTask(task, isTruthyMeta)');
     expect(metaSlice.indexOf('configClaimFlow')).toBeGreaterThan(metaSlice.indexOf('configOpenPR'));
   });
+
+  it('projects the public-review posture so the UI can explain the missing shell link', () => {
+    // `spawnHeadless = publicReview || !isTui` forces a public-review stage
+    // headless even on a TUI provider, so its card never gets an "Open Shell"
+    // link. Without this projection the card cannot tell that apart from a PTY
+    // that failed to attach, and the run reads as wedged.
+    const registerIdx = RUN_SPAWN_BODY.indexOf('registerAgent(agentId, task.id, {');
+    const metaSlice = RUN_SPAWN_BODY.slice(registerIdx, RUN_SPAWN_BODY.indexOf('\n  });', registerIdx));
+    expect(metaSlice).toMatch(/^\s*publicReviewPosture,$/m);
+  });
 });
 
 // These used to be three source-regex assertions pinning a hand-spread env