amicus 1.9.1 → 2.1.0

package/src/cli.js

@@ -94,6 +94,17 @@ function parseArgs(argv) {
       } else {
         result[key] = true;
       }
+    } else if (arg === '-o') {
+      // Single short-flag alias, scoped to exactly '-o' (council verdict's
+      // --out shorthand). No general short-flag support is implemented —
+      // any other leading-dash token still falls through to positionals.
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        result.out = next;
+        i++;
+      } else {
+        result.out = true;
+      }
     } else {
       result._.push(arg);
     }
@@ -338,7 +349,10 @@ Commands:
   council tally <input.json> [--json]   Tally council findings → tiers/street-cred
   council stats [--json]                Reviewer-reliability from the ledger
   council report <verdict.json> [--wave <wave.json>] [--md|--html]   Disagreement+verdict report
+  council validate <file> [--json]      Validate a Stage-1 findings block (exit 0/2/1)
+  council verdict <tally.json> [--decisions <d.json>] [-o <out.json>]   Build + write verdict.json
   doctor      Check your setup: keys, catalog, binary, skills, MCP (--json)
+  spend [--since 7d] [--json]           Cross-run cost rollup from the spend ledger
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
@@ -428,6 +442,7 @@ Options for 'status':
   abort: `
 Options for 'abort':
   --all                        Abort all running sessions in this project
+  --json                       Emit the abort result as stable JSON
 `,
   read: `
 Options for 'read':
@@ -443,6 +458,7 @@ Options for 'continue':
   --model <model>              Optional. Override the model (alias or provider/model)
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
+  --json                       With --no-ui: emit the run result as stable JSON
   --timeout <minutes>          Headless timeout (default: 15)
   --context-turns <N>          Max conversation turns (default: 50)
   --context-max-tokens <N>     Max context tokens (default: 80000)
@@ -452,6 +468,7 @@ Options for 'resume':
   <task_id>                    Required. Session to reopen (positional)
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
+  --json                       With --no-ui: emit the run result as stable JSON
   --timeout <minutes>          Headless timeout (default: 15)
 `,
   council: `
@@ -465,12 +482,33 @@ Subcommands for 'council':
     --wave <wave.json>         Include per-leg run stats from a wave file
     --md                       Emit Markdown (default)
     --html                     Emit a self-contained HTML page
+  validate <file>               Validate a Stage-1 reviewer's findings block
+    --json                     Machine-readable output
+    Exit codes: 0 ok:true, 2 ok:false (validation failure), 1 BAD_ARGS
+                               (missing/unreadable file)
+  verdict <tally.json>          Build + write verdict.json (buildVerdict + atomic write)
+    --decisions <d.json>       Optional. Stage-4 decisions array (default [])
+    -o, --out <out.json>       Output path (default ./verdict.json)
+    --json                     Print the full verdict document
+  save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
+    --json                     Machine-readable output
+  list                          List saved councils plus the built-in benches
+    --json                     Machine-readable output
+  show <name>                   Resolve a council by name (saved or built-in)
+    --json                     Machine-readable output
 `,
   doctor: `
 Options for 'doctor':
   --json                       Machine-readable output
   --fix                        Self-heal fixable checks in place (provisions the
                                Electron GUI binary; no global reinstall)
+`,
+  spend: `
+Options for 'spend':
+  --since <Nd>                  Restrict to the last N days (e.g. --since 7d)
+  --json                        Machine-readable output (versioned spend doc)
+  Reads ~/.config/amicus/spend-ledger.jsonl (one row per completed run/leg).
+  Shows remaining OpenRouter credit when a key is configured.
 `,
   setup: `
 Options for 'setup':
@@ -511,6 +549,22 @@ Examples:
   amicus read abc123 --conversation
 `;
 
+// Commands handled directly in bin/amicus.js's switch that have no dedicated
+// USAGE_COMMAND_BLOCKS entry (their usage is covered by USAGE_HEADER's command
+// list only). Kept minimal and explicit rather than parsing the switch itself.
+const SWITCH_ONLY_COMMANDS = ['update'];
+
+/**
+ * Canonical list of top-level command names, for did-you-mean suggestions and
+ * any other consumer that needs "every command amicus recognizes" without a
+ * second hand-maintained list. Derived from USAGE_COMMAND_BLOCKS (the existing
+ * per-command help source of truth) plus SWITCH_ONLY_COMMANDS.
+ * @returns {string[]}
+ */
+function getCommandNames() {
+  return [...Object.keys(USAGE_COMMAND_BLOCKS), ...SWITCH_ONLY_COMMANDS];
+}
+
 /**
  * Get usage text.
  *
@@ -535,5 +589,6 @@ module.exports = {
   parseArgs,
   validateStartArgs,
   getUsage,
+  getCommandNames,
   DEFAULTS
 };

package/src/council/presets-cli.js

@@ -0,0 +1,141 @@
+// src/council/presets-cli.js
+'use strict';
+
+/**
+ * `amicus council save|list|show` — CLI wrappers around the council-preset
+ * primitives (src/utils/config.js councils.*, src/utils/council-presets.js
+ * built-in benches). Split out of cli-handlers-council.js to keep that file
+ * under the 300-line size gate.
+ */
+
+const { failJson, ERROR_CODES } = require('../utils/error-doc');
+const { listBuiltinCouncilNames } = require('../utils/council-presets');
+
+/**
+ * `amicus council save <name> --models a,b,c`
+ * Validates >=2 members, each resolvable via the same alias/catalog logic
+ * `resolveCouncilMembers` uses (effective aliases, or a raw `provider/model`
+ * id containing '/'). Overwrites an existing name with a notice — this is
+ * also how a user shadows a built-in bench of the same name.
+ * @param {string|undefined} name
+ * @param {string|undefined} modelsArg comma-separated aliases/ids
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runSave(name, modelsArg, useJson) {
+  if (!name) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council save needs a <name>',
+      hint: 'amicus council save <name> --models a,b,c' });
+  }
+  if (typeof modelsArg !== 'string' || !modelsArg.trim()) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council save needs --models a,b,c',
+      hint: 'amicus council save <name> --models a,b,c' });
+  }
+  const members = modelsArg.split(',').map(m => m.trim()).filter(Boolean);
+  if (members.length < 2) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'a council needs at least 2 members',
+      hint: 'pass --models with 2 or more comma-separated aliases or provider/model IDs' });
+  }
+  const { getEffectiveAliases, loadConfig, saveConfig, getCouncil } = require('../utils/config');
+  const aliases = getEffectiveAliases();
+  const unresolved = members.filter(m => !m.includes('/') && !aliases[m]);
+  if (unresolved.length) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `unresolvable member(s): ${unresolved.join(', ')}`,
+      hint: 'each member must be a known alias (see `amicus models`) or a provider/model id containing "/"' });
+  }
+  const overwritten = !!getCouncil(name);
+  const cfg = loadConfig() || {};
+  if (!cfg.councils) { cfg.councils = {}; }
+  cfg.councils[name] = members;
+  saveConfig(cfg);
+  const doc = { ok: true, name, models: members, overwritten };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderSave(doc));
+  return 0;
+}
+
+function renderSave(doc) {
+  const notice = doc.overwritten ? ' (overwritten)' : '';
+  return `Saved council '${doc.name}'${notice}: ${doc.models.join(', ')}\n`;
+}
+
+/**
+ * `amicus council list [--json]` — user-saved councils plus the built-in
+ * benches (free/budget/frontier), each entry marked `builtin`. When a user
+ * council shares a name with a built-in, BOTH entries are listed: the user
+ * entry (builtin:false) is the one actually used by resolveCouncilMembers,
+ * and the built-in entry (builtin:true) is marked `shadowed:true`.
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runList(useJson) {
+  const { getCouncils } = require('../utils/config');
+  const userCouncils = getCouncils();
+  const userNames = new Set(Object.keys(userCouncils));
+  const entries = [];
+  for (const name of Object.keys(userCouncils).sort()) {
+    entries.push({ name, builtin: false, members: userCouncils[name] });
+  }
+  for (const name of listBuiltinCouncilNames()) {
+    const entry = { name, builtin: true };
+    if (userNames.has(name)) { entry.shadowed = true; }
+    entries.push(entry);
+  }
+  const doc = { councils: entries };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderList(entries));
+  return 0;
+}
+
+function renderList(entries) {
+  const lines = entries.map(e => {
+    if (e.builtin) { return `  ${e.name.padEnd(16)} [built-in]${e.shadowed ? ' (shadowed by a saved council of the same name)' : ''}`; }
+    return `  ${e.name.padEnd(16)} ${e.members.join(', ')}`;
+  });
+  return 'Councils:\n' + lines.join('\n') + '\n';
+}
+
+/**
+ * `amicus council show <name> [--json]` — resolves `name` exactly like
+ * `resolveCouncilMembers` (user config first, built-in fallback) and
+ * displays the raw members plus per-member resolution results (resolved /
+ * dropped). Unlike `resolveCouncilMembers` (which the run paths use, and
+ * which fails outright below 2 usable members), `show` is diagnostic-only:
+ * it always reports the full resolved/dropped split, even for a council
+ * that currently has fewer than 2 usable members.
+ * @param {string|undefined} name
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runShow(name, useJson) {
+  if (!name) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council show needs a <name>',
+      hint: 'amicus council show <name> [--json]' });
+  }
+  const { getCouncilWithSource, getEffectiveAliases } = require('../utils/config');
+  const { readCache } = require('../utils/model-catalog');
+  const catalog = (readCache() || {}).models || [];
+  const { members, builtin } = getCouncilWithSource(name, catalog);
+  if (!members) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Unknown council '${name}'`,
+      hint: "'amicus council list' shows available councils, or 'amicus council save' to create one" });
+  }
+  const aliases = getEffectiveAliases();
+  const resolved = [];
+  const dropped = [];
+  for (const member of members) {
+    const id = member.includes('/') ? member : aliases[member];
+    (id ? resolved : dropped).push(member);
+  }
+  const doc = { name, builtin, members, resolved, dropped };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderShow(doc));
+  return 0;
+}
+
+function renderShow(doc) {
+  const tag = doc.builtin ? ' [built-in]' : '';
+  let out = `Council '${doc.name}'${tag}\n  members: ${doc.members.join(', ')}\n  resolved: ${doc.resolved.join(', ')}\n`;
+  if (doc.dropped.length) { out += `  dropped: ${doc.dropped.join(', ')}\n`; }
+  return out;
+}
+
+module.exports = { runSave, runList, runShow };

package/src/headless.js

@@ -12,33 +12,51 @@ const { ensureNodeModulesBinInPath } = require('./utils/path-setup');
 const { ensurePortAvailable } = require('./utils/server-setup');
 const { mapAgentToOpenCode } = require('./utils/agent-mapping');
 const { writeProgress } = require('./sidecar/progress');
-const { createMirrorState, mirrorMessages, logMessage } = require('./sidecar/conversation-mirror');
+const { writeFileAtomic } = require('./utils/atomic-write');
+const { createMirrorState, mirrorMessages, logMessage, getPendingToolCalls } = require('./sidecar/conversation-mirror');
+const { buildFoldMarker, trailingFoldMarkerRegex, generateFoldNonce } = require('./utils/fold-marker');
 
 /**
- * Fold marker that the agent outputs when done
+ * Fold marker that the agent outputs when done.
  * Spec Reference: §6.2
+ *
+ * #BL-7 residual (15b.3): the bare `[SIDECAR_FOLD]` string is now a LEGACY
+ * literal only, kept exported for external consumers with no nonce context
+ * (see extractSummary/formatFoldOutput's no-nonce fallback paths below).
+ * NOTE for anyone `.toContain('[SIDECAR_FOLD]')`-checking real run output:
+ * that substring check does NOT match the real nonced marker — a nonced
+ * marker is `[SIDECAR_FOLD:<nonce>]`, which lacks the literal closing
+ * bracket immediately after FOLD that `[SIDECAR_FOLD]` requires. Real runs
+ * always call buildFoldMarker(nonce), never this bare constant.
  */
 const FOLD_MARKER = '[SIDECAR_FOLD]';
 const COMPLETE_MARKER = FOLD_MARKER; // backward compat
 
 /**
- * #BL-7: the fold marker is the fixed public string [SIDECAR_FOLD]. A model can
- * legitimately emit it on its own line mid-output — summarizing a prior sidecar,
- * reproducing these instructions, or from scraped content — which used to force a
- * PREMATURE fold. Harden by requiring the marker to be the FINAL non-empty line
- * of the output: a standalone marker followed by MORE content is treated as
- * echoed prose, not a completion signal. Only the true trailing marker folds.
+ * #BL-7: the fold marker used to be the fixed public string [SIDECAR_FOLD]. A
+ * model can legitimately emit that bare string on its own line mid-output —
+ * summarizing a prior sidecar, reproducing these instructions, or from
+ * scraped content — which forced a PREMATURE fold even after pinning the
+ * marker to the final non-empty line (the marker being fixed and public means
+ * ANY echo of it, if it happened to land last, still completed the run).
+ *
+ * 15b.3 closes the residual gap: every run now carries a per-run random
+ * nonce, and the model is instructed to emit `[SIDECAR_FOLD:<nonce>]` — a
+ * string the model can only produce by actually finishing (it isn't public,
+ * isn't in training data, and isn't guessable). A bare `[SIDECAR_FOLD]` or a
+ * marker carrying a DIFFERENT run's nonce no longer completes.
  *
  * @param {string} output - Accumulated assistant output
+ * @param {string} nonce - This run's fold nonce (required — see runHeadless)
  * @returns {number} char index where the trailing marker line begins, or -1
  */
-function findTrailingFoldMarker(output) {
-  if (!output) { return -1; }
+function findTrailingFoldMarker(output, nonce) {
+  if (!output || !nonce) { return -1; }
   // The marker must be the last non-empty line: it sits alone on its line
   // (only intra-line whitespace around it) and NOTHING but whitespace follows
   // to the end of the string. The `(?![\s\S]*\S)` lookahead pins it to the true
-  // end — a bare marker followed by more prose is echoed content, not a signal.
-  const m = /^[^\S\r\n]*\[SIDECAR_FOLD\][^\S\r\n]*$(?![\s\S]*\S)/m.exec(output);
+  // end — a marker followed by more prose is echoed content, not a signal.
+  const m = trailingFoldMarkerRegex(nonce).exec(output);
   return m ? m.index : -1;
 }
 
@@ -53,6 +71,7 @@ const STABLE_FINISHED_POLLS = Number(process.env.AMICUS_STABLE_FINISHED_POLLS) |
 const STABLE_IDLE_POLLS = Number(process.env.AMICUS_STABLE_IDLE_POLLS) || 30;          // ~60s at 2s — no completion signal
 const POLL_CALL_TIMEOUT_MS = Number(process.env.AMICUS_POLL_CALL_TIMEOUT_MS) || 30000; // per getMessages call (used by a later task)
 const MAX_CONSECUTIVE_POLL_FAILURES = Number(process.env.AMICUS_MAX_CONSECUTIVE_POLL_FAILURES) || 15; // ≈30s at 2s polls
+const TOOL_CALL_STALL_MS = Number(process.env.AMICUS_TOOL_CALL_STALL_MS) || 180000; // B53: wedged tool call w/ no progress
 
 /**
  * Race a promise against a timeout. Returns the promise's result, or rejects with
@@ -103,6 +122,15 @@ async function waitForServer(client, checkHealthFn, maxAttempts = 30) {
  * @param {string} [options.summaryLength='normal'] - Desired summary length
  * @param {object} [options.reasoning] - Reasoning/thinking configuration
  * @param {string} [options.reasoning.effort] - Effort level: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'none'
+ * @param {string} [options.nonce] - Per-run fold nonce (15b.3, #BL-7 residual). The
+ *   PROMPT the caller built (prompt-builder.js buildPrompts) must have instructed the
+ *   model with this SAME nonce — runHeadless only DETECTS, it never re-derives one from
+ *   the prompt text, so caller and detector agreeing on the nonce is the caller's
+ *   responsibility. Falls back to a freshly generated nonce if omitted (keeps this
+ *   function usable standalone / in tests that don't care about the fold-nonce
+ *   property) — but a fallback nonce the prompt never advertised means the model can
+ *   never legitimately produce it, so such a run can only ever complete via one of the
+ *   non-fold-marker paths (idle/timeout/etc.), never a premature bare-marker fold.
  * @returns {Promise<object>} Result object with summary, completed, timedOut flags
  */
 async function runHeadless(model, systemPrompt, userMessage, taskId, project, timeoutMs = DEFAULT_TIMEOUT, agent, options = {}) {
@@ -116,6 +144,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
   } = require('./opencode-client');
 
   const { reasoning } = options;
+  // 15b.3: never fall back to bare-marker detection — an omitted nonce still
+  // gets ONE generated here so findTrailingFoldMarker always has something to
+  // match, but since the prompt (built by the caller) never advertised THIS
+  // fallback value, the model cannot legitimately produce it. No silent
+  // bare-`[SIDECAR_FOLD]` acceptance path exists anywhere below.
+  const foldNonce = options.nonce || generateFoldNonce();
   const { getSessionDir } = require('./session-manager');
   const sessionDir = getSessionDir(project, taskId);
   const conversationPath = path.join(sessionDir, 'conversation.jsonl');
@@ -202,7 +236,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       writeProgress(sessionDir, 'server_ready');
 
       if (!serverReady) {
-        server.close();
+        await server.close();
         return {
           summary: '',
           completed: false,
@@ -239,7 +273,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         sessionId = await createSession(client, ...dirArgs);
       } catch (error) {
         if (watchdog) { watchdog.cancel(); }
-        if (!externalServer) { server.close(); }
+        if (!externalServer) { await server.close(); }
         return {
           summary: '',
           completed: false,
@@ -261,7 +295,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           const metaPath = path.join(sessionDir, 'metadata.json');
           const m = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
           m.goPid = server.goPid;
-          fs.writeFileSync(metaPath, JSON.stringify(m, null, 2), { mode: 0o600 });
+          writeFileAtomic(metaPath, JSON.stringify(m, null, 2), { mode: 0o600 });
         } catch { /* metadata optional */ }
       }
       const { installSignalAbort, markAborted } = require('./utils/session-abort');
@@ -276,7 +310,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             const { abortSession } = require('./opencode-client');
             abortSession(client, sessionId, ...dirArgs).catch(() => {});
           } catch { /* best-effort */ }
-          try { server.close(); } catch { /* best-effort */ }
+          // close() is now async (B06 escalation) — this handler stays sync
+          // (do not restructure signal handlers), so fire-and-forget with a
+          // rejection guard. The REF'd escalation poll inside close() still
+          // does its work; the pre-existing 300ms exit timer below may cut
+          // that grace short — see task 15b.1 report for that known gap.
+          try { server.close().catch(() => {}); } catch { /* best-effort */ }
           const { resolveTerminalState } = require('./sidecar/session-finalize');
           const code = resolveTerminalState({ aborted: true }, signal).exitCode;
           const t = setTimeout(() => process.exit(code), 300);
@@ -356,6 +395,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     const stableIdlePolls = options.stableIdlePolls || STABLE_IDLE_POLLS;
     const pollCallTimeoutMs = options.pollCallTimeoutMs || POLL_CALL_TIMEOUT_MS;
     const maxConsecutivePollFailures = options.maxConsecutivePollFailures || MAX_CONSECUTIVE_POLL_FAILURES;
+    const toolCallStallMs = options.toolCallStallMs || TOOL_CALL_STALL_MS;
     let consecutivePollFailures = 0;
     let pollFailureBail = false;
     let lastAssistantMsgId = null;
@@ -364,6 +404,9 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let lastToolCallCount = 0;
     let lastToolResultCount = 0;
     let lastMessageCount = 0;
+    let lastReasoningLength = 0; // B53: track reasoning-output growth to detect thinking
+    let lastProgressAt = Date.now(); // B53: last poll where `progressed` was true
+    let toolStalled = false; // B53: distinct from completed/timedOut/aborted — see resolveTerminalState
 
     while (!completed && (Date.now() - startTime) < timeoutMs) {
       watchdog.touch();
@@ -420,11 +463,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           elapsed: Date.now() - startTime
         });
 
-        // Check for the completion marker as the FINAL non-empty line (#BL-7).
-        // Models may emit [SIDECAR_FOLD] on its own line mid-output (echoing a
-        // prior sidecar, these instructions, or scraped content) — only treat
-        // it as a completion signal when nothing but blank lines follow it.
-        if (findTrailingFoldMarker(mirror.output) !== -1) {
+        // Check for the completion marker as the FINAL non-empty line, carrying
+        // THIS run's nonce (#BL-7 + 15b.3). Models may emit a bare or wrong-nonce
+        // marker on its own line mid-output (echoing a prior sidecar, these
+        // instructions, or scraped content) — only the exact nonced marker,
+        // with nothing but blank lines after it, is a completion signal.
+        if (findTrailingFoldMarker(mirror.output, foldNonce) !== -1) {
           completed = true;
           break;
         }
@@ -472,8 +516,9 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         }
 
         // Activity-aware idle detection: ANY of text growth, a new tool call, a new
-        // tool result, a new message, or a new assistant message id counts as progress.
-        // Only count toward completion when NOTHING changed (genuine idle).
+        // tool result, a new message, a new assistant message id, or reasoning-output
+        // growth counts as progress. Only count toward completion when NOTHING changed
+        // (genuine idle).
         const outputGrew = mirror.output.length > lastOutputLength;
         lastOutputLength = mirror.output.length;
         const toolActivity = mirror.toolCalls.length > lastToolCallCount;
@@ -483,8 +528,42 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         const messageActivity = messageCount > lastMessageCount;
         lastMessageCount = messageCount;
         const newAssistant = currentAssistantMsgId !== lastAssistantMsgId;
-
-        const progressed = outputGrew || toolActivity || resultActivity || messageActivity || newAssistant;
+        // B53: an interleaved-thinking model with a pending tool call can stream ONLY
+        // reasoning deltas for minutes with no text/tool/result/message growth — mirror
+        // the F6d treatment in conversation-mirror.js (reasoning growth = activity) so
+        // the stall clock resets instead of falsely firing "Tool call stalled".
+        const reasoningActivity = mirror.reasoningOutput.length > lastReasoningLength;
+        lastReasoningLength = mirror.reasoningOutput.length;
+
+        const progressed = outputGrew || toolActivity || resultActivity || messageActivity
+          || newAssistant || reasoningActivity;
+        if (progressed) { lastProgressAt = Date.now(); }
+
+        // B53: a wedged tool call (tool_use emitted, result never arrives) otherwise
+        // burns the full --timeout with zero output — the stable-poll idle gate above
+        // requires mirror.output.length > 0, which a pre-text wedge never satisfies.
+        // Fire ONLY when a tool call is genuinely pending AND no progress of any kind
+        // (text/tool/result/message/new-assistant) has been observed for the stall
+        // window — this cannot false-positive during active streaming (progress
+        // resets the clock every poll) and cannot fire without a wedged tool.
+        const pendingToolCalls = getPendingToolCalls(mirror);
+        if (pendingToolCalls.length > 0 && (Date.now() - lastProgressAt) > toolCallStallMs) {
+          const stalled = pendingToolCalls[0];
+          const pendingSeconds = Math.round((Date.now() - Date.parse(stalled.firstSeenAt)) / 1000);
+          sessionError = `Tool call stalled: ${stalled.name} pending ${pendingSeconds}s with no result or output`;
+          logger.error('Tool call stalled — no progress within threshold', {
+            taskId, toolName: stalled.name, toolId: stalled.id, pendingSeconds, toolCallStallMs
+          });
+          toolStalled = true;
+          try {
+            const { abortSession } = require('./opencode-client');
+            await abortSession(client, sessionId, ...dirArgs);
+            logger.info('Session aborted after tool-call stall', { taskId, sessionId });
+          } catch (abortErr) {
+            logger.warn('Failed to abort session after tool-call stall', { error: abortErr.message });
+          }
+          break;
+        }
 
         if (!progressed) {
           // Require real output before counting toward completion — the SDK creates an
@@ -556,7 +635,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 
     watchdog.cancel();
     if (uninstallSignals) { uninstallSignals(); }
-    if (!externalServer) { server.close(); }
+    if (!externalServer) { await server.close(); }
 
     // Log summary of tool calls for debugging
     if (mirror.toolCalls.length > 0) {
@@ -572,13 +651,15 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // Propagate the error when the model errored with no output (F1 semantics:
     // a model error alongside streamed output still yields a usable summary),
     // and ALWAYS when the poll loop bailed on consecutive failures (F4: a dead
-    // server must never classify as a complete leg, even with partial output).
+    // server must never classify as a complete leg, even with partial output)
+    // or on a tool-call stall (B53: same — a wedged tool must never classify
+    // as complete, even if some text streamed alongside it before the wedge).
     const { sumPerMessageUsage } = require('./utils/pricing');
     const usage = sumPerMessageUsage(mirror.usageByMsg);
 
-    if (sessionError && (!mirror.output || pollFailureBail)) {
+    if (sessionError && (!mirror.output || pollFailureBail || toolStalled)) {
       return {
-        summary: mirror.output ? extractSummary(mirror.output) : '',
+        summary: mirror.output ? extractSummary(mirror.output, foldNonce) : '',
         completed: false,
         timedOut,
         aborted,
@@ -590,7 +671,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     }
 
     return {
-      summary: extractSummary(mirror.output),
+      summary: extractSummary(mirror.output, foldNonce),
       completed,
       timedOut,
       aborted,
@@ -617,7 +698,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     }
     if (watchdog) { watchdog.cancel(); }
     if (uninstallSignals) { uninstallSignals(); }
-    if (!externalServer) { server.close(); }
+    if (!externalServer) { await server.close(); }
     const { emptyUsageTotals } = require('./utils/pricing');
     return {
       summary: '',
@@ -632,28 +713,47 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 }
 
 /**
- * Extract summary from output (everything before the trailing [SIDECAR_FOLD])
- * Spec Reference: §6.2 - Return summary (everything before [SIDECAR_FOLD])
+ * Extract summary from output (everything before the trailing fold marker)
+ * Spec Reference: §6.2 - Return summary (everything before the fold marker)
  *
  * @param {string} output - Raw output from OpenCode
+ * @param {string} [nonce] - This run's fold nonce (15b.3). When omitted, falls
+ *   back to matching the LEGACY bare `[SIDECAR_FOLD]` marker — this keeps
+ *   extractSummary usable as a standalone string utility (e.g. re-processing
+ *   output captured before the nonce scheme, or a caller that genuinely has
+ *   no nonce context) without ever accepting a WRONG nonce as a match.
  * @returns {string} Extracted summary
  */
-function extractSummary(output) {
+function extractSummary(output, nonce) {
   if (!output) {
     return '';
   }
 
   // Split on the fold marker only when it is the FINAL non-empty line (#BL-7).
-  // A [SIDECAR_FOLD] echoed mid-output (describing code, reproducing these
+  // A marker echoed mid-output (describing code, reproducing these
   // instructions, or from scraped content) is NOT a delimiter — keep it as
   // content. Only the true trailing marker is stripped.
-  const idx = findTrailingFoldMarker(output);
+  const idx = nonce ? findTrailingFoldMarker(output, nonce) : findLegacyBareTrailingMarker(output);
   if (idx !== -1) {
     return output.slice(0, idx).trim();
   }
   return output.trim();
 }
 
+/**
+ * Legacy bare-marker trailing match (`[SIDECAR_FOLD]`, no nonce) — the
+ * pre-15b.3 behavior, kept only for extractSummary's no-nonce fallback path.
+ * NEVER used by runHeadless's own detection (that always carries a nonce —
+ * see findTrailingFoldMarker), so no live completion path can be forced by a
+ * bare marker.
+ * @param {string} output
+ * @returns {number}
+ */
+function findLegacyBareTrailingMarker(output) {
+  const m = /^[^\S\r\n]*\[SIDECAR_FOLD\][^\S\r\n]*$(?![\s\S]*\S)/m.exec(output);
+  return m ? m.index : -1;
+}
+
 /**
  * Format a structured fold output with metadata
  * @param {Object} options - Fold output options
@@ -663,11 +763,14 @@ function extractSummary(output) {
  * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
  * @param {string} [options.mode='headless'] - Execution mode
  * @param {string} options.summary - Summary text
+ * @param {string} [options.nonce] - This run's fold nonce (15b.3). When omitted,
+ *   falls back to the legacy bare `[SIDECAR_FOLD]` marker for back-compat with
+ *   external callers of this exported utility that predate the nonce scheme.
  * @returns {string} Formatted fold output
  */
-function formatFoldOutput({ model, sessionId, client, cwd, mode, summary }) {
+function formatFoldOutput({ model, sessionId, client, cwd, mode, summary, nonce }) {
   return [
-    '[SIDECAR_FOLD]',
+    nonce ? buildFoldMarker(nonce) : FOLD_MARKER,
     `Model: ${model}`,
     `Session: ${sessionId}`,
     `Client: ${client || 'code-local'}`,
@@ -688,9 +791,14 @@ module.exports = {
   DEFAULT_TIMEOUT,
   FOLD_MARKER,
   COMPLETE_MARKER,
+  // 15b.3: re-exported so callers that already `require('./headless')` don't
+  // also need `require('./utils/fold-marker')` for the common case.
+  buildFoldMarker,
+  generateFoldNonce,
   POLL_INTERVAL_MS,
   STABLE_FINISHED_POLLS,
   STABLE_IDLE_POLLS,
   POLL_CALL_TIMEOUT_MS,
   MAX_CONSECUTIVE_POLL_FAILURES,
+  TOOL_CALL_STALL_MS,
 };

package/src/index.js

@@ -30,21 +30,13 @@ const { detectEnvironment, inferClient, getSessionRoot } = require('./environmen
 const { compressContext, estimateTokenCount, buildPreamble } = require('./context-compression');
 
 module.exports = {
-  // Canonical Amicus public API (the *Sidecar names below are deprecated shims)
+  // Canonical Amicus public API
   startAmicus: startSidecar,
   listAmicus: listSidecars,
   resumeAmicus: resumeSidecar,
   continueAmicus: continueSidecar,
   readAmicus: readSidecar,
   runFanout,
-
-  // DEPRECATED(amicus-shim): remove *Sidecar exports in a future revision — see docs/SHIMS.md
-  // Primary sidecar APIs
-  startSidecar,
-  listSidecars,
-  resumeSidecar,
-  continueSidecar,
-  readSidecar,
   generateTaskId,
 
   // Context building