amicus 3.2.2 → 4.0.0

package/src/prompt-builder.js

@@ -4,7 +4,7 @@
  * Spec Reference: §6 Fold Mechanism, §9 Implementation
  * Constructs system prompts for sidecar sessions in both interactive and headless modes.
  */
-const { buildFoldMarker } = require('./utils/fold-marker');
+const { buildFoldMarker, stripFoldMarkers } = require('./utils/fold-marker');
 
 /**
  * Summary template for fold output per spec §6.1
@@ -78,17 +78,19 @@ function buildSystemPrompt(briefing, context, project, headless, mode, client) {
  * @param {string} [mode='code'] - Agent mode ('code', 'ask', or 'plan')
  * @param {string} [summaryLength='normal'] - Desired summary length for headless mode
  * @param {string} [client='code-local'] - Client type for branding
- * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). Only used in
- *   headless mode: the model is instructed to emit `[SIDECAR_FOLD:<nonce>]` instead of
- *   the legacy bare `[SIDECAR_FOLD]`, so runHeadless's detector (which must be given
- *   this SAME nonce) can't be forced into completing by a model that merely echoes the
- *   public, guessable bare marker. Callers that build a headless prompt and intend to
- *   run it should generate one nonce (utils/fold-marker.generateFoldNonce()) BEFORE
- *   calling buildPrompts, pass it here, and pass the SAME value to runHeadless's
- *   options.nonce. Omitted in interactive mode (GUI fold is exit-code driven, not
- *   marker-detected) and harmless to omit in headless mode too — buildHeadlessModeSection
- *   falls back to the legacy bare marker, matching runHeadless's own no-nonce fallback.
+ * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). REQUIRED in
+ *   headless mode; ignored in interactive mode. In headless mode the model is instructed
+ *   to emit `[SIDECAR_FOLD:<nonce>]` instead of the legacy bare `[SIDECAR_FOLD]`, so
+ *   runHeadless's detector (which must be given this SAME nonce) can't be forced into
+ *   completing by a model that merely echoes the public, guessable bare marker. Callers
+ *   that build a headless prompt generate one nonce (utils/fold-marker.generateFoldNonce())
+ *   BEFORE calling buildPrompts, pass it here, and pass the SAME value to runHeadless's
+ *   options.nonce. Omitting it in headless mode THROWS (see @throws) — there is no
+ *   bare-marker fallback on this live path: a real prompt must never advertise the
+ *   guessable marker. Interactive mode ignores the nonce entirely (GUI fold is
+ *   exit-code driven, not marker-detected).
  * @returns {{system: string, userMessage: string}} Separated prompts
+ * @throws {TypeError} If `headless` is true and no `nonce` is supplied.
  *
  * @example
  * const { system, userMessage } = buildPrompts(
@@ -101,6 +103,19 @@ function buildSystemPrompt(briefing, context, project, headless, mode, client) {
  * // Use: POST /session/:id/message { system, parts: [{ type: 'text', text: userMessage }] }
  */
 function buildPrompts(briefing, context, project, headless, mode, summaryLength = 'normal', client, nonce) {
+  // 15b.3 (#BL-7 residual): a headless run MUST carry a per-run nonce so the
+  // model is instructed to emit the unguessable `[SIDECAR_FOLD:<nonce>]` — never
+  // the public, guessable bare `[SIDECAR_FOLD]`. buildPrompts is the live
+  // orchestration boundary (start / continue / fanout / mcp-server all route
+  // through it, and all four already generate and pass a nonce), so a forgotten
+  // nonce fails loud HERE rather than silently baking the bare marker into an
+  // executed prompt. Mirrors headless.js's producer precedent — extractSummary /
+  // formatFoldOutput throw a TypeError when the nonce is missing. Interactive
+  // mode is exempt: its fold is exit-code driven, not marker-detected.
+  if (headless && !nonce) {
+    throw new TypeError('buildPrompts requires a per-run nonce for headless mode (15b.3/v4.0 §9)');
+  }
+
   const systemSections = [
     buildHeader(client),
     buildEnvironmentSection(project, mode),
@@ -108,11 +123,11 @@ function buildPrompts(briefing, context, project, headless, mode, summaryLength
   ];
 
   // Strip fold markers from context so the model doesn't mimic them from
-  // previous sidecar outputs in the conversation history. Matches BOTH the
-  // legacy bare `[SIDECAR_FOLD]` and any nonced `[SIDECAR_FOLD:<nonce>]` —
-  // a resumed/continued conversation's history can carry either shape
-  // depending on when the prior turn ran (15b.3).
-  const cleanContext = context ? context.replace(/\[SIDECAR_FOLD(:[^\]]*)?\]/g, '') : context;
+  // previous sidecar outputs in the conversation history. stripFoldMarkers
+  // (src/utils/fold-marker.js) removes BOTH the legacy bare `[SIDECAR_FOLD]`
+  // and any nonced `[SIDECAR_FOLD:<nonce>]` — marker-only lines vanish
+  // entirely; inline occurrences are removed in place (v4.0 §9).
+  const cleanContext = stripFoldMarkers(context);
 
   let userMessage;
   if (headless) {
@@ -254,9 +269,11 @@ Keep track of key findings as you work.`;
  * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). When provided,
  *   the model is instructed to emit `[SIDECAR_FOLD:<nonce>]` instead of the legacy bare
  *   `[SIDECAR_FOLD]` — see buildPrompts' @param doc for the full rationale. Falls back to
- *   the legacy bare marker when omitted (keeps this function usable standalone / by the
- *   deprecated buildSystemPrompt(), which has no orchestration-layer caller to source a
- *   nonce from).
+ *   the legacy bare marker when omitted. NOTE: buildPrompts — the live orchestration path —
+ *   now THROWS rather than reach this helper without a nonce in headless mode, so the
+ *   fallback branch is reachable ONLY via the deprecated buildSystemPrompt(), which has no
+ *   orchestration-layer caller to source a nonce from and launches no real runs. Its bare
+ *   marker is therefore inert: nothing on a live run path ever advertises the guessable form.
  * @returns {string}
  */
 function buildHeadlessModeSection(summaryLength, nonce) {

package/src/sidecar/electron-lock.js

@@ -22,7 +22,10 @@ const STALE_MS = 15 * 60 * 1000;
 
 /** Temp-dir lockfile path, keyed by the electron install dir. */
 function lockPathFor(electronDir) {
-  const key = Buffer.from(electronDir).toString('hex').slice(0, 16);
+  // Hash the FULL path: a truncated hex prefix collapsed distinct installs that
+  // share a leading path segment (C:\Users…, /home/us…) onto one lockfile,
+  // defeating per-install isolation. Mirrors src/utils/engine-lock.js.
+  const key = require('crypto').createHash('sha1').update(electronDir).digest('hex').slice(0, 16);
   return path.join(os.tmpdir(), `amicus-electron-repair-${key}.lock`);
 }
 

package/src/sidecar/fanout-leg.js

@@ -64,7 +64,7 @@ function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
  * Run one leg end-to-end: session record → runHeadless (shared server) →
  * leg finalize. Never throws — always resolves to a run document.
  */
-async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce }) {
+async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce, directory }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
@@ -107,7 +107,7 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
     result = await runHeadless(
       leg.model, systemPrompt, userMessage, legId, project,
       timeoutMs, agent || 'build',
-      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce }
+      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce, directory }
     );
   } catch (err) {
     result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId: legId };

package/src/sidecar/fanout.js

@@ -245,7 +245,7 @@ async function runFanout(options) {
           leg, legId: legIds[i], waveId, project, systemPrompt, userMessage,
           timeoutMs, agent: options.agent, client, server,
           summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
-          foldNonce,
+          foldNonce, directory: options.directory,
         })
       : Promise.resolve(buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }))
     )));

package/src/sidecar/resume.js

@@ -17,7 +17,7 @@ const {
 } = require('./session-utils');
 const { acquireLock, releaseLock } = require('../utils/session-lock');
 const { runHeadless } = require('../headless');
-const { extractNonceFromText, generateFoldNonce } = require('../utils/fold-marker');
+const { extractNonceFromText, generateFoldNonce, stripFoldMarkers } = require('../utils/fold-marker');
 const { logger } = require('../utils/logger');
 
 /** Load session metadata from session directory */
@@ -83,7 +83,12 @@ function buildResumeUserMessage(briefing, conversation) {
 
   if (conversation) {
     parts.push('## PREVIOUS CONVERSATION\n');
-    parts.push(conversation);
+    // v4.0 §9: the replay used to carry the previous turn's valid nonced
+    // [SIDECAR_FOLD:<nonce>] marker verbatim (BACKLOG "Resume nonce-echo
+    // hazard"). Each run mints a fresh nonce so the stale marker could never
+    // fold the new run, but a wire-format token has no business riding into
+    // the new prompt — strip every marker line before embedding.
+    parts.push(stripFoldMarkers(conversation));
     parts.push('\n---\n');
     parts.push('## RESUME\n');
     parts.push('You are resuming a previous session. Continue from where you left off.');

package/src/utils/abort-result.js

@@ -16,7 +16,7 @@ const { SCHEMA_VERSION } = require('./result-schema-version');
  * a specific taskId that exists yet was not running (already terminal) reports
  * ok:false so a scripted caller can tell "nothing happened" from "you aborted N".
  * @param {object} opts
- * @param {'session'|'wave'|'all'} opts.scope
+ * @param {'session'|'wave'|'all'|'council-run'} opts.scope
  * @param {string|null} opts.taskId - null for scope:'all'
  * @param {string[]} opts.aborted - ids actually marked aborted (session/wave id + any legs)
  * @returns {object} abort document

package/src/utils/error-doc.js

@@ -20,6 +20,8 @@ const ERROR_CODES = Object.freeze({
   BAD_SESSION: 'BAD_SESSION',       // task id missing / invalid / not found
   BUDGET_EXCEEDED: 'BUDGET_EXCEEDED', // the WS-2 #10 spend gate
   INTERNAL: 'INTERNAL',             // unexpected pre-flight throw
+  COUNCIL_QUORUM: 'COUNCIL_QUORUM', // council run: <2 surviving Stage-1 reviews (v4.0 §4)
+  COST_EXCEEDED: 'COST_EXCEEDED',   // council run: whole-run --max-cost ceiling hit pre-tally (v4.0 §4)
 });
 
 /**

package/src/utils/fold-marker.js

@@ -70,10 +70,31 @@ function extractNonceFromText(text) {
   return m ? m[1] : null;
 }
 
+/**
+ * v4.0 §9 (BL-7 done-done): remove every fold-marker occurrence — bare
+ * `[SIDECAR_FOLD]` and nonced `[SIDECAR_FOLD:<nonce>]` — from a text.
+ * A line consisting of ONLY a marker (plus horizontal whitespace) is removed
+ * together with its line terminator; a marker embedded mid-line is removed in
+ * place, keeping the rest of the line. Superset of prompt-builder.js's old
+ * inline regex (which left empty lines behind) — used by the resume replay
+ * (src/sidecar/resume.js) and buildPrompts (src/prompt-builder.js) so a
+ * replayed conversation never carries a stale wire-format token.
+ * @param {string|null|undefined} text
+ * @returns {string|null|undefined} falsy input is returned unchanged
+ */
+function stripFoldMarkers(text) {
+  if (!text) { return text; }
+  const marker = `\\[${FOLD_MARKER_PREFIX}(:[^\\]]*)?\\]`;
+  const markerOnlyLine = new RegExp(`^[^\\S\\r\\n]*${marker}[^\\S\\r\\n]*(?:\\r?\\n|$)`, 'gm');
+  const inlineMarker = new RegExp(marker, 'g');
+  return text.replace(markerOnlyLine, '').replace(inlineMarker, '');
+}
+
 module.exports = {
   FOLD_MARKER_PREFIX,
   generateFoldNonce,
   buildFoldMarker,
   trailingFoldMarkerRegex,
   extractNonceFromText,
+  stripFoldMarkers,
 };

package/src/utils/route-error.js

@@ -145,9 +145,35 @@ function toCliMessage(result) {
   return lines.join('\n');
 }
 
+/**
+ * v4.0 §7: map a RouteResult onto error-doc fields ({code, message, hint})
+ * for buildErrorDoc/failJson — the CLI --json and MCP failure surfaces.
+ * Key-shaped reasons map to MISSING_KEY; everything else is BAD_MODEL.
+ * Suggestions are inlined into the message text (the error doc has no
+ * structured suggestions slot; the hint carries the fix line).
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {{code: string, message: string, hint: (string|null)}}
+ */
+function toErrorDocFields(result) {
+  const { ERROR_CODES } = require('./error-doc');
+  const KEY_REASONS = ['no_openrouter_key', 'no_direct_key', 'no_key_for_vendor'];
+  const err = toStructuredError(result);
+  const sentence = REASON_TEXT[err.reason] || `Model routing error (${err.reason}).`;
+  let message = err.requested ? `${sentence} (requested "${err.requested}")` : sentence;
+  if (err.suggestions.length > 0) {
+    message += ` Did you mean: ${err.suggestions.map((s) => s && s.model).filter(Boolean).join(', ')}?`;
+  }
+  return {
+    code: KEY_REASONS.includes(err.reason) ? ERROR_CODES.MISSING_KEY : ERROR_CODES.BAD_MODEL,
+    message,
+    hint: FIX_HINTS[err.reason] || null,
+  };
+}
+
 module.exports = {
   toStructuredError,
   toCliMessage,
+  toErrorDocFields,
   REASON_TEXT,
   ROUTE_ERROR_REASONS,
   SELECTION_REQUIRED_REASON,

package/src/utils/start-helpers.js

@@ -46,7 +46,8 @@ function deriveAlias(args) {
 async function resolveLaunchModel(args) {
   const { resolveGatewayMode } = require('./config');
   const { resolveRouteForLaunch } = require('./route-launch');
-  const { toCliMessage, toStructuredError } = require('./route-error');
+  const { toCliMessage, toErrorDocFields } = require('./route-error');
+  const { failJson, ERROR_CODES } = require('./error-doc');
   const { resolveModelInputOrDefault } = require('./model-input-default');
 
   const gatewayMode = resolveGatewayMode(args.gateway);
@@ -66,9 +67,13 @@ async function resolveLaunchModel(args) {
   // via model-input-default.js, so this lookup lives in exactly one place.
   const modelInput = resolveModelInputOrDefault(args.model);
   if (modelInput === undefined) {
-    process.stderr.write(
-      'No model specified and no default configured. Run \'amicus setup\' to set a default model.\n'
-    );
+    const message = 'No model specified and no default configured. Run \'amicus setup\' to set a default model.';
+    if (args.json) {
+      // v4.0 §7: --json pre-flight failures land on STDOUT as the error doc.
+      failJson(true, { code: ERROR_CODES.BAD_MODEL, message, hint: 'amicus setup' });
+    } else {
+      process.stderr.write(`${message}\n`);
+    }
     process.exit(1);
   }
 
@@ -106,17 +111,21 @@ async function resolveLaunchModel(args) {
         provenance: result.provenance || {},
       };
     } catch (err) {
-      process.stderr.write(`${err.message || 'Model selection cancelled.'}\n`);
+      const message = err.message || 'Model selection cancelled.';
+      if (args.json) {
+        failJson(true, { code: ERROR_CODES.BAD_MODEL, message,
+          hint: 'Pass --model <vendor/model> explicitly to skip the picker.' });
+      } else {
+        process.stderr.write(`${message}\n`);
+      }
       process.exit(1);
     }
   }
 
-  // 'error': render and exit. (A non-interactive run never reaches
-  // kind:'selection_required' — allowSelection is false there, so the router
-  // resolves a catalog miss straight to kind:'error' with reason
-  // 'model_not_found' instead; see gateway-router.js's catalogGate.)
+  // 'error': render and exit. Under --json the error doc goes to STDOUT
+  // (v4.0 §7 — was toStructuredError on stderr); human stderr is unchanged.
   if (args.json) {
-    process.stderr.write(`${JSON.stringify(toStructuredError(result))}\n`);
+    failJson(true, toErrorDocFields(result));
   } else {
     process.stderr.write(`${toCliMessage(result)}\n`);
   }

package/src/utils/untrusted-fence.js

@@ -9,13 +9,14 @@
  * marked as data, not instructions.
  *
  * Applies to every prose channel a sidecar model's output reaches an agent
- * through: MCP amicus_read (summary, wave summary, conversation) and the
- * CLI's non-JSON stdout (read summary/conversation/wave-human, and the
- * foreground start/continue/resume summary echo). It must NOT be applied to
- * JSON contracts (--json stdout, amicus_council_tally/verdict) or metadata
- * (amicus_read mode=metadata) — those are structured data a caller parses,
- * not prose read directly by an LLM, and wrapping them would break the
- * contract.
+ * through: MCP amicus_read (summary, wave summary, conversation), the CLI's
+ * non-JSON stdout (read summary/conversation/wave-human, and the foreground
+ * start/continue/resume summary echo), and — since v4.0 (H9) — the council
+ * MCP tools' JSON returns (amicus_council_tally / amicus_council_stats /
+ * amicus_verdict), whose docs embed untrusted model-raised findings; the JSON
+ * stays intact inside the fence. It must NOT be applied to CLI --json stdout
+ * (the byte-parseable programmatic channel) or amicus_read mode=metadata —
+ * structured data a caller parses, where wrapping would break the contract.
  */
 'use strict';