amicus 1.9.0 → 2.0.0

package/src/prompt-builder.js

@@ -4,6 +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');
 
 /**
  * Summary template for fold output per spec §6.1
@@ -77,6 +78,16 @@ 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.
  * @returns {{system: string, userMessage: string}} Separated prompts
  *
  * @example
@@ -89,16 +100,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) {
+function buildPrompts(briefing, context, project, headless, mode, summaryLength = 'normal', client, nonce) {
   const systemSections = [
     buildHeader(client),
     buildEnvironmentSection(project, mode),
-    headless ? buildHeadlessModeSection(summaryLength) : buildInteractiveModeSection()
+    headless ? buildHeadlessModeSection(summaryLength, nonce) : buildInteractiveModeSection()
   ];
 
-  // Strip [SIDECAR_FOLD] markers from context so the model doesn't
-  // mimic them from previous sidecar outputs in the conversation history
-  const cleanContext = context ? context.replace(/\[SIDECAR_FOLD\]/g, '') : context;
+  // 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;
 
   let userMessage;
   if (headless) {
@@ -237,9 +251,16 @@ Keep track of key findings as you work.`;
  * Spec Reference: §6.2 Headless Mode
  *
  * @param {string} summaryLength - Desired summary length (brief, normal, verbose)
+ * @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).
  * @returns {string}
  */
-function buildHeadlessModeSection(summaryLength) {
+function buildHeadlessModeSection(summaryLength, nonce) {
+  const marker = nonce ? buildFoldMarker(nonce) : '[SIDECAR_FOLD]';
   let summaryFormat = `## Summary Format
 
 When complete, output your findings in this format:
@@ -266,7 +287,7 @@ When complete, output your findings in this format:
 
 **Open Questions:** (if any)
 
-[SIDECAR_FOLD]`;
+${marker}`;
 
   if (summaryLength === 'brief') {
     summaryFormat = `## Summary Format
@@ -281,7 +302,7 @@ When complete, output a BRIEF summary in this format:
 **Recommendations:**
 [Suggested actions]
 
-[SIDECAR_FOLD]`;
+${marker}`;
   } else if (summaryLength === 'verbose') {
     // Verbose could include more details or examples
     summaryFormat = `## Summary Format (VERBOSE)
@@ -315,7 +336,7 @@ When complete, output a COMPREHENSIVE summary in this format, including all deta
 **Open Questions:** (if any)
 [List all remaining ambiguities, unresolved issues, or areas requiring further investigation.]
 
-[SIDECAR_FOLD]`;
+${marker}`;
   }
 
   return `## HEADLESS MODE INSTRUCTIONS
@@ -324,14 +345,14 @@ You are running autonomously without human interaction.
 
 1. Execute the task completely
 2. Make reasonable assumptions and document them
-3. When done, output your summary followed by [SIDECAR_FOLD]
+3. When done, output your summary followed by ${marker}
 
 Do NOT ask questions. Work independently.
 
 If you encounter a blocker you cannot resolve:
 1. Document what you tried
 2. Output partial results
-3. End with [SIDECAR_FOLD]
+3. End with ${marker}
 
 ${summaryFormat}`;
 }

package/src/session-manager.js

@@ -21,9 +21,6 @@ const SESSION_STATUS = {
 
 /** Canonical session dir name — new sessions are written here. */
 const SESSIONS_DIR = 'amicus_sessions';
-// DEPRECATED(amicus-shim): legacy session dir read for pre-rebrand sessions.
-// Remove in a future revision — see docs/SHIMS.md.
-const LEGACY_SESSIONS_DIR = 'sidecar_sessions';
 
 /**
  * Get the canonical session directory path for a task (used for WRITES).
@@ -50,19 +47,16 @@ function getSessionDir(projectDir, taskId) {
 }
 
 /**
- * Resolve an EXISTING session dir for reads: prefer amicus, fall back to legacy.
- * Backward-compat shim so pre-rebrand `.claude/sidecar_sessions/` stay visible.
+ * Resolve an EXISTING session dir for reads. Currently identical to
+ * getSessionDir (kept as a distinct name for call-site clarity/history —
+ * pre-#19 it also probed a legacy session-dir root).
  *
  * @param {string} projectDir - Project directory path
  * @param {string} taskId - Sidecar task ID
- * @returns {string} Path to the resolved session directory (defaults to the new path)
+ * @returns {string} Path to the resolved session directory
  */
 function resolveExistingSessionDir(projectDir, taskId) {
-  const current = getSessionDir(projectDir, taskId);
-  if (fs.existsSync(current)) { return current; }
-  const legacy = path.join(projectDir, '.claude', LEGACY_SESSIONS_DIR, taskId);
-  if (fs.existsSync(legacy)) { return legacy; }
-  return current; // default to the new path
+  return getSessionDir(projectDir, taskId);
 }
 
 /**
@@ -299,7 +293,7 @@ function createSubagentSession(projectDir, parentTaskId, subagentId, metadata) {
   };
 
   // Write metadata
-  fs.writeFileSync(
+  writeFileAtomic(
     path.join(subagentDir, 'metadata.json'),
     JSON.stringify(subagentMetadata, null, 2),
     { mode: 0o600 }
@@ -329,7 +323,7 @@ function updateSubagentSession(projectDir, parentTaskId, subagentId, updates) {
 
   const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
   const updated = { ...metadata, ...updates };
-  fs.writeFileSync(metadataPath, JSON.stringify(updated, null, 2), { mode: 0o600 });
+  writeFileAtomic(metadataPath, JSON.stringify(updated, null, 2), { mode: 0o600 });
 }
 
 /**
@@ -418,7 +412,6 @@ module.exports = {
   getSessionDir,
   resolveExistingSessionDir,
   SESSIONS_DIR,
-  LEGACY_SESSIONS_DIR,
   SESSION_STATUS,
   // Sub-agent functions
   getSubagentDir,

package/src/sidecar/continue.js

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 
+const { writeFileAtomic } = require('../utils/atomic-write');
 const { generateTaskId, runInteractive, buildMcpConfig } = require('./start');
 const {
   SessionPaths,
@@ -16,6 +17,7 @@ const {
 const { acquireLock, releaseLock } = require('../utils/session-lock');
 const { runHeadless } = require('../headless');
 const { buildPrompts } = require('../prompt-builder');
+const { generateFoldNonce } = require('../utils/fold-marker');
 const { logger } = require('../utils/logger');
 
 /** Load previous session data (metadata, summary, conversation) */
@@ -103,7 +105,7 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
     continuesFrom: oldTaskId
   };
 
-  fs.writeFileSync(SessionPaths.metadataFile(sessionDir), JSON.stringify(metadata, null, 2));
+  writeFileAtomic(SessionPaths.metadataFile(sessionDir), JSON.stringify(metadata, null, 2));
 
   return sessionDir;
 }
@@ -151,9 +153,14 @@ async function continueSidecar(options) {
   // Inherit agent from previous session if not specified
   const effectiveAgent = agent || oldMetadata.agent || 'Build';
 
+  // 15b.3: a continuation builds a FRESH prompt (unlike resume, which re-sends
+  // the original), so it gets a fresh nonce too — the old session's nonce has
+  // no bearing on this new one.
+  const foldNonce = generateFoldNonce();
+
   // Build system prompt and user message
   const { system: systemPrompt, userMessage } = buildPrompts(
-    briefing, fullContext, project, headless, effectiveAgent, 'normal', client
+    briefing, fullContext, project, headless, effectiveAgent, 'normal', client, foldNonce
   );
 
   // Use provided task ID (from MCP server) or generate a new one
@@ -180,7 +187,7 @@ async function continueSidecar(options) {
     if (headless) {
       result = await runHeadless(
         model, systemPrompt, userMessage, newTaskId, project,
-        timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers }
+        timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers, nonce: foldNonce }
       );
       summary = result.summary ||
         '## Sidecar Results: No Output\n\nContinued session completed without summary.';
@@ -191,7 +198,7 @@ async function continueSidecar(options) {
       logger.info('Launching interactive continue', { taskId: newTaskId, model });
       result = await runInteractive(
         model, systemPrompt, userMessage, newTaskId, project,
-        { agent: effectiveAgent, mcp: mcpServers }
+        { agent: effectiveAgent, mcp: mcpServers, foldNonce }
       );
       summary = result.summary || '';
       if (result.error) { logger.error('Interactive continue error', { taskId: newTaskId, error: result.error }); }
@@ -220,7 +227,7 @@ async function continueSidecar(options) {
     meta.status = 'error';
     meta.reason = (result && result.error) ? String(result.error) : 'Incomplete';
     meta.completedAt = new Date().toISOString();
-    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
     logger.error('Continuation completed with error', { taskId: newTaskId, error: meta.reason });
   } else {
     finalizeSession(sessionDir, summary, project, meta, { status: terminal.status });

package/src/sidecar/conversation-mirror.js

@@ -24,6 +24,7 @@ function createMirrorState() {
     toolCalls: [],              // [{id,name,input}] — capped at MAX_TOOL_CALLS (most-recent-N)
     seenToolCallIds: new Set(), // stable dedup identity for tool calls (survives the cap)
     seenToolResultIds: new Set(),
+    pendingToolCalls: new Map(), // id -> {id,name,firstSeenAt} — tool_use with no tool_result yet (B53)
     receivingReported: false,
     output: '',                 // accumulated assistant text
     seenReasoningParts: new Map(), // partId -> last captured reasoning length
@@ -32,6 +33,19 @@ function createMirrorState() {
   };
 }
 
+/**
+ * Unresolved tool calls: tool_use ids seen with no matching tool_result yet
+ * (matched by `part.tool_use_id`). Used by the headless poll loop's stall
+ * detector (B53) to fail fast on a wedged tool call instead of burning the
+ * full timeout. Returns a fresh array each call; `state.pendingToolCalls`
+ * is the live source of truth.
+ * @param {object} state from createMirrorState()
+ * @returns {Array<{id:string,name:string,firstSeenAt:string}>}
+ */
+function getPendingToolCalls(state) {
+  return Array.from(state.pendingToolCalls.values());
+}
+
 /**
  * @param {Array} messages getMessages() snapshot
  * @param {object} state from createMirrorState() (mutated + returned)
@@ -94,6 +108,10 @@ function mirrorMessages(messages, state, opts = {}) {
         if (state.toolCalls.length > MAX_TOOL_CALLS) { state.toolCalls.shift(); }
         appendLines.push({ role: 'assistant', type: 'tool_use', toolCall, timestamp: now() });
 
+        // Track as pending until a matching tool_result arrives (B53 stall detector).
+        // firstSeenAt is captured once here — never touched again for this id.
+        state.pendingToolCalls.set(part.id, { id: part.id, name: part.name, firstSeenAt: now() });
+
         // Update progress on tool_use detection
         progressUpdates.push({
           stage: 'receiving',
@@ -117,6 +135,9 @@ function mirrorMessages(messages, state, opts = {}) {
             timestamp: now(),
           });
         }
+        // Resolved: clear the pending entry regardless of dedup state above (a
+        // result seen again for an id already cleared is a harmless no-op delete).
+        if (part.tool_use_id) { state.pendingToolCalls.delete(part.tool_use_id); }
       } else if (part.type === 'reasoning' && part.text) {
         // Some providers (e.g. Gemini 3.x on the direct Google path) return the
         // answer as a reasoning part with no separate text part. Accumulate it in a
@@ -178,4 +199,4 @@ function logMessage(conversationPath, message) {
   fs.appendFileSync(conversationPath, JSON.stringify(message) + '\n', { mode: 0o600 });
 }
 
-module.exports = { createMirrorState, mirrorMessages, logMessage };
+module.exports = { createMirrorState, mirrorMessages, logMessage, getPendingToolCalls };

package/src/sidecar/crash-handler.js

@@ -9,6 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const { SessionPaths } = require('./session-utils');
+const { writeFileAtomic } = require('../utils/atomic-write');
 
 /**
  * Create a crash handler that updates session metadata on error.
@@ -38,7 +39,7 @@ function installCrashHandler(taskId, project) {
       metadata.reason = err.message;
       metadata.errorAt = new Date().toISOString();
 
-      fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+      writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
 
       // Delete session lock if it exists
       const lockPath = path.join(sessionDir, 'session.lock');

package/src/sidecar/fanout-leg.js

@@ -10,6 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { logger } = require('../utils/logger');
+const { writeFileAtomic } = require('../utils/atomic-write');
 
 /** Map a runHeadless result to a leg metadata status. */
 function legStatusFromResult(result) {
@@ -30,7 +31,7 @@ function writeLegPatch(legDir, patch) {
     delete defined.status;
   }
   const merged = { ...meta, ...defined };
-  fs.writeFileSync(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
   return merged;
 }
 
@@ -38,7 +39,7 @@ function writeLegPatch(legDir, patch) {
  * 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 }) {
+async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
@@ -81,7 +82,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 }
+      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce }
     );
   } catch (err) {
     result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId: legId };
@@ -93,6 +94,14 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
   const summary = result.summary || null;
   const { resolveUsage } = require('../utils/pricing');
   const usage = result && result.usage ? resolveUsage({ model: leg.model, usageTotals: result.usage }) : null;
+  // B24: cross-run spend ledger — one row per leg (mirrors start.js's single-run
+  // append). Best-effort; never let ledger bookkeeping affect the leg's own result.
+  if (usage) {
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      appendSpend({ taskId: legId, waveId, model: leg.model, mode: 'leg', usage });
+    } catch { /* best-effort */ }
+  }
   // If setup threw before the session dir existed, there is nothing on disk to
   // finalize — still resolve to an error run document so the wave aggregates.
   const legPatch = {

package/src/sidecar/fanout.js

@@ -15,6 +15,7 @@ const path = require('path');
 const { logger } = require('../utils/logger');
 const { runLeg } = require('./fanout-leg');
 const { ERROR_CODES } = require('../utils/error-doc');
+const { writeFileAtomic } = require('../utils/atomic-write');
 
 /** Default max legs per wave (env-overridable). */
 const DEFAULT_MAX_LEGS = 10;
@@ -86,15 +87,24 @@ async function validateFanoutModels(modelsArg, opts = {}) {
   return { legs };
 }
 
-/** Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote). */
+/**
+ * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
+ * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
+ * to a softer status (same precedence rule as writeLegPatch — a signal/abort
+ * marker must never lose a write race against an in-flight init/finalize).
+ */
 function writeWaveMetadata(waveDir, patch) {
   const metaPath = path.join(waveDir, 'metadata.json');
   let existing = {};
   if (fs.existsSync(metaPath)) {
     try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
   }
-  const merged = { ...existing, ...patch };
-  fs.writeFileSync(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  const safePatch = { ...patch };
+  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
+    delete safePatch.status;
+  }
+  const merged = { ...existing, ...safePatch };
+  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
   return merged;
 }
 
@@ -114,6 +124,7 @@ async function runFanout(options) {
   const { createWaveHeartbeat } = require('./wave-progress');
   const { buildContext } = require('./context-builder');
   const { buildPrompts } = require('../prompt-builder');
+  const { generateFoldNonce } = require('../utils/fold-marker');
   const { installSignalAbort, markAborted } = require('../utils/session-abort');
   const { getSessionDir } = require('../session-manager');
 
@@ -188,8 +199,12 @@ async function runFanout(options) {
         coworkProcess: options.coworkProcess,
       })
     : '[Context excluded by caller - briefing is self-contained]';
+  // 15b.3: ONE nonce for the whole wave — every leg shares the SAME prompt
+  // (built once, above), so every leg's model is instructed with the same
+  // nonce, and runLeg threads it to each leg's own runHeadless detector.
+  const foldNonce = generateFoldNonce();
   const { system: systemPrompt, userMessage } = buildPrompts(
-    options.prompt, context, project, true, options.agent || 'build', options.summaryLength, options.client
+    options.prompt, context, project, true, options.agent || 'build', options.summaryLength, options.client, foldNonce
   );
 
   // 4. One shared OpenCode server
@@ -220,7 +235,10 @@ async function runFanout(options) {
       logger.warn('Signal received — aborting wave', { waveId, signal });
       markAborted(waveDir, signal);
       for (const dir of legDirs) { markAborted(dir, signal); }
-      try { server.close(); } catch { /* best-effort */ }
+      // close() is async (B06 escalation); this handler stays sync, so
+      // fire-and-forget with a rejection guard. The 10s exit watchdog below
+      // comfortably outlives the ~2s escalation grace inside close().
+      try { server.close().catch(() => {}); } catch { /* best-effort */ }
       const { armExitWatchdog } = require('../utils/lifecycle');
       armExitWatchdog(code, 10000, { log: (m, meta) => logger.debug(m, meta) });
     },
@@ -241,11 +259,12 @@ 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,
     })));
   } finally {
     heartbeat.stop();
     uninstallSignals();
-    try { server.close(); } catch { /* already closed on signal */ }
+    try { await server.close(); } catch { /* already closed on signal */ }
   }
 
   // 7. Aggregate, persist (atomic: tmp + rename), finalize, emit
@@ -255,9 +274,7 @@ async function runFanout(options) {
     status: signalled ? 'aborted' : null,
   });
   const wavePath = path.join(waveDir, 'wave.json');
-  const waveTmp = `${wavePath}.tmp`;
-  fs.writeFileSync(waveTmp, JSON.stringify(wave, null, 2), { mode: 0o600 });
-  fs.renameSync(waveTmp, wavePath);
+  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
   writeWaveMetadata(waveDir, { status: wave.status, completedAt });
   emit(wave);
   const exitCode = signalled
@@ -268,5 +285,5 @@ async function runFanout(options) {
 
 module.exports = {
   parseModelsList, deriveLegIds, validateFanoutModels, DEFAULT_MAX_LEGS,
-  runFanout,
+  runFanout, writeWaveMetadata,
 };

package/src/sidecar/interactive-process.js

@@ -6,7 +6,6 @@
 const path = require('path');
 
 const { logger } = require('../utils/logger');
-const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 
 /** Resolve the Electron binary path ONLY when the exe actually exists on disk.
  *  #54: path.txt surviving (require('electron') resolving) is NOT enough — a
@@ -31,13 +30,12 @@ function checkElectronAvailable() {
 
 /** Build environment variables for Electron process */
 function buildElectronEnv(taskId, model, project, nodeModulesBin, existingPath, options = {}) {
-  const { agent, isResume, conversation, mcp, client, windowPosition, sessionDirectory } = options;
+  const { client, windowPosition, sessionDirectory, foldNonce } = options;
   const env = {
     ...process.env,
     PATH: `${nodeModulesBin}${path.delimiter}${existingPath}`,
     AMICUS_TASK_ID: taskId,
-    AMICUS_MODEL: model,
-    SIDECAR_PROJECT: project
+    AMICUS_MODEL: model
   };
 
   if (client) { env.AMICUS_CLIENT = client; }
@@ -46,19 +44,10 @@ function buildElectronEnv(taskId, model, project, nodeModulesBin, existingPath,
   // Web-UI route from THIS, not a fresh base64url(CWD) guess, so follow-up
   // prompts resolve the session when process cwd != --cwd.
   if (sessionDirectory) { env.AMICUS_SESSION_DIRECTORY = sessionDirectory; }
-
-  if (agent) {
-    const agentConfig = mapAgentToOpenCode(agent);
-    env.SIDECAR_AGENT = agentConfig.agent;
-    if (agentConfig.permissions) { env.SIDECAR_PERMISSIONS = agentConfig.permissions; }
-  }
-
-  if (isResume) {
-    env.SIDECAR_RESUME = 'true';
-    if (conversation) { env.SIDECAR_CONVERSATION = conversation; }
-  }
-
-  if (mcp) { env.SIDECAR_MCP_CONFIG = JSON.stringify(mcp); }
+  // 15b.3: per-run fold nonce (#BL-7 residual) — the same value baked into the
+  // system prompt's instruction (buildPrompts) so fold.js writes a marker the
+  // prompt actually asked for, not the guessable legacy bare `[SIDECAR_FOLD]`.
+  if (foldNonce) { env.AMICUS_FOLD_NONCE = foldNonce; }
 
   return env;
 }

package/src/sidecar/interactive.js

@@ -11,7 +11,6 @@ const { startOpenCodeServer } = require('./session-utils');
 const { createSession, sendPromptAsync, getMessages, abortSession } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { logger } = require('../utils/logger');
-const { getCompatEnv } = require('../utils/env-compat');
 const { startInteractiveMirror } = require('./interactive-mirror');
 const { startAbortWatch, markResultAborted, readAbortedMarker } = require('./interactive-abort');
 const { getSessionDir } = require('../session-manager');
@@ -34,7 +33,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     };
   }
 
-  const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client } = options;
+  const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client, foldNonce } = options;
 
   // F6c: mirror headless's lifecycle stages (best-effort — a write failure must
   // never break the GUI) so the heartbeat/status never read "Starting up...".
@@ -101,7 +100,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     }
     logger.debug('Interactive session ready', { sessionId, isResume: !!isResume });
   } catch (error) {
-    server.close();
+    server.close().catch(() => {});
     return {
       summary: '', completed: false, timedOut: false, taskId,
       error: `Session setup failed: ${error.message}`
@@ -157,12 +156,12 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     const existingPath = process.env.PATH || '';
     const env = buildElectronEnv(
       taskId, model, project, nodeModulesBin, existingPath,
-      { agent, isResume, conversation, mcp, client, sessionDirectory }
+      { agent, isResume, conversation, mcp, client, sessionDirectory, foldNonce }
     );
     env.AMICUS_OPENCODE_PORT = serverPort;
     env.AMICUS_SESSION_ID = sessionId;
 
-    const debugPort = getCompatEnv('DEBUG_PORT') || '9222';
+    const debugPort = process.env.AMICUS_DEBUG_PORT || '9222';
     logger.debug('Launching Electron', { taskId, model, debugPort, serverPort, sessionId });
 
     electronProcess = spawn(electronPath, [
@@ -200,7 +199,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
         const { usage } = await mirror.stop();
         if (usage) { result.usage = usage; }
       } catch (err) { logger.debug('mirror stop failed', { error: err.message }); }
-      server.close();
+      try { await server.close(); } catch { /* best-effort */ }
       logger.debug('OpenCode server closed after Electron exit');
       result.opencodeSessionId = sessionId;
       resolve(result);

package/src/sidecar/models.js

@@ -47,15 +47,29 @@ function aliasMarks() {
   return map;
 }
 
+/**
+ * #13: a one-line honest memo when the last refresh attempt on record failed
+ * AFTER the data currently being shown was fetched — i.e. the cache is stale
+ * because refreshing keeps failing, not just because nobody's refreshed lately.
+ * @returns {string|null}
+ */
+function staleMemo(fetchedAt, lastRefreshAttempt, lastRefreshError) {
+  if (!lastRefreshAttempt || !lastRefreshError) { return null; }
+  if (fetchedAt && lastRefreshAttempt <= fetchedAt) { return null; }
+  const attemptWhen = new Date(lastRefreshAttempt).toISOString();
+  const fetchedWhen = fetchedAt ? new Date(fetchedAt).toISOString() : 'never';
+  return `⚠ catalog may be stale: last refresh attempt failed ${attemptWhen} (${lastRefreshError}); showing data fetched ${fetchedWhen}`;
+}
+
 async function runList(args) {
-  const { models, fetchedAt } = await getCatalogInfo();
+  const { models, fetchedAt, lastRefreshAttempt, lastRefreshError } = await getCatalogInfo();
   const q = typeof args.search === 'string' ? args.search.toLowerCase() : null;
   const filtered = q
     ? models.filter(m => m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q))
     : models;
   if (args.json) {
     process.stdout.write(JSON.stringify(buildCatalogDoc({
-      models: filtered, fetchedAt, search: q
+      models: filtered, fetchedAt, search: q, lastRefreshAttempt, lastRefreshError
     }), null, 2) + '\n');
     return 0;
   }
@@ -71,16 +85,31 @@ async function runList(args) {
   if (filtered.length === 0 && models.length === 0) {
     process.stdout.write('Catalog unavailable (offline or first run) — try: amicus models --refresh\n');
   }
+  const memo = staleMemo(fetchedAt, lastRefreshAttempt, lastRefreshError);
+  if (memo) { process.stdout.write(memo + '\n'); }
   return 0;
 }
 
 async function runRefresh(args) {
   const models = await refreshCatalog();
+  const { fetchedAt, lastRefreshAttempt, lastRefreshError } = await getCatalogInfo({ maxAgeMs: Number.POSITIVE_INFINITY });
   if (args.json) {
     process.stdout.write(JSON.stringify(buildCatalogDoc({
-      models, fetchedAt: models.length > 0 ? Date.now() : null, refreshed: true
+      models, fetchedAt, refreshed: true, lastRefreshAttempt, lastRefreshError
     }), null, 2) + '\n');
-    return 0;
+    return models.length === 0 && !fetchedAt ? 1 : 0;
+  }
+  if (models.length === 0 && lastRefreshError) {
+    // Honest failure report — never claim "Refreshed catalog: 0 models" when
+    // the refresh actually failed and an old (or no) cache was retained.
+    if (fetchedAt) {
+      const when = new Date(fetchedAt).toISOString();
+      process.stdout.write(`refresh failed (${lastRefreshError}); keeping catalog from ${when}\n`);
+      process.stdout.write(`Cache: ${catalogPath()}\n`);
+      return 0; // stale-but-served: a warning, not a command failure
+    }
+    process.stdout.write(`refresh failed (${lastRefreshError}); no cache available\n`);
+    return 1; // no cache at all: a real failure
   }
   process.stdout.write(`Refreshed catalog: ${models.length} models.\n`);
   process.stdout.write(`Cache: ${catalogPath()}\n`);

package/src/sidecar/progress.js

@@ -10,6 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { latestAssistantPreview } = require('./progress-fields');
+const { writeFileAtomic } = require('../utils/atomic-write');
 
 /** Lifecycle stage labels */
 const STAGE_LABELS = {
@@ -117,7 +118,7 @@ function writeProgress(sessionDir, stage, extra = {}) {
     updatedAt: new Date().toISOString(),
     ...extra
   };
-  fs.writeFileSync(progressPath, JSON.stringify(data), { mode: 0o600 });
+  writeFileAtomic(progressPath, JSON.stringify(data), { mode: 0o600 });
 }
 
 /**