amicus 1.9.1 → 2.0.0

package/src/mcp-server.js

@@ -1,13 +1,14 @@
 /** @module mcp-server — Amicus MCP Server (stdio transport) */
 const fs = require('fs');
 const path = require('path');
+const { writeFileAtomic } = require('./utils/atomic-write');
 const { spawn } = require('child_process');
 const { getTools, getGuideText } = require('./mcp-tools');
 const { tryResolveModel } = require('./utils/config');
 const os = require('os');
 const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
-const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
+const { getSessionDir, SESSIONS_DIR } = require('./session-manager');
 const { readProgress, isStalled } = require('./sidecar/progress');
 const { deriveStage, sanitizePreview } = require('./sidecar/progress-fields');
 const { SharedServerManager } = require('./utils/shared-server');
@@ -20,6 +21,7 @@ const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
 const { runWait, registerInProcessRun, settleInProcessRun } = require('./mcp-wait');
 const { detectClient } = require('./utils/client-detect');
 const { fenceSidecarOutput } = require('./utils/untrusted-fence');
+const { sliceForRead } = require('./utils/read-slice');
 
 /**
  * Elapsed run duration: time between createdAt and the run's end, bounding the
@@ -42,6 +44,14 @@ function elapsedMs(metadata) {
 // coverage); 'idle-timeout' is the shared-server idle-eviction value.
 const FAILED_TERMINAL_STATUSES = ['error', 'crashed', 'timeout', 'timed-out', 'idle-timeout', 'aborted'];
 
+// 15a.1: the statuses finalizeHeadlessResult's SUCCESS path can commit
+// (resolveTerminalState's complete/aborted/timed-out outcomes — never 'error',
+// which is finalizeHeadlessResult's OWN failure branch and must remain
+// overwritable by a later genuine failure). Once one of these lands, a later
+// throw in the same .then/.catch chain (e.g. removeSession) must not
+// overwrite it with a fresh 'error' — see the shared-server .catch below.
+const TERMINAL_STATUS_SET = new Set(['complete', 'aborted', 'timed-out']);
+
 const sharedServer = new SharedServerManager({ logger });
 
 /**
@@ -284,6 +294,7 @@ const handlers = {
         const { buildContext } = require('./sidecar/context-builder');
         const { buildPrompts } = require('./prompt-builder');
         const { runHeadless } = require('./headless');
+        const { generateFoldNonce } = require('./utils/fold-marker');
         const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
         // resolvedModel is already available from validateStartInputs() above
 
@@ -299,7 +310,7 @@ const handlers = {
         recordSession(taskId, cwd); // #40: global index for cross-project lookup
         const metaPath = path.join(sessionDir, 'metadata.json');
         const serverPort = server.url ? new URL(server.url).port : null;
-        fs.writeFileSync(metaPath, JSON.stringify({
+        writeFileAtomic(metaPath, JSON.stringify({
           taskId, status: 'running',
           pid: null, // Shared server path: don't store MCP server PID (abort would kill all sessions)
           opencodeSessionId: sessionId,
@@ -331,9 +342,12 @@ const handlers = {
           }
         }
 
+        // 15b.3: one nonce per run, generated before prompt construction.
+        const foldNonce = generateFoldNonce();
+
         // Build prompts (same as CLI path in start.js)
         const { system: systemPrompt, userMessage } = buildPrompts(
-          input.prompt, context, cwd, true, agent, input.summaryLength
+          input.prompt, context, cwd, true, agent, input.summaryLength, undefined, foldNonce
         );
 
         // Register session with idle eviction
@@ -342,7 +356,7 @@ const handlers = {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
             meta.status = 'idle-timeout';
             meta.completedAt = new Date().toISOString();
-            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+            writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
           } catch (err) {
             logger.warn('Failed to update evicted session metadata', { error: err.message });
           }
@@ -366,6 +380,7 @@ const handlers = {
             // Not yet consumed downstream; threaded here so it's available the
             // moment a consumer (e.g. metadata/fold-output) needs it (12a.1/B02).
             amicusClient: detectedClient,
+            nonce: foldNonce,
           }
         ).then((result) => {
           // Session done — route through resolveTerminalState (same single source
@@ -377,16 +392,38 @@ const handlers = {
           } catch (finErr) {
             logger.warn('Failed to finalize session', { error: finErr.message });
           }
-          sharedServer.removeSession(sessionId);
+          // Guarded: a throw here (e.g. a stale/evicted sessionId) must not
+          // escape into an unhandled rejection, and must not fall into .catch
+          // below and have its error-overwrite clobber the terminal status
+          // finalizeHeadlessResult just committed above.
+          try {
+            sharedServer.removeSession(sessionId);
+          } catch (removeErr) {
+            logger.warn('Failed to remove session from shared server', { taskId, error: removeErr.message });
+          }
         }).catch((err) => {
           logger.error('Shared server session failed', { taskId, error: err.message });
-          sharedServer.removeSession(sessionId);
+          try {
+            sharedServer.removeSession(sessionId);
+          } catch (removeErr) {
+            logger.warn('Failed to remove session from shared server', { taskId, error: removeErr.message });
+          }
           try {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+            // A run that already committed a terminal status (complete/aborted/
+            // timed-out) must never be clobbered by a LATER in-chain throw (e.g.
+            // a bug after finalizeHeadlessResult) — only a genuine pre-terminal
+            // failure (runHeadless itself rejecting) should land here as 'error'.
+            if (TERMINAL_STATUS_SET.has(meta.status)) {
+              logger.warn('Shared server chain error after terminal status already committed — not overwriting', {
+                taskId, existingStatus: meta.status, error: err.message,
+              });
+              return;
+            }
             meta.status = 'error';
             meta.reason = err.message;
             meta.completedAt = new Date().toISOString();
-            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+            writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
           } catch (writeErr) {
             logger.warn('Failed to write error metadata', { error: writeErr.message });
           }
@@ -433,7 +470,7 @@ const handlers = {
       recordSession(taskId, cwd); // #40: global index for cross-project lookup
       const metaPath = path.join(sessionDir, 'metadata.json');
       if (!fs.existsSync(metaPath)) {
-        fs.writeFileSync(metaPath, JSON.stringify({
+        writeFileAtomic(metaPath, JSON.stringify({
           taskId, status: 'running', pid: child.pid, createdAt: new Date().toISOString(),
           headless: !!input.noUi,
           // Seed briefing/mode so list/status are informative even before the
@@ -490,27 +527,31 @@ const handlers = {
       // Crash-detection for hard-killed fanout processes: the wave branch
       // returns early, so the single-session pid probe below never runs here.
       if (metadata.status === 'running' && metadata.pid) {
-        try { process.kill(metadata.pid, 0); } catch {
-          const crashedAt = new Date().toISOString();
-          Object.assign(metadata, {
-            status: 'crashed', crashedAt,
-            reason: 'Fan-out process exited unexpectedly',
-          });
-          fs.writeFileSync(path.join(sessionDir, 'metadata.json'),
-            JSON.stringify(metadata, null, 2), { mode: 0o600 });
-          // Cascade to legs whose pollers died with the parent
-          for (const leg of legs) {
-            if (leg.status === 'running') {
-              const legMeta = readMetadata(leg.taskId, cwd);
-              if (legMeta) {
-                Object.assign(legMeta, {
-                  status: 'crashed', crashedAt,
-                  reason: 'Parent fan-out process killed',
-                });
-                fs.writeFileSync(
-                  path.join(getSessionDir(cwd, leg.taskId), 'metadata.json'),
-                  JSON.stringify(legMeta, null, 2), { mode: 0o600 });
-                leg.status = 'crashed';
+        try { process.kill(metadata.pid, 0); } catch (err) {
+          // EPERM means the pid exists but we lack permission to signal it —
+          // that's ALIVE, not dead (mirrors utils/abort-coordinator.js isAlive).
+          if (err.code !== 'EPERM') {
+            const crashedAt = new Date().toISOString();
+            Object.assign(metadata, {
+              status: 'crashed', crashedAt,
+              reason: 'Fan-out process exited unexpectedly',
+            });
+            writeFileAtomic(path.join(sessionDir, 'metadata.json'),
+              JSON.stringify(metadata, null, 2), { mode: 0o600 });
+            // Cascade to legs whose pollers died with the parent
+            for (const leg of legs) {
+              if (leg.status === 'running') {
+                const legMeta = readMetadata(leg.taskId, cwd);
+                if (legMeta) {
+                  Object.assign(legMeta, {
+                    status: 'crashed', crashedAt,
+                    reason: 'Parent fan-out process killed',
+                  });
+                  writeFileAtomic(
+                    path.join(getSessionDir(cwd, leg.taskId), 'metadata.json'),
+                    JSON.stringify(legMeta, null, 2), { mode: 0o600 });
+                  leg.status = 'crashed';
+                }
               }
             }
           }
@@ -536,13 +577,17 @@ const handlers = {
     }
 
     if (metadata.status === 'running' && metadata.pid) {
-      try { process.kill(metadata.pid, 0); } catch {
-        Object.assign(metadata, {
-          status: 'crashed', crashedAt: new Date().toISOString(),
-          reason: 'Process exited unexpectedly',
-        });
-        fs.writeFileSync(path.join(sessionDir, 'metadata.json'),
-          JSON.stringify(metadata, null, 2));
+      try { process.kill(metadata.pid, 0); } catch (err) {
+        // EPERM means the pid exists but we lack permission to signal it —
+        // that's ALIVE, not dead (mirrors utils/abort-coordinator.js isAlive).
+        if (err.code !== 'EPERM') {
+          Object.assign(metadata, {
+            status: 'crashed', crashedAt: new Date().toISOString(),
+            reason: 'Process exited unexpectedly',
+          });
+          writeFileAtomic(path.join(sessionDir, 'metadata.json'),
+            JSON.stringify(metadata, null, 2), { mode: 0o600 });
+        }
       }
     }
 
@@ -619,7 +664,10 @@ const handlers = {
         // Fence the whole wave.json text: it embeds each leg's folded-back
         // summary/error, which is untrusted model prose entering the parent
         // context (same blunt whole-text treatment as the single-session fence).
-        return textResult(fenceSidecarOutput(fs.readFileSync(wavePath, 'utf-8')));
+        // Sliced BEFORE fencing (15a.3/B17) so the fence markup itself is
+        // never truncated.
+        const { body } = sliceForRead(fs.readFileSync(wavePath, 'utf-8'), input);
+        return textResult(fenceSidecarOutput(body));
       }
       const legsTotal = (readMeta.legs || []).length;
       const stillRunning = !readMeta.status || readMeta.status === 'running';
@@ -632,14 +680,22 @@ const handlers = {
 
     const mode = input.mode || 'summary';
     if (mode === 'metadata') {
-      return textResult(fs.readFileSync(path.join(sessionDir, 'metadata.json'), 'utf-8'));
+      // metadata is small structured JSON: exempt from offset/limit/tail (a
+      // caller slicing JSON would just break parsing), but still cap-defended
+      // defensively — apply the SAME notice convention, left unfenced to
+      // match its unfenced (structured-data) status.
+      const metaText = fs.readFileSync(path.join(sessionDir, 'metadata.json'), 'utf-8');
+      const { body } = sliceForRead(metaText, {});
+      return textResult(body);
     }
     if (mode === 'conversation') {
       const convPath = path.join(sessionDir, 'conversation.jsonl');
       if (!fs.existsSync(convPath)) { return textResult('No conversation recorded.'); }
       // Fence the whole conversation dump in ONE fence (not per-line): it is
-      // untrusted model prose entering the parent context.
-      return textResult(fenceSidecarOutput(fs.readFileSync(convPath, 'utf-8')));
+      // untrusted model prose entering the parent context. Sliced BEFORE
+      // fencing (15a.3/B17) so the fence markup itself is never truncated.
+      const { body } = sliceForRead(fs.readFileSync(convPath, 'utf-8'), input);
+      return textResult(fenceSidecarOutput(body));
     }
     // Default: summary
     const summaryPath = path.join(sessionDir, 'summary.md');
@@ -667,49 +723,47 @@ const handlers = {
     // parent context (inbound mirror of prompt-builder's outbound fence). Same
     // fence also wraps wave-summary and conversation-mode reads above (B03);
     // mode=metadata and every --json contract stay unfenced (structured data).
-    return textResult(fenceSidecarOutput(header + summaryText));
+    // Sliced BEFORE fencing (15a.3/B17). The model header is prepended before
+    // slicing, so it counts against offset/limit/the cap like the rest of the
+    // body — an explicit offset can page past it, same as any other prose.
+    const { body: slicedSummary } = sliceForRead(header + summaryText, input);
+    return textResult(fenceSidecarOutput(slicedSummary));
   },
 
   async amicus_list(input, project) {
     const cwd = project || getProjectDir(input.project);
-    // Scan BOTH roots: canonical amicus first, then legacy sidecar (shim).
-    const roots = [SESSIONS_DIR, LEGACY_SESSIONS_DIR]
-      .map(d => path.join(cwd, '.claude', d))
-      .filter(fs.existsSync);
-    if (roots.length === 0) { return textResult('No amicus sessions found.'); }
+    const root = path.join(cwd, '.claude', SESSIONS_DIR);
+    if (!fs.existsSync(root)) { return textResult('No amicus sessions found.'); }
 
-    // Dedup by task id — amicus (first root) wins over legacy.
     const byId = new Map();
-    for (const root of roots) {
-      for (const d of fs.readdirSync(root)) {
-        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(d)) { continue; }
-        if (byId.has(d)) { continue; }
-        const metaPath = path.join(root, d, 'metadata.json');
-        if (!fs.existsSync(metaPath)) { continue; }
-        try {
-          const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-          const entry = {
-            id: d, model: meta.model, status: meta.status, agent: meta.agent,
-            briefing: sanitizePreview(String(meta.briefing || ''), 80),
-            createdAt: meta.createdAt,
-            mode: meta.mode
-              || (meta.headless === undefined ? undefined : (meta.headless ? 'headless' : 'interactive')),
-          };
-          // Live-progress enrichment for RUNNING sessions only — readProgress
-          // parses conversation.jsonl, so terminal rows stay cheap.
-          if (meta.status === 'running') {
-            try {
-              const p = readProgress(path.join(root, d));
-              entry.phase = deriveStage(meta.status, p.stage);
-              entry.messageCount = p.messages;
-              entry.lastActivityAt = p.lastActivityAt;
-              entry.latestPreview = p.latestPreview;
-            } catch { /* progress optional */ }
-          }
-          byId.set(d, entry);
-        } catch {
-          // Skip unreadable metadata
+    for (const d of fs.readdirSync(root)) {
+      if (!/^[a-zA-Z0-9_-]{1,64}$/.test(d)) { continue; }
+      if (byId.has(d)) { continue; }
+      const metaPath = path.join(root, d, 'metadata.json');
+      if (!fs.existsSync(metaPath)) { continue; }
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        const entry = {
+          id: d, model: meta.model, status: meta.status, agent: meta.agent,
+          briefing: sanitizePreview(String(meta.briefing || ''), 80),
+          createdAt: meta.createdAt,
+          mode: meta.mode
+            || (meta.headless === undefined ? undefined : (meta.headless ? 'headless' : 'interactive')),
+        };
+        // Live-progress enrichment for RUNNING sessions only — readProgress
+        // parses conversation.jsonl, so terminal rows stay cheap.
+        if (meta.status === 'running') {
+          try {
+            const p = readProgress(path.join(root, d));
+            entry.phase = deriveStage(meta.status, p.stage);
+            entry.messageCount = p.messages;
+            entry.lastActivityAt = p.lastActivityAt;
+            entry.latestPreview = p.latestPreview;
+          } catch { /* progress optional */ }
         }
+        byId.set(d, entry);
+      } catch {
+        // Skip unreadable metadata
       }
     }
 
@@ -881,7 +935,7 @@ const handlers = {
       // The prompt goes via file: the spawned command line must NOT carry it,
       // or it re-hits the ~32KB Windows argument cap (F4 spec §4.2).
       fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
-      fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify({
+      writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
         models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
       }, null, 2), { mode: 0o600 });
@@ -915,7 +969,7 @@ const handlers = {
       try {
         const m = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8'));
         Object.assign(m, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
-        fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify(m, null, 2), { mode: 0o600 });
+        writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify(m, null, 2), { mode: 0o600 });
       } catch { /* best-effort */ }
       return textResult(`Failed to start fan-out: ${err.message}`, true);
     }
@@ -970,31 +1024,6 @@ const handlers = {
   async amicus_guide() { return textResult(getGuideText()); },
 };
 
-// DEPRECATED(amicus-shim): legacy sidecar_* twins of each amicus_* tool.
-// OPT-IN since v1.8.0 — registering both names doubled the advertised tool
-// surface (14 -> 28 per server). Set AMICUS_LEGACY_ALIASES=1 in the MCP
-// entry's "env" to restore them. A stdio MCP server cannot learn the
-// client-side registration key it was launched under (initialize carries
-// clientInfo, not the config key), so an env flag is the only reliable
-// switch. Remove entirely in the next major.
-const LEGACY_TOOL_ALIASES = {
-  amicus_start: 'sidecar_start', amicus_status: 'sidecar_status',
-  amicus_wait: 'sidecar_wait',
-  amicus_read: 'sidecar_read', amicus_list: 'sidecar_list',
-  amicus_resume: 'sidecar_resume', amicus_continue: 'sidecar_continue',
-  amicus_setup: 'sidecar_setup', amicus_abort: 'sidecar_abort',
-  amicus_fanout: 'sidecar_fanout',
-  amicus_guide: 'sidecar_guide',
-  amicus_council_tally: 'sidecar_council_tally',
-  amicus_council_stats: 'sidecar_council_stats',
-  amicus_verdict: 'sidecar_verdict',
-};
-
-/** sidecar_* tool aliases are opt-in as of v1.8.0. */
-function legacyAliasesEnabled(env = process.env) {
-  return env.AMICUS_LEGACY_ALIASES === '1';
-}
-
 /** Start the MCP server on stdio transport */
 async function startMcpServer() {
   const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
@@ -1005,9 +1034,6 @@ async function startMcpServer() {
     // can request them (roots/list) when no explicit project is supplied.
     { capabilities: { roots: {} } }
   );
-  // Read once per call (not at module load) so tests and long-lived
-  // processes observe the env deterministically.
-  const withLegacyAliases = legacyAliasesEnabled();
 
   for (const tool of getTools()) {
     const register = (name) => server.registerTool(
@@ -1025,7 +1051,6 @@ async function startMcpServer() {
       }
     );
     register(tool.name);
-    if (withLegacyAliases && LEGACY_TOOL_ALIASES[tool.name]) { register(LEGACY_TOOL_ALIASES[tool.name]); }
   }
   process.on('SIGTERM', () => {
     sharedServer.shutdown();
@@ -1042,5 +1067,4 @@ async function startMcpServer() {
 
 module.exports = {
   handlers, startMcpServer, getProjectDir, resolveProjectDir, getClientRoot,
-  LEGACY_TOOL_ALIASES, legacyAliasesEnabled,
 };

package/src/mcp-tools.js

@@ -9,6 +9,7 @@
 
 const { z } = require('zod');
 const { formatAliasNames } = require('./utils/config');
+const { READ_CAP_BYTES } = require('./utils/read-slice');
 
 /** Zod pattern for safe task IDs (alphanumeric, hyphens, underscores only) */
 const safeTaskId = z.string().regex(
@@ -159,14 +160,35 @@ function getTools() {
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     description:
       'Read the results of a completed Amicus session. Returns the summary ' +
-      'by default, or full conversation history, or session metadata.',
+      'by default, or full conversation history, or session metadata. ' +
+      'Every mode is capped at ~50KB by default; when content exceeds the ' +
+      'cap and no offset/limit/tail is given, the response is the TAIL of ' +
+      'the content with a "[truncated: ...]" notice as the first line — use ' +
+      'offset/limit or tail to page through the rest.',
     inputSchema: {
       taskId: safeTaskId.describe('The task ID to read.'),
       mode: z.enum(['summary', 'conversation', 'metadata']).optional()
         .default('summary').describe(
           'What to read. summary (default): the fold summary. ' +
-          'conversation: full message history. metadata: session info.'
+          'conversation: full message history. metadata: session info ' +
+          '(always small; offset/limit/tail are ignored in this mode).'
         ),
+      offset: z.number().int().min(0).optional().describe(
+        'Byte offset to start reading from (0-based). When given, no cap or ' +
+        'truncation notice applies — the result is simply bounded by `limit` ' +
+        `(default ${READ_CAP_BYTES} bytes). Takes precedence over \`tail\` if ` +
+        'both are given. Ignored in mode "metadata".'
+      ),
+      limit: z.number().int().min(1).max(READ_CAP_BYTES).optional().describe(
+        `Max bytes to return, 1-${READ_CAP_BYTES}. Defaults to the ${READ_CAP_BYTES}-byte ` +
+        'cap. Ignored in mode "metadata".'
+      ),
+      tail: z.boolean().optional().describe(
+        'Return the last `limit` bytes instead of the start. Ignored if ' +
+        '`offset` is also given, and ignored in mode "metadata". This is ' +
+        'also the implicit default when content exceeds the cap and neither ' +
+        '`offset` nor `tail` is set.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -283,7 +305,9 @@ function getTools() {
         `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
       ),
       council: z.string().optional().describe(
-        "Run a saved council by name (e.g. 'free') instead of 'models'. Expands to the council's members. Mutually exclusive with 'models'."
+        "Run a saved council, or a built-in bench ('free', 'budget', 'frontier'), instead of 'models'. " +
+        "Expands to the council's members; a saved council of the same name shadows a built-in. " +
+        'Mutually exclusive with \'models\'.'
       ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'

package/src/mcp-wait.js

@@ -119,11 +119,14 @@ async function runWait(input, project, deps) {
 
   // Torn-read tolerance: a statusFn THROW, or a non-error result whose
   // content[0].text fails to JSON.parse, is a MISSED TICK — not a hard
-  // failure. metadata.json is written with non-atomic fs.writeFileSync by
-  // several writers, and this loop reads it up to ~55x per call (2s cadence),
-  // multiplying exposure to a mid-write torn read vs the old 25s manual
-  // polling. Keep looping on a miss; only surface an error if the deadline
-  // passes without EVER having seen a valid snapshot.
+  // failure. As of Phase 15 all metadata.json writers use writeFileAtomic
+  // (tmp+rename), so a torn read is no longer expected from any current
+  // writer; this tolerance remains as defense-in-depth for metadata.json
+  // files left by pre-upgrade writers and for exotic filesystems where
+  // rename isn't atomic. This loop reads it up to ~55x per call (2s cadence),
+  // multiplying exposure vs the old 25s manual polling. Keep looping on a
+  // miss; only surface an error if the deadline passes without EVER having
+  // seen a valid snapshot.
   let lastSnapshot = null;
   let lastFailure = null;
 

package/src/opencode-client.js

@@ -540,34 +540,57 @@ function buildServerOptions(options = {}) {
 }
 
 const { findListenerPid } = require('./utils/port-pid');
+const { waitThenKill: defaultWaitThenKill } = require('./utils/abort-coordinator');
+
+// Teardown-appropriate grace window for the SIGTERM->SIGKILL escalation on
+// close() (B06). Constant, not env-overridable — this is process teardown,
+// not the marker-honoring abort grace in abort-coordinator.js.
+const CLOSE_KILL_GRACE_MS = 2000;
 
 /**
  * Build the { url, goPid, close } server handle around a raw SDK server.
  * Extracted + dependency-injected so the goPid capture and cross-platform
  * force-kill (F3 #15) can be unit-tested without the SDK's dynamic import.
+ *
+ * close() (B06 teardown-race fix): sdkServer.close() SIGTERMs the SDK's
+ * wrapper script, not the Go binary — the SDK exposes no pid for it. So
+ * close() ALSO SIGTERMs goPid directly (captured via the port scan / sdk
+ * pid fields above) and runs it through the REF'd SIGTERM->SIGKILL
+ * escalation primitive, bounded by CLOSE_KILL_GRACE_MS. The old unref'd
+ * SIGKILL-only timer is gone: on POSIX it could die with the parent before
+ * ever firing (orphaning the Go server), and it never sent a SIGTERM to the
+ * Go pid at all. On win32 this is a no-op beyond firing the signal — the
+ * job-object semantics that already reap the tree are untouched.
  * @param {{url:string, close:Function, pid?:number, process?:{pid:number}}} sdkServer
- * @param {{findListenerPid?:Function, kill?:Function, logger?:object}} [deps]
+ * @param {{findListenerPid?:Function, kill?:Function, logger?:object, waitThenKill?:Function}} [deps]
  * @returns {{url:string, goPid:number|null, close:Function}}
  */
 function buildServerHandle(sdkServer, deps = {}) {
   const findPid = deps.findListenerPid || findListenerPid;
   const kill = deps.kill || ((pid, sig) => process.kill(pid, sig));
   const log = deps.logger || require('./utils/logger').logger;
+  const waitThenKill = deps.waitThenKill || defaultWaitThenKill;
   const serverPort = parseInt(new URL(sdkServer.url).port, 10);
   const goPid = sdkServer.pid || (sdkServer.process && sdkServer.process.pid) || findPid(serverPort);
   const server = {
     url: sdkServer.url,
     goPid,
-    close() {
+    async close() {
       sdkServer.close();
-      const fallback = setTimeout(() => {
-        const pid = server.goPid;
-        if (pid && pid !== process.pid) {
-          try { kill(pid, 'SIGKILL'); } catch { /* already dead */ }
-          log.debug('Force-killed OpenCode server', { port: serverPort, pid });
-        }
-      }, 2000);
-      if (fallback.unref) { fallback.unref(); }
+      const pid = server.goPid;
+      if (!pid || pid === process.pid) { return; }
+      // graceMs: 0 => waitThenKill's own poll fires the direct SIGTERM to
+      // goPid immediately (no wait beforehand — the SDK's close() above never
+      // reaches the Go binary, so there is no reason to delay this one), then
+      // the escalation tier SIGKILLs any survivor after CLOSE_KILL_GRACE_MS.
+      const { escalated } = await waitThenKill(pid, {
+        graceMs: 0,
+        escalate: { killGraceMs: CLOSE_KILL_GRACE_MS },
+        deps: { kill },
+      });
+      if (escalated.includes(pid)) {
+        log.debug('Force-killed OpenCode server', { port: serverPort, pid });
+      }
     }
   };
   return server;