codehere 0.6.1 → 0.7.0

package/dist/infrastructure/orchestration/progress-aggregator.js

@@ -159,11 +159,47 @@ export class ProgressAggregator {
             return this.ingestGemini(type, data);
         if (this.agentId === 'aider')
             return this.ingestAider(type, data);
+        if (this.agentId === 'opencode')
+            return this.ingestOpencode(type, data);
         return false;
     }
+    // OpenCode · `run --format json` emits tool_use with shape
+    // { type:'tool_use', part:{ tool, state:{ input, output, status } } }. Was
+    // never wired into the aggregator (opencode showed ZERO timeline steps — a
+    // real gap surfaced by the mock harness). Build a step on the terminal
+    // (status==='completed') event so opencode is a first-class agent.
+    ingestOpencode(type, data) {
+        if (type !== 'tool_use')
+            return false;
+        const part = (data.part ?? {});
+        if (part.state?.status && part.state.status !== 'completed')
+            return false; // skip in-flight
+        const map = {
+            bash: 'Bash',
+            read: 'Read',
+            write: 'Write',
+            edit: 'Edit',
+            grep: 'Grep',
+            glob: 'Glob',
+            webfetch: 'WebFetch',
+            websearch: 'WebSearch',
+        };
+        const tool = map[String(part.tool ?? '').toLowerCase()] || 'Bash';
+        const label = labelForClaudeToolUse(tool, part.state?.input);
+        const output = typeof part.state?.output === 'string' ? part.state.output : '';
+        this._steps.push({
+            label,
+            state: 'done',
+            startedAt: Date.now(),
+            completedAt: Date.now(),
+            ...(output ? { output: truncateOutput(output) } : {}),
+        });
+        return true;
+    }
     /** Flush: mark every still-active step as failed (called on abnormal exit). */
     finalize(status) {
-        let changed = false;
+        // Surface any trailing aider reasoning that had no following action.
+        let changed = this.flushAiderSay();
         for (const s of this._steps) {
             if (s.state === 'active' || s.state === 'pending') {
                 s.state = status === 'completed' ? 'done' : 'failed';
@@ -184,7 +220,22 @@ export class ProgressAggregator {
             let changed = false;
             for (const blk of content) {
                 const b = (blk && typeof blk === 'object' ? blk : {});
-                if (b.type === 'tool_use') {
+                if (b.type === 'text' && typeof b.text === 'string' && b.text.trim()) {
+                    // The agent's own words/reasoning. In claude's stream the text block
+                    // precedes the tool_use in the same message — capture it first so the
+                    // timeline reads "explains → acts". This is the "watch it work" signal
+                    // the agent already produces; we were dropping it.
+                    const said = b.text.trim();
+                    this._steps.push({
+                        kind: 'say',
+                        label: said.length > 500 ? said.slice(0, 500) + '\\u2026' : said,
+                        state: 'done',
+                        startedAt: Date.now(),
+                        completedAt: Date.now(),
+                    });
+                    changed = true;
+                }
+                else if (b.type === 'tool_use') {
                     const id = String(b.id ?? '');
                     const label = labelForClaudeToolUse(String(b.name ?? ''), b.input);
                     const idx = this.addStep(label, 'active');
@@ -316,7 +367,6 @@ export class ProgressAggregator {
      * blocking parity. v0.5 ships observability; v0.5.x or v0.6 ships blocking
      * once Path A merges.
      */
-    // eslint-disable-next-line no-control-regex
     static ANSI_RE = /\x1b\[[0-9;]*m/g;
     /**
      * Per-instance set of file paths aider just created via "Creating empty file ...".
@@ -341,6 +391,23 @@ export class ProgressAggregator {
      */
     aiderRunningStepIdx = null;
     aiderOutputBuffer = [];
+    /**
+     * A1 (PRODUCT_STATE §0 NEXT #1) — Aider's natural-language reasoning.
+     * Aider streams its plain-English explanation to stdout BEFORE the
+     * SEARCH/REPLACE blocks and "Applied edit" lines. We were dropping every
+     * such line. Mirror ingestClaude's text-block handling: collect consecutive
+     * prose lines (skipping diff fences + SEARCH/REPLACE markers + aider's own
+     * status noise) and flush them as ONE kind:'say' step before the next
+     * action — the "watch it work" signal across aider, not just claude.
+     */
+    aiderSayBuffer = [];
+    aiderInFence = false;
+    aiderInDiff = false;
+    /** Aider stdout lines that are status/noise, never reasoning prose. The
+     *  "must contain a space + length >= 4" guard in collectAiderSay already
+     *  drops bare filenames, fence langs and spinner rules; this catches the
+     *  noisy lines that DO contain spaces. */
+    static AIDER_NONPROSE_RE = /^(=======\s*$|Tokens:|Cost:|Commit [0-9a-f]|Applied edit to |Running |Creating empty file |Did not |Added \S+ to the chat|Removed \S+ from the chat|No changes made|Warning: |Scanning repo|Initial repo scan|Repo-map:|Main model:|Weak model:|Model:|Git repo:|Use \/|aider |Committing )/;
     aiderFlushOutput() {
         if (this.aiderRunningStepIdx === null)
             return;
@@ -356,6 +423,50 @@ export class ProgressAggregator {
         this.aiderRunningStepIdx = null;
         this.aiderOutputBuffer = [];
     }
+    /** Flush buffered aider prose as one kind:'say' step. Returns true if a step
+     *  was pushed (so finalize can fold it into its changed flag). */
+    flushAiderSay() {
+        if (this.aiderSayBuffer.length === 0)
+            return false;
+        const said = this.aiderSayBuffer.join(' ').replace(/\s+/g, ' ').trim();
+        this.aiderSayBuffer = [];
+        if (!said)
+            return false;
+        this._steps.push({
+            kind: 'say',
+            label: said.length > 500 ? said.slice(0, 500) + '…' : said,
+            state: 'done',
+            startedAt: Date.now(),
+            completedAt: Date.now(),
+        });
+        return true;
+    }
+    /** Collect one aider stdout line as reasoning prose unless it's a fence, a
+     *  SEARCH/REPLACE marker/body, status noise, or a bare token. */
+    collectAiderSay(line) {
+        if (line.startsWith('```')) {
+            this.aiderInFence = !this.aiderInFence;
+            return;
+        }
+        if (this.aiderInFence)
+            return;
+        if (/^<<<<<<< SEARCH/.test(line)) {
+            this.aiderInDiff = true;
+            return;
+        }
+        if (/^>>>>>>> REPLACE/.test(line)) {
+            this.aiderInDiff = false;
+            return;
+        }
+        if (this.aiderInDiff)
+            return;
+        if (ProgressAggregator.AIDER_NONPROSE_RE.test(line))
+            return;
+        // Require a space + minimum length so filenames/code tokens don't leak in.
+        if (line.length < 4 || !line.includes(' '))
+            return;
+        this.aiderSayBuffer.push(line);
+    }
     ingestAider(type, data) {
         if (type !== 'stdout')
             return false;
@@ -377,6 +488,7 @@ export class ProgressAggregator {
             // P22 slice 4 — flush the previous Running step's buffer before
             // starting the new one. New step is the active output target.
             this.aiderFlushOutput();
+            this.flushAiderSay(); // emit any reasoning prose that preceded this run
             const idx = this._steps.length;
             this._steps.push({
                 label: truncate('Run ' + m[1]),
@@ -394,6 +506,7 @@ export class ProgressAggregator {
             // P22 slice 4 — flush any in-flight running-step output before
             // recording the edit (which is a new aider-pattern signal).
             this.aiderFlushOutput();
+            this.flushAiderSay(); // emit reasoning prose that preceded this edit
             // If aider JUST created this file, the Write step already represents the
             // action; skip the Edit step that aider emits for the initial content.
             // Clear from the set after consuming so subsequent edits to the same
@@ -415,6 +528,7 @@ export class ProgressAggregator {
         if (m) {
             const path = m[1];
             this.aiderFlushOutput();
+            this.flushAiderSay(); // emit reasoning prose that preceded this write
             this.aiderJustCreated.add(path);
             // Use "Write" to align with Claude/Gemini's net-new-file label vocabulary.
             this._steps.push({
@@ -439,6 +553,11 @@ export class ProgressAggregator {
                 step.output = truncateOutput(this.aiderOutputBuffer.join('\n'));
             return true; // mark as "step changed" so the SSE re-emits codehere:steps
         }
+        // Outside a Running window: aider's natural-language reasoning. Buffer it
+        // (skipping diff fences + markers + status noise); flushed as one kind:'say'
+        // step before the next action or at finalize. (PRODUCT_STATE §0 NEXT #1)
+        if (this.aiderRunningStepIdx === null)
+            this.collectAiderSay(line);
         return false;
     }
     ingestCodex(type, data) {
@@ -464,8 +583,7 @@ export class ProgressAggregator {
         if (itemType === 'tool_call' || itemType === 'local_shell_call') {
             const name = String(item.tool_name ?? item.name ?? 'tool');
             // Tool-call items may carry a `result` or `output` field too.
-            const result = (typeof item.result === 'string' ? item.result : '') ||
-                (typeof item.output === 'string' ? item.output : '');
+            const result = (typeof item.result === 'string' ? item.result : '') || (typeof item.output === 'string' ? item.output : '');
             this._steps.push({
                 label: truncate(name),
                 state: 'done',
@@ -475,6 +593,61 @@ export class ProgressAggregator {
             });
             return true;
         }
+        // file_change — codex emits one item per Edit/Write/Delete batch. The audit
+        // mirror (codex-adapter.ts) already handles these; the timeline-step path was
+        // dropping them, so real codex file edits were invisible in "watch it work"
+        // (mock-currency audit 2026-06-02 caught this — the mock emits the real shape).
+        if (itemType === 'file_change') {
+            const changes = Array.isArray(item.changes)
+                ? item.changes
+                : [];
+            let changed = false;
+            for (const ch of changes) {
+                const path = String(ch.path ?? '');
+                const kind = String(ch.kind ?? 'update');
+                const toolName = kind === 'add' ? 'Write' : kind === 'delete' ? 'Delete' : 'Edit';
+                // Label directly so the path always shows (labelForClaudeToolUse only
+                // knows Edit/Write/Read — it drops the path for Delete).
+                this._steps.push({
+                    label: path ? toolName + ' ' + path : toolName,
+                    state: 'done',
+                    startedAt: Date.now(),
+                    completedAt: Date.now(),
+                });
+                changed = true;
+            }
+            return changed;
+        }
+        // mcp_tool_call + web_search — real visible actions the codex-adapter mirrors
+        // to audit; surface them as timeline steps too (2026-06-02 follow-up, Ega-approved
+        // class: "watch it work"). Labels mirror codex-adapter conventions.
+        if (itemType === 'mcp_tool_call') {
+            const server = String(item.server ?? '');
+            const tool = String(item.tool ?? 'mcp');
+            this._steps.push({
+                label: 'MCP · ' + (server ? server + '.' : '') + tool,
+                state: 'done',
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+            });
+            return true;
+        }
+        if (itemType === 'web_search') {
+            const q = String(item.query ?? '').trim().slice(0, 80);
+            this._steps.push({
+                label: q ? 'Web search · ' + q : 'Web search',
+                state: 'done',
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+            });
+            return true;
+        }
+        // NOTE (mock-currency 2026-06-02): codex `agent_message` is intentionally NOT
+        // captured here — a prior decision (pm-layers.test.ts "just chatter, not a
+        // step") drops it. This is INCONSISTENT with ingestClaude/ingestAider, which
+        // DO capture agent narration as kind:'say' (per #45 + A1 "watch it work").
+        // Resolving that inconsistency is a product taste call → flagged for Ega in
+        // mock-currency-2026-06-02.md, not changed unilaterally by the autonomous loop.
         return false;
     }
 }

package/dist/infrastructure/orchestration/session-manager.js

@@ -22,15 +22,15 @@ import { buildGenericAdapter, loadAgentsConfig } from './generic-cli-adapter.js'
 import { buildConductorAdapter } from './conductor-adapter.js';
 import { seedAgentsConfig } from './agents-config-seed.js';
 import { AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
-import { appendSpawned, appendCompleted, appendFinalReport, loadRecent } from './session-persistence.js';
+import { appendSpawned, appendCompleted, appendFinalReport, loadRecent, } from './session-persistence.js';
 import { generateFinalReport, printFinalReportToTerminal } from '../../application/use-cases/generate-final-report.js';
 import { mirrorSpawnedToThread, mirrorCompletedToThread } from '../storage/project-thread-mirror.js';
 import { scanPromptBeforeSpawn } from '../hooks/pre-prompt-scan.js';
 import { generateNarration } from '../../application/use-cases/generate-narration.js';
 import { randomUUID } from 'crypto';
 import { classifyFailoverEligibility } from './failover-classifier.js';
-import { resolveFailoverTarget, toAvailability, } from './failover-policy.js';
-import { loadFailoverConfig, resolveChain } from './failover-config.js';
+import { resolveFailoverTarget, toAvailability } from './failover-policy.js';
+import { loadFailoverConfig } from './failover-config.js';
 import { enrichPromptWithPackSync, compileSessionPackSync, persistContextPack } from './graphify-context.js';
 import { buildFailoverHandoff, enrichPromptWithHandoff } from './context-handoff.js';
 import { mirrorFailoverToThread } from '../storage/project-thread-mirror.js';
@@ -39,7 +39,13 @@ import { mirrorFailoverToThread } from '../storage/project-thread-mirror.js';
 // order. Built-in adapters first; user-config-driven ones appended from
 // ~/.codehere/agents.yaml (generic-cli-adapter). isInstalled() gates visibility
 // so an adapter registering for an un-installed CLI is harmless.
-const BUILTIN_REGISTRY = [ClaudeCodeAdapter, CodexAdapter, AiderAdapter, OpenCodeAdapter, GeminiAdapter];
+const BUILTIN_REGISTRY = [
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    AiderAdapter,
+    OpenCodeAdapter,
+    GeminiAdapter,
+];
 // Seed the default agents.yaml if this user has never configured one, so Gemini
 // / Cursor / Pi / Antigravity / Goose appear in the registry pre-wired. They
 // stay hidden in the UI until isInstalled() flips to true. Idempotent.
@@ -145,27 +151,39 @@ export class SessionManager {
     narrationBySession = new Map();
     narrationTimers = new Map();
     narrationStepsAtLastFire = new Map();
+    /** Stall watchdog (dogfood 2026-05-27 #1): a spawned agent can hang with no
+     *  output and sit "running" forever (opencode did exactly this). We track the
+     *  timestamp of the last event from each session and, if a running session
+     *  goes silent past the stall window, kill it and record an honest reason so
+     *  the UI shows "stopped — no response", never a fake "running" or a normal row. */
+    stallTimers = new Map();
+    lastActivityBySession = new Map();
+    stalledBySession = new Map();
     /** Stores active failover offers keyed by sessionId+target. API layer
      *  reads these via getFailoverOffers() for the /api/failover-offers endpoint. */
     failoverOffers;
     /** Tracks the failover error code per session so acceptFailover can emit
-      *  the correct reason in the thread event. Populated by handleFailover. */
+     *  the correct reason in the thread event. Populated by handleFailover. */
     failoverReasonBySession = new Map();
     /** Session threading — tracks which session continued as which after failover.
-      *  continuedAsBySession: original → new session ID
-      *  continuedFromBySession: new → original session ID */
+     *  continuedAsBySession: original → new session ID
+     *  continuedFromBySession: new → original session ID */
     continuedAsBySession = new Map();
     continuedFromBySession = new Map();
     /** Final Report failure tracking — when generateFinalReport rejects, we
-      *  record it so the API can return a definitive "failed" status instead
-      *  of leaving the UI showing "Generating report…" forever. */
+     *  record it so the API can return a definitive "failed" status instead
+     *  of leaving the UI showing "Generating report…" forever. */
     failedReportBySession = new Set();
     spawn(prompt, agentId = 'claude-code', options) {
         const adapter = getAdapter(agentId);
         if (!adapter) {
             throw new Error(`Unknown agent: ${agentId}. Registered: ${REGISTRY.map((a) => a.id).join(', ')}`);
         }
-        if (!adapter.isInstalled()) {
+        // CODEHERE_MOCK spawns a synthetic agent (mock REPL), so the real CLI need
+        // not be installed — bypass the readiness gate. Makes the mock harness truly
+        // zero-dependency (dogfood/dev without any agent CLI installed).
+        const mockMode = process.env.CODEHERE_MOCK === '1' || process.env.CODEHERE_MOCK === 'true';
+        if (!mockMode && !adapter.isInstalled()) {
             throw new Error(`Agent ${adapter.label} (${adapter.id}) is not installed on this machine`);
         }
         // Cross-vendor pre-prompt scan (task #110, slice 1). Closes the gap
@@ -215,7 +233,10 @@ export class SessionManager {
             cwd,
             startedAt: session.startedAt,
         });
+        this.lastActivityBySession.set(session.sessionId, Date.now());
         const unsubscribe = session.subscribe((event) => {
+            // Any event = the agent is alive. Reset the stall clock. (watchdog)
+            this.lastActivityBySession.set(session.sessionId, Date.now());
             // ── Failover check — intercept rate-limit / quota errors before exit ──
             // Adapters emit 'codehere:error' (structured: { code, message, recovery })
             // or 'error' (spawn-level: { message }). Both need classification.
@@ -245,6 +266,7 @@ export class SessionManager {
                 completedAt,
                 steps: session.steps ? [...session.steps] : undefined,
                 artifacts: session.artifacts,
+                stalledReason: this.stalledBySession.get(session.sessionId)?.reason,
             });
             // v0.6.0 M1+M7 — forward-mirror completion to project thread.
             mirrorCompletedToThread({
@@ -305,7 +327,10 @@ export class SessionManager {
             // or pack compilation may fail. All degrade silently.
             void Promise.resolve().then(() => {
                 try {
-                    const stepsStr = session.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                    const stepsStr = session.steps
+                        ?.map((s) => `${s.label}: ${s.output || s.state}`)
+                        .filter(Boolean)
+                        .join('\n') ?? '';
                     const pack = compileSessionPackSync(cwd, {
                         prompt: session.prompt,
                         artifacts: JSON.stringify(session.artifacts, null, 2),
@@ -325,6 +350,8 @@ export class SessionManager {
                 clearInterval(t);
                 this.narrationTimers.delete(session.sessionId);
             }
+            // Watchdog: session settled on its own — stop watching it.
+            this.clearStallTimer(session.sessionId);
             this.evictOldCompleted();
             unsubscribe();
         });
@@ -335,6 +362,7 @@ export class SessionManager {
         // failures (no claude binary, timeout, malformed output) silently
         // skip — narration is enrichment, not the primary surface.
         this.startNarrationTimer(session);
+        this.startStallWatchdog(session);
         return session;
     }
     /** Tracks which agents have already been tried for a given prompt during
@@ -346,7 +374,6 @@ export class SessionManager {
      *  session if auto-spawn was triggered, undefined otherwise. */
     handleFailover(session, signal) {
         const config = loadFailoverConfig();
-        const chain = resolveChain(config?.chain);
         const tried = this.failoverTriedBySession.get(session.sessionId) ?? new Set();
         tried.add(signal.fromAgent);
         this.failoverTriedBySession.set(session.sessionId, tried);
@@ -399,11 +426,14 @@ export class SessionManager {
                 this.sessions.set(newSession.sessionId, newSession);
                 this.spawnOrder.push(newSession.sessionId);
                 this.cwdBySession.set(newSession.sessionId, cwd);
+                this.lastActivityBySession.set(newSession.sessionId, Date.now());
                 // Subscribe BEFORE persistence so exit events are never lost if the
                 // adapter exits synchronously (command not found, instant crash, etc).
                 const unsubscribe = newSession.subscribe((event) => {
+                    this.lastActivityBySession.set(newSession.sessionId, Date.now());
                     if (event.type !== 'exit')
                         return;
+                    this.clearStallTimer(newSession.sessionId);
                     const data = event.data;
                     const completedAt = Date.now();
                     this.completedAtBySession.set(newSession.sessionId, completedAt);
@@ -414,6 +444,7 @@ export class SessionManager {
                         completedAt,
                         steps: newSession.steps ? [...newSession.steps] : undefined,
                         artifacts: newSession.artifacts,
+                        stalledReason: this.stalledBySession.get(newSession.sessionId)?.reason,
                     });
                     mirrorCompletedToThread({
                         sessionId: newSession.sessionId,
@@ -446,14 +477,21 @@ export class SessionManager {
                             try {
                                 printFinalReportToTerminal(reportInput, report);
                             }
-                            catch { /* defensive */ }
+                            catch {
+                                /* defensive */
+                            }
                         }
                     })
-                        .catch(() => { });
+                        .catch(() => {
+                        /* defensive */
+                    });
                     // P1 — persist context pack at failover-replacement session exit.
                     void Promise.resolve().then(() => {
                         try {
-                            const stepsStr = newSession.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                            const stepsStr = newSession.steps
+                                ?.map((s) => `${s.label}: ${s.output || s.state}`)
+                                .filter(Boolean)
+                                .join('\n') ?? '';
                             const pack = compileSessionPackSync(cwd, {
                                 prompt: newSession.prompt,
                                 artifacts: JSON.stringify(newSession.artifacts, null, 2),
@@ -503,6 +541,7 @@ export class SessionManager {
                 this.continuedAsBySession.set(session.sessionId, newSession.sessionId);
                 this.continuedFromBySession.set(newSession.sessionId, session.sessionId);
                 this.startNarrationTimer(newSession);
+                this.startStallWatchdog(newSession);
                 return newSession;
             }
             catch {
@@ -523,7 +562,6 @@ export class SessionManager {
             this.failoverOffers = new Map();
         }
         const key = `${offer.session.sessionId}-${offer.target}`;
-        const expiresAt = Date.now() + 60_000;
         this.failoverOffers.set(key, { offer, createdAt: Date.now() });
         // Auto-expire offers after 60 seconds to keep the map bounded
         setTimeout(() => {
@@ -535,7 +573,7 @@ export class SessionManager {
         if (!this.failoverOffers)
             return [];
         const offers = [];
-        for (const [key, { offer, createdAt }] of this.failoverOffers) {
+        for (const [, { offer, createdAt }] of this.failoverOffers) {
             offers.push({
                 sessionId: offer.session.sessionId,
                 signal: offer.signal,
@@ -546,9 +584,9 @@ export class SessionManager {
         return offers;
     }
     /** v0.6.x P0 — user-initiated failover accept. Spawns a replacement
-       *  session on the target agent, preserving the original prompt + cwd.
-       *  P2 — injects handoff context for cross-agent continuity.
-       *  Returns the new session or undefined if the target is unavailable. */
+     *  session on the target agent, preserving the original prompt + cwd.
+     *  P2 — injects handoff context for cross-agent continuity.
+     *  Returns the new session or undefined if the target is unavailable. */
     acceptFailover(sessionId, targetAgent) {
         const session = this.sessions.get(sessionId);
         if (!session)
@@ -584,11 +622,14 @@ export class SessionManager {
         this.sessions.set(newSession.sessionId, newSession);
         this.spawnOrder.push(newSession.sessionId);
         this.cwdBySession.set(newSession.sessionId, cwd);
+        this.lastActivityBySession.set(newSession.sessionId, Date.now());
         // Subscribe BEFORE persistence so exit events are never lost if the
         // adapter exits synchronously.
         const unsubscribe = newSession.subscribe((event) => {
+            this.lastActivityBySession.set(newSession.sessionId, Date.now());
             if (event.type !== 'exit')
                 return;
+            this.clearStallTimer(newSession.sessionId);
             const data = event.data;
             const completedAt = Date.now();
             this.completedAtBySession.set(newSession.sessionId, completedAt);
@@ -599,6 +640,7 @@ export class SessionManager {
                 completedAt,
                 steps: newSession.steps ? [...newSession.steps] : undefined,
                 artifacts: newSession.artifacts,
+                stalledReason: this.stalledBySession.get(newSession.sessionId)?.reason,
             });
             mirrorCompletedToThread({
                 sessionId: newSession.sessionId,
@@ -631,14 +673,21 @@ export class SessionManager {
                     try {
                         printFinalReportToTerminal(reportInput, report);
                     }
-                    catch { /* defensive */ }
+                    catch {
+                        /* defensive */
+                    }
                 }
             })
-                .catch(() => { });
+                .catch(() => {
+                /* defensive */
+            });
             // P1 — persist context pack at accept-failover replacement session exit.
             void Promise.resolve().then(() => {
                 try {
-                    const stepsStr = newSession.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                    const stepsStr = newSession.steps
+                        ?.map((s) => `${s.label}: ${s.output || s.state}`)
+                        .filter(Boolean)
+                        .join('\n') ?? '';
                     const pack = compileSessionPackSync(cwd, {
                         prompt: newSession.prompt,
                         artifacts: JSON.stringify(newSession.artifacts, null, 2),
@@ -686,6 +735,7 @@ export class SessionManager {
             cwd,
         });
         this.startNarrationTimer(newSession);
+        this.startStallWatchdog(newSession);
         return newSession;
     }
     /** v0.6 M3 — periodic narration loop per session. */
@@ -718,10 +768,60 @@ export class SessionManager {
                 if (out)
                     this.narrationBySession.set(session.sessionId, out);
             })
-                .catch(() => { });
+                .catch(() => {
+                /* defensive — generateNarration never throws */
+            });
         }, intervalMs);
         this.narrationTimers.set(session.sessionId, timer);
     }
+    /** Stall watchdog (dogfood 2026-05-27 #1). Polls a running session; if no
+     *  event has arrived within the stall window, kills it and records an honest
+     *  reason. Cross-agent — opencode hung, but any adapter can. Timings are
+     *  env-overridable so the mock harness + tests can drive it fast. Disable
+     *  entirely with CODEHERE_DISABLE_WATCHDOG=1. */
+    startStallWatchdog(session) {
+        if (process.env.CODEHERE_DISABLE_WATCHDOG === '1')
+            return;
+        const stallMs = Number(process.env.CODEHERE_STALL_TIMEOUT_MS ?? 180_000);
+        const pollMs = Number(process.env.CODEHERE_STALL_POLL_MS ?? 15_000);
+        if (!(stallMs > 0) || !(pollMs > 0))
+            return;
+        const timer = setInterval(() => {
+            if (session.status !== 'running') {
+                this.clearStallTimer(session.sessionId);
+                return;
+            }
+            const last = this.lastActivityBySession.get(session.sessionId) ?? session.startedAt;
+            const silentMs = Date.now() - last;
+            if (silentMs < stallMs)
+                return;
+            const reason = `Stopped after no response for ${Math.round(silentMs / 1000)}s — the agent hung without finishing.`;
+            this.stalledBySession.set(session.sessionId, { reason, stalledAt: Date.now() });
+            this.clearStallTimer(session.sessionId);
+            try {
+                session.kill();
+            }
+            catch {
+                // kill is best-effort; the recorded stall reason + 'killed' status is
+                // what the UI reads, so a kill that throws still surfaces honestly.
+            }
+        }, pollMs);
+        this.stallTimers.set(session.sessionId, timer);
+    }
+    clearStallTimer(sessionId) {
+        const t = this.stallTimers.get(sessionId);
+        if (t) {
+            clearInterval(t);
+            this.stallTimers.delete(sessionId);
+        }
+    }
+    /** Watchdog verdict for a session — the honest "why it stopped" reason when
+     *  the stall watchdog killed it, or undefined if it settled on its own.
+     *  The API layer surfaces this so the dashboard never shows a hung task as a
+     *  normal row. */
+    getStallReason(sessionId) {
+        return this.stalledBySession.get(sessionId)?.reason;
+    }
     /** v0.6 M3 — latest narration for a session, or undefined. */
     getNarration(sessionId) {
         return this.narrationBySession.get(sessionId);
@@ -750,14 +850,14 @@ export class SessionManager {
         return this.continuedAsBySession.get(sessionId);
     }
     /** PM-UX Layer 3 · prose Final Report for an in-memory exited session.
-      *  Returns undefined while generation is in flight OR if the provider chain
-      *  failed (no claude-free, no claude, no credit, etc). The web UI reads this
-      *  through the /api/tasks serializer to render the prose summary inline. */
+     *  Returns undefined while generation is in flight OR if the provider chain
+     *  failed (no claude-free, no claude, no credit, etc). The web UI reads this
+     *  through the /api/tasks serializer to render the prose summary inline. */
     getFinalReport(sessionId) {
         return this.finalReportBySession.get(sessionId);
     }
     /** Returns true if Final Report generation explicitly failed for this session.
-      *  Lets the API distinguish "not yet" from "never coming". */
+     *  Lets the API distinguish "not yet" from "never coming". */
     hasFailedReport(sessionId) {
         return this.failedReportBySession.has(sessionId);
     }
@@ -784,6 +884,9 @@ export class SessionManager {
                 clearInterval(t);
                 this.narrationTimers.delete(id);
             }
+            this.clearStallTimer(id);
+            this.lastActivityBySession.delete(id);
+            this.stalledBySession.delete(id);
             this.sessions.delete(id);
             this.completedAtBySession.delete(id);
             this.cwdBySession.delete(id);
@@ -808,10 +911,14 @@ export class SessionManager {
     }
     /** Graceful shutdown: kill all running sessions and clear all timers. */
     shutdown() {
-        for (const [id, timer] of this.narrationTimers) {
+        for (const [, timer] of this.narrationTimers) {
             clearInterval(timer);
         }
         this.narrationTimers.clear();
+        for (const [, timer] of this.stallTimers) {
+            clearInterval(timer);
+        }
+        this.stallTimers.clear();
         for (const session of this.sessions.values()) {
             if (session.status === 'running')
                 session.kill();
@@ -957,4 +1064,10 @@ export class SessionManager {
 export function __testOnlyRegisterAdapter(adapter) {
     REGISTRY.push(adapter);
 }
+/** @internal Resets REGISTRY to BUILTIN_REGISTRY for test isolation.
+ *  Call before __testOnlyRegisterAdapter to avoid adapter accumulation. */
+export function __testOnlyResetRegistry() {
+    REGISTRY.length = 0;
+    REGISTRY.push(...BUILTIN_REGISTRY);
+}
 //# sourceMappingURL=session-manager.js.map