@shardworks/claude-code-apparatus 0.1.274 → 0.1.275

package/dist/babysitter.js

@@ -15,10 +15,10 @@
  *
  * The single-purpose primitives (stdin parsing, retrying HTTP, DLQ writes,
  * the SQLite trio, lifecycle reporters, stderr redirect) live in
- * `runtime.ts`. This file owns the orchestrator (`runBabysitter`), the
- * MCP/SSE proxy, and the script entry point. The previously-exported
- * primitives are re-exported below to preserve the package's public
- * surface.
+ * `runtime.ts`. The MCP/SSE proxy lives in `mcp-proxy.ts`. This file owns
+ * the orchestrator (`runBabysitter`) and the script entry point. The
+ * previously-exported primitives are re-exported below to preserve the
+ * package's public surface.
  *
  * See: docs/architecture/detached-sessions.md
  */
@@ -26,378 +26,266 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import http from 'node:http';
 import { fileURLToPath } from 'node:url';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { toolNameToRoute } from '@shardworks/tools-apparatus';
 import { processNdjsonBuffer, parseStreamJsonMessage, } from "./index.js";
-import { callGuildHttpApi, openTranscriptDb, readConfigFromStdin, redirectStderrToFile, reportRunning, reportResult, STDERR_DIAGNOSTIC_TAIL_LIMIT, writeToDlq, writeTranscript, } from "./runtime.js";
+import { isSourcePath, openTranscriptDb, readConfigFromStdin, redirectStderrToFile, reportRunning, reportResult, STDERR_DIAGNOSTIC_TAIL_LIMIT, writeTranscript, callGuildHttpApi, } from "./runtime.js";
+import { createProxyMcpHttpServer, } from "./mcp-proxy.js";
 // ── Re-exports (preserves the pre-extraction public surface) ────────────
 export { callGuildHttpApi, findRetryableCode, initTranscriptDb, openTranscriptDb, readConfigFromStdin, redirectStderrToFile, reportResult, reportRunning, resolveTerminalStatus, STDERR_DIAGNOSTIC_TAIL_LIMIT, writeToDlq, writeTranscript, } from "./runtime.js";
-// ── MCP proxy server ────────────────────────────────────────────────────
+export { createProxyMcpHttpServer } from "./mcp-proxy.js";
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
 /**
- * Create an MCP/SSE HTTP server that proxies tool calls to the guild.
- *
- * For each tool in the config, registers an MCP tool whose handler
- * forwards the call to the guild's Tool HTTP API via HTTP POST.
- *
- * Uses the low-level MCP Server class to register tools with raw
- * JSON Schema (the serialized params from the config).
+ * Init phase: open SQLite, start the MCP proxy, prepare session files,
+ * spawn the claude child, attach the stderr forwarder. Populates the
+ * resource handles on `ctx`. Throws if any step fails — the orchestrator's
+ * finally block cleans up whatever was allocated.
  */
-export async function createProxyMcpHttpServer(tools, guildToolUrl, sessionId) {
-    const server = new Server({ name: 'nexus-guild-proxy', version: '0.0.0' }, { capabilities: { tools: {} } });
-    // ── MCP proxy diagnostics ──────────────────────────────────────────
-    // Track connection state and tool call metrics for debugging SSE drops.
-    let sseConnectedAt = null;
-    let sseClosedAt = null;
-    let toolCallCount = 0;
-    // Register tools/list handler — advertises all tools with their JSON Schema.
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: tools.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: {
-                type: 'object',
-                ...t.params,
+async function runInitPhase(ctx) {
+    const { config } = ctx;
+    // 1. Open SQLite
+    ctx.db = ctx.injectedDb ?? await openTranscriptDb(config.dbPath);
+    // 2. Start MCP proxy server
+    ctx.mcpHandle = await createProxyMcpHttpServer(config.tools, config.guildToolUrl, config.sessionId);
+    // 3. Prepare session files
+    ctx.tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-babysitter-'));
+    const args = [...config.claudeArgs];
+    // Write mcp-config pointing to the babysitter's MCP proxy server
+    const mcpConfig = {
+        mcpServers: {
+            'nexus-guild': {
+                type: 'sse',
+                url: ctx.mcpHandle.url,
             },
-        })),
-    }));
-    // Build a name → HTTP method lookup so the proxy can route each call to
-    // the correct verb (read tools are GET-only on the tool server; POSTing
-    // to them 404s).
-    const toolMethods = new Map();
-    for (const t of tools) {
-        toolMethods.set(t.name, t.method);
+        },
+    };
+    const mcpConfigPath = path.join(ctx.tmpDir, 'mcp-config.json');
+    fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig));
+    args.push('--mcp-config', mcpConfigPath, '--strict-mcp-config');
+    // Add autonomous mode flags
+    args.push('--print', '-', '--output-format', 'stream-json', '--verbose');
+    // 4. Spawn claude
+    const claudeProc = ctx.spawnFn('claude', args, {
+        cwd: config.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...config.env },
+    });
+    ctx.claudeProc = claudeProc;
+    // Pipe prompt to claude's stdin, then close
+    if (config.prompt) {
+        claudeProc.stdin.write(config.prompt);
     }
-    // Register tools/call handler — proxies each call to the guild HTTP API.
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const toolName = request.params.name;
-        const params = request.params.arguments ?? {};
-        const route = toolNameToRoute(toolName);
-        const url = `${guildToolUrl}${route}`;
-        const method = toolMethods.get(toolName) ?? 'POST';
-        toolCallCount++;
-        const callNum = toolCallCount;
-        const callStart = Date.now();
-        try {
-            const result = await callGuildHttpApi(url, sessionId, params, undefined, method);
-            const elapsed = Date.now() - callStart;
-            process.stderr.write(`[babysitter] mcp-proxy: ${toolName} → ${method} ${route} (${elapsed}ms, call #${callNum})\n`);
-            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
-            return {
-                content: [{ type: 'text', text }],
-            };
-        }
-        catch (err) {
-            const elapsed = Date.now() - callStart;
-            const message = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[babysitter] mcp-proxy: ${toolName} FAILED (${elapsed}ms, call #${callNum}): ${message}\n`);
-            return {
-                content: [{ type: 'text', text: `Error: ${message}` }],
-                isError: true,
-            };
-        }
+    claudeProc.stdin.end();
+    // Forward claude's stderr bytes to the babysitter's redirected
+    // stderr log. No detection happens here — rate-limit signals are
+    // detected only on structured NDJSON messages inside
+    // parseStreamJsonMessage.
+    //
+    // Also maintain a rolling tail buffer (last
+    // STDERR_DIAGNOSTIC_TAIL_LIMIT chars) — used as the `stderrExcerpt`
+    // of the passive `terminationDiagnostic` attached when the session
+    // ends with `'failed'`. O(1) per chunk: append then slice the tail.
+    claudeProc.stderr?.on('data', (chunk) => {
+        process.stderr.write(chunk);
+        const text = chunk.toString('utf8');
+        ctx.stderrTail = (ctx.stderrTail + text).slice(-STDERR_DIAGNOSTIC_TAIL_LIMIT);
     });
-    // Wrap in HTTP server with SSE transport (same pattern as mcp-server.ts).
-    // Promise-gate: POST /message waits for the SSE transport to be fully connected,
-    // eliminating the race where a POST arrives before GET /sse completes.
-    let resolveTransport;
-    let rejectTransport;
-    const transportReady = new Promise((resolve, reject) => {
-        resolveTransport = resolve;
-        rejectTransport = reject;
+}
+/**
+ * Steady-state phase: fire the running report, install the SIGTERM
+ * handler, start the heartbeat schedule, consume stdout into the
+ * accumulator (with first-wins terminationTag), and await claude's
+ * exit. Returns the exit code and signal the terminal phase will report.
+ */
+async function runSteadyStatePhase(ctx) {
+    const { config, claudeProc, db } = ctx;
+    if (!claudeProc) {
+        throw new Error('runSteadyStatePhase: claudeProc not initialized');
+    }
+    // 5. Report "running" status (don't await — fire and forget with retry)
+    const cancelHandle = { kind: 'local-pgid', pgid: process.pid };
+    const runningPromise = reportRunning(config, cancelHandle, ctx.retryTimeoutMs).catch((err) => {
+        process.stderr.write(`[babysitter] Failed to report running: ${err}\n`);
     });
-    // Direct reference for close() — null until connected.
-    let transport = null;
-    // SSE keepalive timer — sends periodic comments to prevent idle timeouts.
-    // SSE spec says lines starting with ':' are comments, ignored by clients.
-    const SSE_KEEPALIVE_INTERVAL_MS = 30_000;
-    let keepaliveTimer = null;
-    const httpServer = http.createServer(async (req, res) => {
-        try {
-            if (req.method === 'GET' && req.url === '/sse') {
-                const t = new SSEServerTransport('/message', res);
-                try {
-                    await server.connect(t);
-                    transport = t;
-                    sseConnectedAt = Date.now();
-                    process.stderr.write(`[babysitter] mcp-proxy: SSE connection established\n`);
-                    // Start keepalive pings on the SSE response stream
-                    keepaliveTimer = setInterval(() => {
-                        try {
-                            res.write(':keepalive\n\n');
-                        }
-                        catch {
-                            // Stream already closed — timer will be cleared by close handler
-                        }
-                    }, SSE_KEEPALIVE_INTERVAL_MS);
-                    // Log when SSE connection closes (the key diagnostic for the drop)
-                    res.on('close', () => {
-                        const duration = sseConnectedAt ? Date.now() - sseConnectedAt : 0;
-                        sseClosedAt = Date.now();
-                        process.stderr.write(`[babysitter] mcp-proxy: SSE connection closed after ${duration}ms ` +
-                            `(${toolCallCount} tool calls proxied)\n`);
-                        if (keepaliveTimer) {
-                            clearInterval(keepaliveTimer);
-                            keepaliveTimer = null;
-                        }
-                    });
-                    resolveTransport(t);
-                }
-                catch (err) {
-                    rejectTransport(err instanceof Error ? err : new Error(String(err)));
-                    throw err;
-                }
-            }
-            else if (req.method === 'POST' && req.url?.startsWith('/message')) {
-                if (!transport) {
-                    process.stderr.write(`[babysitter] mcp-proxy: POST /message arrived before SSE transport ready — waiting\n`);
-                }
-                let t;
-                try {
-                    t = await transportReady;
-                }
-                catch {
-                    res.writeHead(503).end('SSE transport failed to initialize');
-                    return;
-                }
-                // Detect and log the "SSE already dead" case before it hits the SDK
-                if (sseClosedAt) {
-                    const ago = Date.now() - sseClosedAt;
-                    process.stderr.write(`[babysitter] mcp-proxy: POST /message on dead SSE connection ` +
-                        `(closed ${ago}ms ago, after ${toolCallCount} calls)\n`);
-                }
-                await t.handlePostMessage(req, res);
+    ctx.runningPromise = runningPromise;
+    // 5b. Heartbeat timer — sends liveness signal every 30s after ready report.
+    function scheduleHeartbeat() {
+        ctx.heartbeatTimer = setTimeout(async () => {
+            const route = toolNameToRoute('session-heartbeat');
+            const hbUrl = `${config.guildToolUrl}${route}`;
+            try {
+                await callGuildHttpApi(hbUrl, config.sessionId, { sessionId: config.sessionId }, HEARTBEAT_TIMEOUT_MS);
             }
-            else {
-                res.writeHead(404).end('Not found');
+            catch {
+                // Dropped — next heartbeat in 30s. Staleness threshold (90s) tolerates this.
             }
+            scheduleHeartbeat();
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    // Start heartbeat after running report completes
+    runningPromise.then(() => scheduleHeartbeat());
+    // 5c. SIGTERM handler — sets cancelled flag and propagates to claude.
+    const onSigterm = () => {
+        ctx.cancelledBySignal = true;
+        // Stop heartbeat timer
+        if (ctx.heartbeatTimer) {
+            clearTimeout(ctx.heartbeatTimer);
+            ctx.heartbeatTimer = null;
         }
-        catch {
-            if (!res.headersSent) {
-                res.writeHead(500).end('Internal Server Error');
+        // Propagate SIGTERM to the claude process
+        if (ctx.claudeProc && ctx.claudeProc.pid && !ctx.claudeProc.killed) {
+            try {
+                ctx.claudeProc.kill('SIGTERM');
             }
+            catch { /* already dead */ }
+        }
+        // The normal claude exit path will run, check cancelledBySignal,
+        // and report status 'cancelled' instead of computing from exit code.
+    };
+    ctx.onSigterm = onSigterm;
+    process.on('SIGTERM', onSigterm);
+    // 6. Consume stdout, stream transcript. The accumulator is mutated in
+    // place by parseStreamJsonMessage; the first-wins terminationTag
+    // invariant relies on a single accumulator identity for the whole
+    // stream.
+    let buffer = '';
+    claudeProc.stdout.on('data', (chunk) => {
+        buffer += chunk.toString();
+        const prevLength = ctx.acc.transcript.length;
+        buffer = processNdjsonBuffer(buffer, (msg) => {
+            parseStreamJsonMessage(msg, ctx.acc);
+        });
+        // Write transcript to SQLite if new messages were added
+        if (ctx.acc.transcript.length > prevLength && db) {
+            writeTranscript(db, config.sessionId, ctx.acc.transcript);
         }
     });
-    await new Promise((resolve) => {
-        httpServer.listen(0, '127.0.0.1', resolve);
+    // 7. Wait for claude to exit
+    return await new Promise((resolve, reject) => {
+        claudeProc.on('error', (err) => {
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        claudeProc.on('close', (code, signal) => {
+            resolve({ exitCode: code ?? 1, exitSignal: signal ?? undefined });
+        });
     });
-    const addr = httpServer.address();
-    if (!addr || typeof addr === 'string') {
-        throw new Error('Failed to get MCP proxy server address');
+}
+/**
+ * Terminal phase: stop the heartbeat, remove the SIGTERM handler, await
+ * the running report, build the final StreamJsonResult, and submit it
+ * via `reportResult` (which handles both the normal and cancelled-by-
+ * signal paths via the StatusOverride contract).
+ */
+async function runTerminalPhase(ctx, exit) {
+    // Stop heartbeat before terminal report
+    if (ctx.heartbeatTimer) {
+        clearTimeout(ctx.heartbeatTimer);
+        ctx.heartbeatTimer = null;
     }
-    const url = `http://127.0.0.1:${addr.port}/sse`;
-    process.stderr.write(`[babysitter] MCP proxy server listening on port ${addr.port}\n`);
-    return {
-        url,
-        async close() {
-            if (keepaliveTimer) {
-                clearInterval(keepaliveTimer);
-                keepaliveTimer = null;
-            }
-            if (transport) {
-                await transport.close();
-            }
-            await new Promise((resolve, reject) => {
-                httpServer.close((err) => (err ? reject(err) : resolve()));
-            });
-        },
+    // Clean up SIGTERM handler (happy path; the finally block in
+    // runBabysitter is a defensive no-op when the handler was already
+    // removed here).
+    if (ctx.onSigterm) {
+        process.removeListener('SIGTERM', ctx.onSigterm);
+        ctx.onSigterm = null;
+    }
+    // Ensure running report completed before recording result
+    if (ctx.runningPromise) {
+        await ctx.runningPromise;
+    }
+    // Build result
+    const result = {
+        exitCode: exit.exitCode,
+        transcript: ctx.acc.transcript,
+        costUsd: ctx.acc.costUsd,
+        tokenUsage: ctx.acc.tokenUsage,
+        providerSessionId: ctx.acc.providerSessionId,
+        signal: exit.exitSignal,
+        ...(ctx.acc.terminationTag ? { terminationTag: ctx.acc.terminationTag } : {}),
     };
+    // 8. Report result
+    await reportResult(ctx.config, result, ctx.acc.transcript, ctx.retryTimeoutMs, ctx.cancelledBySignal ? 'cancelled' : undefined, ctx.stderrTail);
 }
-// ── Main babysitter function ────────────────────────────────────────────
 /**
  * Run the session babysitter.
  *
- * This is the main orchestration function. It:
- * 1. Opens SQLite for transcript streaming
- * 2. Starts the MCP proxy server
- * 3. Prepares session files (tmpDir, system prompt, mcp-config)
- * 4. Spawns claude
- * 5. Reports "running" status
- * 6. Streams transcript to SQLite
- * 7. Reports result on exit
- * 8. Cleans up
+ * Three-phase orchestrator threading a {@link BabysitterRuntimeContext}:
+ * `runInitPhase` allocates resources, `runSteadyStatePhase` reports
+ * lifecycle events and consumes claude's NDJSON stream, `runTerminalPhase`
+ * builds and submits the final result. The shared try/catch/finally
+ * funnels all error and cleanup handling.
+ *
+ * The orchestrator-error path goes through `reportResult` via the
+ * `StatusOverride` contract (no hand-rolled session-record + DLQ
+ * cascade) — `reportResult` is the single sink for both the normal
+ * `'failed'` path and the orchestrator-caught error path.
  */
 export async function runBabysitter(config, deps) {
-    const spawnFn = deps?.spawnFn ?? spawn;
-    const retryTimeoutMs = deps?.retryTimeoutMs;
-    let db = null;
-    let mcpHandle = null;
-    let tmpDir = null;
-    let claudeProc = null;
+    const ctx = {
+        config,
+        spawnFn: deps?.spawnFn ?? spawn,
+        retryTimeoutMs: deps?.retryTimeoutMs,
+        injectedDb: deps?.db,
+        db: null,
+        mcpHandle: null,
+        tmpDir: null,
+        claudeProc: null,
+        heartbeatTimer: null,
+        onSigterm: null,
+        cancelledBySignal: false,
+        runningPromise: null,
+        acc: { transcript: [] },
+        stderrTail: '',
+    };
     try {
-        // 1. Open SQLite
-        db = deps?.db ?? await openTranscriptDb(config.dbPath);
-        // 2. Start MCP proxy server
-        mcpHandle = await createProxyMcpHttpServer(config.tools, config.guildToolUrl, config.sessionId);
-        // 3. Prepare session files
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-babysitter-'));
-        const args = [...config.claudeArgs];
-        // Write system prompt if present in args (already handled by claudeArgs)
-        // Write mcp-config pointing to the babysitter's MCP proxy server
-        const mcpConfig = {
-            mcpServers: {
-                'nexus-guild': {
-                    type: 'sse',
-                    url: mcpHandle.url,
-                },
-            },
-        };
-        const mcpConfigPath = path.join(tmpDir, 'mcp-config.json');
-        fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig));
-        args.push('--mcp-config', mcpConfigPath, '--strict-mcp-config');
-        // Add autonomous mode flags
-        args.push('--print', '-', '--output-format', 'stream-json', '--verbose');
-        // 4. Spawn claude
-        claudeProc = spawnFn('claude', args, {
-            cwd: config.cwd,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, ...config.env },
-        });
-        // Pipe prompt to claude's stdin, then close
-        if (config.prompt) {
-            claudeProc.stdin.write(config.prompt);
-        }
-        claudeProc.stdin.end();
-        // Forward claude's stderr bytes to the babysitter's redirected
-        // stderr log. No detection happens here — rate-limit signals are
-        // detected only on structured NDJSON messages inside
-        // parseStreamJsonMessage.
-        //
-        // Also maintain a rolling tail buffer (last
-        // STDERR_DIAGNOSTIC_TAIL_LIMIT chars) — used as the `stderrExcerpt`
-        // of the passive `terminationDiagnostic` attached when the session
-        // ends with `'failed'`. O(1) per chunk: append then slice the tail.
-        let stderrTail = '';
-        claudeProc.stderr?.on('data', (chunk) => {
-            process.stderr.write(chunk);
-            const text = chunk.toString('utf8');
-            stderrTail = (stderrTail + text).slice(-STDERR_DIAGNOSTIC_TAIL_LIMIT);
-        });
-        // 5. Report "running" status (don't await — fire and forget with retry)
-        const cancelHandle = { kind: 'local-pgid', pgid: process.pid };
-        const runningPromise = reportRunning(config, cancelHandle, retryTimeoutMs).catch((err) => {
-            process.stderr.write(`[babysitter] Failed to report running: ${err}\n`);
-        });
-        // 5b. Heartbeat timer — sends liveness signal every 30s after ready report.
-        const HEARTBEAT_INTERVAL_MS = 30_000;
-        const HEARTBEAT_TIMEOUT_MS = 10_000;
-        let heartbeatTimer = null;
-        function scheduleHeartbeat() {
-            heartbeatTimer = setTimeout(async () => {
-                const route = toolNameToRoute('session-heartbeat');
-                const hbUrl = `${config.guildToolUrl}${route}`;
-                try {
-                    await callGuildHttpApi(hbUrl, config.sessionId, { sessionId: config.sessionId }, HEARTBEAT_TIMEOUT_MS);
-                }
-                catch {
-                    // Dropped — next heartbeat in 30s. Staleness threshold (90s) tolerates this.
-                }
-                scheduleHeartbeat();
-            }, HEARTBEAT_INTERVAL_MS);
-        }
-        // Start heartbeat after running report completes
-        runningPromise.then(() => scheduleHeartbeat());
-        // 5c. SIGTERM handler — sets cancelled flag and propagates to claude.
-        let cancelledBySignal = false;
-        const onSigterm = () => {
-            cancelledBySignal = true;
-            // Stop heartbeat timer
-            if (heartbeatTimer) {
-                clearTimeout(heartbeatTimer);
-                heartbeatTimer = null;
-            }
-            // Propagate SIGTERM to the claude process
-            if (claudeProc && claudeProc.pid && !claudeProc.killed) {
-                try {
-                    claudeProc.kill('SIGTERM');
-                }
-                catch { /* already dead */ }
-            }
-            // The normal claude exit path will run, check cancelledBySignal,
-            // and report status 'cancelled' instead of computing from exit code.
-        };
-        process.on('SIGTERM', onSigterm);
-        // 6. Consume stdout, stream transcript
-        const acc = { transcript: [] };
-        let buffer = '';
-        claudeProc.stdout.on('data', (chunk) => {
-            buffer += chunk.toString();
-            const prevLength = acc.transcript.length;
-            buffer = processNdjsonBuffer(buffer, (msg) => {
-                parseStreamJsonMessage(msg, acc);
-            });
-            // Write transcript to SQLite if new messages were added
-            if (acc.transcript.length > prevLength && db) {
-                writeTranscript(db, config.sessionId, acc.transcript);
-            }
-        });
-        // 7. Wait for claude to exit
-        const { code: exitCode, signal: exitSignal } = await new Promise((resolve, reject) => {
-            claudeProc.on('error', (err) => {
-                reject(new Error(`Failed to spawn claude: ${err.message}`));
-            });
-            claudeProc.on('close', (code, signal) => {
-                resolve({ code: code ?? 1, signal: signal ?? undefined });
-            });
-        });
-        // Stop heartbeat before terminal report
-        if (heartbeatTimer) {
-            clearTimeout(heartbeatTimer);
-            heartbeatTimer = null;
-        }
-        // Clean up SIGTERM handler
-        process.removeListener('SIGTERM', onSigterm);
-        // Ensure running report completed before recording result
-        await runningPromise;
-        // Build result
-        const result = {
-            exitCode,
-            transcript: acc.transcript,
-            costUsd: acc.costUsd,
-            tokenUsage: acc.tokenUsage,
-            providerSessionId: acc.providerSessionId,
-            signal: exitSignal,
-            ...(acc.terminationTag ? { terminationTag: acc.terminationTag } : {}),
-        };
-        // 8. Report result
-        await reportResult(config, result, acc.transcript, retryTimeoutMs, cancelledBySignal ? 'cancelled' : undefined, stderrTail);
+        await runInitPhase(ctx);
+        const exit = await runSteadyStatePhase(ctx);
+        await runTerminalPhase(ctx, exit);
     }
     catch (err) {
-        // Top-level error: attempt to report failure
+        // Funnel the orchestrator-caught error through reportResult via the
+        // StatusOverride contract. reportResult writes to the DLQ when the
+        // guild HTTP API is unreachable, so this single call covers both
+        // the happy and degraded paths the legacy hand-rolled cascade
+        // covered.
         const message = err instanceof Error ? err.message : String(err);
+        const partial = {
+            exitCode: 1,
+            transcript: ctx.acc.transcript,
+            costUsd: ctx.acc.costUsd,
+            tokenUsage: ctx.acc.tokenUsage,
+            providerSessionId: ctx.acc.providerSessionId,
+        };
         try {
-            const route = toolNameToRoute('session-record');
-            const url = `${config.guildToolUrl}${route}`;
-            await callGuildHttpApi(url, config.sessionId, {
-                sessionId: config.sessionId,
-                status: 'failed',
-                exitCode: 1,
-                error: message,
-            }, retryTimeoutMs);
+            await reportResult(ctx.config, partial, ctx.acc.transcript, ctx.retryTimeoutMs, { kind: 'orchestrator-error', error: message }, ctx.stderrTail);
         }
         catch {
-            writeToDlq(config.cwd, `${config.sessionId}.json`, {
-                sessionId: config.sessionId,
-                status: 'failed',
-                exitCode: 1,
-                error: message,
-            });
+            // reportResult itself failed catastrophically — already DLQ'd
+            // internally on HTTP failure; swallow so we still rethrow the
+            // original error.
         }
         throw err;
     }
     finally {
         // 9. Cleanup
-        process.removeAllListeners('SIGTERM');
-        await mcpHandle?.close().catch(() => { });
-        db?.close();
-        if (tmpDir) {
-            fs.rmSync(tmpDir, { recursive: true, force: true });
+        // Targeted SIGTERM-listener removal: the happy path already removes
+        // ctx.onSigterm in runTerminalPhase, so this is a defensive no-op
+        // when steady-state completed; on a partial-init path where steady-
+        // state never installed the listener, ctx.onSigterm is null and the
+        // call is skipped. Avoids removeAllListeners which would sweep
+        // unrelated listeners installed by hosts of this module.
+        if (ctx.onSigterm) {
+            process.removeListener('SIGTERM', ctx.onSigterm);
+            ctx.onSigterm = null;
+        }
+        await ctx.mcpHandle?.close().catch(() => { });
+        ctx.db?.close();
+        if (ctx.tmpDir) {
+            fs.rmSync(ctx.tmpDir, { recursive: true, force: true });
         }
-        if (config.systemPromptTmpDir) {
-            fs.rmSync(config.systemPromptTmpDir, { recursive: true, force: true });
+        if (ctx.config.systemPromptTmpDir) {
+            fs.rmSync(ctx.config.systemPromptTmpDir, { recursive: true, force: true });
         }
     }
 }
@@ -428,11 +316,17 @@ async function main() {
         }
     }
 }
-// Check if this module is the entry point
-const isEntryPoint = process.argv[1] &&
-    (process.argv[1] === fileURLToPath(import.meta.url) ||
-        path.basename(process.argv[1]) === 'babysitter.js' ||
-        path.basename(process.argv[1]) === 'babysitter.ts');
+// Check if this module is the entry point. The argv-vs-import.meta.url
+// equality is the primary check; the basename comparison is a fallback for
+// path-resolution differences (symlinks, realpath). The `isSourcePath`
+// predicate selects the basename to expect — `babysitter.ts` in source
+// mode, `babysitter.js` in compiled output — keeping the extension test in
+// step with the other two source-mode branches in this package.
+const argv1 = process.argv[1];
+const expectedBasename = isSourcePath(import.meta.url) ? 'babysitter.ts' : 'babysitter.js';
+const isEntryPoint = argv1 !== undefined &&
+    (argv1 === fileURLToPath(import.meta.url) ||
+        path.basename(argv1) === expectedBasename);
 if (isEntryPoint) {
     main();
 }