amicus 1.9.1 → 2.1.0

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 });
 }
 
 /**

package/src/sidecar/read.js

@@ -8,7 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const { safeSessionDir, TASK_ID_PATTERN } = require('../utils/validators');
-const { SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('../session-manager');
+const { SESSIONS_DIR } = require('../session-manager');
 const { fenceSidecarOutput } = require('../utils/untrusted-fence');
 
 /**
@@ -31,18 +31,16 @@ function formatAge(dateStr) {
 }
 
 /**
- * Enumerate sessions across canonical + legacy roots (dedup, amicus wins).
+ * Enumerate sessions under the canonical amicus_sessions root.
  * @param {string} project
  * @param {{status?: string}} [opts] - status filter ('running', etc.); omit/'all' for all
  * @returns {Array<{id, model, status, agent, briefing, createdAt}>}
  */
 function enumerateSessions(project, opts = {}) {
-  const roots = [SESSIONS_DIR, LEGACY_SESSIONS_DIR]
-    .map(d => path.join(project, '.claude', d))
-    .filter(fs.existsSync);
+  const root = path.join(project, '.claude', SESSIONS_DIR);
 
   const byId = new Map();
-  for (const root of roots) {
+  if (fs.existsSync(root)) {
     for (const d of fs.readdirSync(root)) {
       if (!TASK_ID_PATTERN.test(d)) { continue; }
       if (byId.has(d)) { continue; }

package/src/sidecar/resume.js

@@ -6,6 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 
+const { writeFileAtomic } = require('../utils/atomic-write');
 const { runInteractive, buildMcpConfig } = require('./start');
 const {
   SessionPaths,
@@ -16,6 +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 { logger } = require('../utils/logger');
 
 /** Load session metadata from session directory */
@@ -106,7 +108,7 @@ function updateSessionStatus(sessionDir, status) {
   if (status === 'running') {
     meta.resumedAt = new Date().toISOString();
   }
-  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+  writeFileAtomic(metaPath, JSON.stringify(meta, null, 2));
   return meta;
 }
 
@@ -117,7 +119,7 @@ function updateSessionStatus(sessionDir, status) {
 async function resumeSidecar(options) {
   const {
     taskId, project = process.cwd(), headless = false, timeout = 15,
-    mcp, mcpConfig, client, noMcp, excludeMcp
+    mcp, mcpConfig, client, noMcp, excludeMcp, json = false
   } = options;
 
   // Resume operates on an EXISTING session — resolve dual-dir (amicus, then legacy).
@@ -159,6 +161,18 @@ async function resumeSidecar(options) {
       logger.warn('Files changed since last activity', { taskId, changedFileCount: drift.changedFiles.length });
     }
 
+    // 15b.3: resume re-sends the ORIGINAL prompt text verbatim (unlike
+    // continue, which builds a fresh one) — that prompt already instructed
+    // the model with the nonce baked in at the initial start/continue time.
+    // Recover it from the saved text so the detector agrees with what the
+    // model was actually told. A session saved before 15b.3 shipped (or any
+    // prompt that somehow lost its marker instruction) has no nonce to
+    // recover — generate a fresh one so resume still gets nonce protection,
+    // even though the OLD prompt text won't mention it (that just means this
+    // resumed run can only complete via a non-fold-marker path, same as any
+    // other run whose prompt and detector nonce happen to mismatch).
+    const foldNonce = extractNonceFromText(systemPrompt) || generateFoldNonce();
+
     // Update metadata (get updated metadata with resumedAt)
     const updatedMetadata = updateSessionStatus(sessionDir, 'running');
 
@@ -177,10 +191,17 @@ async function resumeSidecar(options) {
 
     if (headless) {
       const userMessage = buildResumeUserMessage(metadata.briefing || '', existingConversation);
-      result = await runHeadless(
-        metadata.model, resumePrompt, userMessage,
-        taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers }
-      );
+      try {
+        result = await runHeadless(
+          metadata.model, resumePrompt, userMessage,
+          taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers, nonce: foldNonce }
+        );
+      } catch (err) {
+        if (!json) { throw err; }
+        // --json contract: stdout must always carry a parseable run doc,
+        // even when the engine throws rather than returning {error}.
+        result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId };
+      }
       summary = result.summary || '## Sidecar Results: No Output\n\nResumed session completed without summary.';
 
       if (result.timedOut) { logger.warn('Resume task timed out', { taskId }); }
@@ -196,15 +217,16 @@ async function resumeSidecar(options) {
           isResume: true,
           conversation: existingConversation,
           opencodeSessionId: metadata.opencodeSessionId,
-          mcp: mcpServers
+          mcp: mcpServers,
+          foldNonce
         }
       );
       summary = result.summary || '';
       if (result.error) { logger.error('Interactive resume error', { taskId, error: result.error }); }
     }
 
-    // Output summary
-    outputSummary(summary);
+    // Output summary (human mode only — json mode keeps stdout to the doc below)
+    if (!json) { outputSummary(summary); }
 
     // Map the run result to the canonical terminal status + exit code —
     // mirrors start.js. Explicit status preserves the interactive
@@ -216,11 +238,19 @@ async function resumeSidecar(options) {
       updatedMetadata.status = 'error';
       updatedMetadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
       updatedMetadata.completedAt = new Date().toISOString();
-      fs.writeFileSync(metaPath, JSON.stringify(updatedMetadata, null, 2), { mode: 0o600 });
+      writeFileAtomic(metaPath, JSON.stringify(updatedMetadata, null, 2), { mode: 0o600 });
       logger.error('Resume completed with error', { taskId, error: updatedMetadata.reason });
     } else {
-      finalizeSession(sessionDir, summary, project, updatedMetadata, { status: terminal.status });
+      finalizeSession(sessionDir, summary, project, updatedMetadata, { quietStdout: json, status: terminal.status });
     }
+
+    if (json) {
+      const { buildRunResult } = require('../utils/result-schema');
+      const finalMeta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      const doc = buildRunResult({ taskId, metadata: finalMeta, result, summary, sessionDir });
+      console.log(JSON.stringify(doc, null, 2));
+    }
+
     return terminal.exitCode; // finally below still releases the lock first
   } finally {
     if (heartbeat) { heartbeat.stop(); }

package/src/sidecar/session-finalize.js

@@ -42,6 +42,7 @@ function finalizeHeadlessResult(sessionDir, result, project, metadata) {
   const fs = require('fs');
   const path = require('path');
   const { finalizeSession, SessionPaths } = require('./session-utils');
+  const { writeFileAtomic } = require('../utils/atomic-write');
 
   const terminal = resolveTerminalState(result);
   if (terminal.status === 'error') {
@@ -51,7 +52,7 @@ function finalizeHeadlessResult(sessionDir, result, project, metadata) {
     metadata.status = 'error';
     metadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
     metadata.completedAt = new Date().toISOString();
-    fs.writeFileSync(
+    writeFileAtomic(
       path.join(sessionDir, 'metadata.json'),
       JSON.stringify(metadata, null, 2),
       { mode: 0o600 }

package/src/sidecar/session-utils.js

@@ -9,6 +9,11 @@ const path = require('path');
 const { detectConflicts, formatConflictWarning } = require('../conflict');
 const { logger } = require('../utils/logger');
 const { fenceSidecarOutput } = require('../utils/untrusted-fence');
+const { writeFileAtomic } = require('../utils/atomic-write');
+// isProcessAlive/checkSessionLiveness live in utils/abort-coordinator.js
+// (shared EPERM-aware liveness classification with isAlive); re-exported
+// below for backward-compatible imports.
+const { isAlive: isProcessAlive, checkSessionLiveness } = require('../utils/abort-coordinator');
 const {
   SESSIONS_DIR,
   getSessionDir,
@@ -31,9 +36,8 @@ const SessionPaths = {
   },
 
   /**
-   * Resolve an EXISTING session directory for READS: prefer amicus, fall back
-   * to legacy `sidecar_sessions` (backward-compat shim). Use this when
-   * resuming/continuing an existing session so pre-rebrand sessions are found.
+   * Resolve an EXISTING session directory for READS. Use this when
+   * resuming/continuing an existing session.
    */
   resolveSessionDir(project, taskId) {
     return resolveExistingSessionDir(project, taskId);
@@ -100,7 +104,7 @@ function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
   const hasSummary = typeof summary === 'string' && summary.trim().length > 0;
   metadata.status = opts.status || (hasSummary ? 'complete' : 'error');
   metadata.completedAt = new Date().toISOString();
-  fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
 
   logger.info('Session finalized', { taskId: metadata.taskId, status: metadata.status });
 }
@@ -248,43 +252,17 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
 
   const ready = await waitForServer(client, checkHealth);
   if (!ready) {
-    server.close();
+    // Fire-and-forget: today close() is sync (Promise.resolve wraps a
+    // non-promise harmlessly); once close() becomes async (bounded
+    // kill-escalation poll) this guard prevents an unhandled rejection
+    // from racing the throw below.
+    Promise.resolve(server.close()).catch(() => {});
     throw new Error('OpenCode server failed to become ready');
   }
 
   return { client, server };
 }
 
-/**
- * Check if a process with the given PID is still alive.
- * @param {number|null} pid
- * @returns {boolean}
- */
-function isProcessAlive(pid) {
-  if (!pid) { return false; }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a session's processes are alive.
- * @param {Object} metadata - Session metadata with pid and goPid
- * @returns {'alive'|'server-dead'|'dead'}
- */
-function checkSessionLiveness(metadata) {
-  if (!metadata) { return 'dead'; }
-  const nodeAlive = isProcessAlive(metadata.pid);
-  const goAlive = isProcessAlive(metadata.goPid);
-
-  if (nodeAlive && goAlive) { return 'alive'; }
-  if (nodeAlive && !goAlive) { return 'server-dead'; }
-  return 'dead';
-}
-
 module.exports = {
   HEARTBEAT_INTERVAL,
   SessionPaths,

package/src/sidecar/setup-window.js

@@ -1,7 +1,7 @@
 /**
  * Setup Window Launcher
  *
- * Spawns the Electron window in setup mode (SIDECAR_MODE=setup)
+ * Spawns the Electron window in setup mode (AMICUS_MODE=setup)
  * for API key configuration. Waits for the window to close and
  * returns whether setup completed successfully.
  */
@@ -11,7 +11,6 @@ const path = require('path');
 const { logger } = require('../utils/logger');
 const { getElectronPath } = require('./interactive-process');
 const { ensureElectron } = require('./electron-ensure');
-const { getCompatEnv } = require('../utils/env-compat');
 
 /**
  * Launch the Electron setup window for API key entry.
@@ -35,7 +34,7 @@ async function launchSetupWindow() {
       AMICUS_MODE: 'setup'
     };
 
-    const debugPort = getCompatEnv('DEBUG_PORT');
+    const debugPort = process.env.AMICUS_DEBUG_PORT;
     const args = debugPort
       ? [`--remote-debugging-port=${debugPort}`, mainPath]
       : [mainPath];

package/src/sidecar/start.js

@@ -6,6 +6,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 
+const { writeFileAtomic } = require('../utils/atomic-write');
 const { buildContext } = require('./context-builder');
 const {
   SessionPaths,
@@ -25,6 +26,7 @@ const { loadMcpConfig, parseMcpSpec } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { discoverParentMcps } = require('../utils/mcp-discovery');
 const { stripSelfMcpEntries } = require('../utils/mcp-self-identity');
+const { generateFoldNonce } = require('../utils/fold-marker');
 
 /** Generate a unique 8-character hex task ID */
 function generateTaskId() {
@@ -66,7 +68,7 @@ function createSessionMetadata(taskId, project, options) {
     createdAt: existing.createdAt || new Date().toISOString()
   };
 
-  fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
 
   return sessionDir;
 }
@@ -163,6 +165,12 @@ async function startSidecar(options) {
   });
   const taskId = options.taskId || generateTaskId();
   const reasoning = thinking ? { effort: thinking } : undefined;
+  // 15b.3: one nonce per run, generated BEFORE prompt construction so the
+  // SAME value can be baked into the prompt's instruction (buildPrompts) and
+  // handed to the detector (runHeadless.options.nonce / the GUI fold writer
+  // via env). Harmless to generate even for the interactive path — buildPrompts
+  // only consumes it in headless mode.
+  const foldNonce = generateFoldNonce();
 
   logger.info('Starting task', { taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive' });
 
@@ -170,7 +178,7 @@ async function startSidecar(options) {
     ? buildContext(effectiveProject, effectiveSession, { contextTurns, contextSince, contextMaxTokens, sessionDir, client, coworkProcess })
     : '[Context excluded by caller - briefing is self-contained]';
   const { system: systemPrompt, userMessage } = buildPrompts(
-    effectivePrompt, context, effectiveProject, effectiveHeadless, agent, summaryLength, client
+    effectivePrompt, context, effectiveProject, effectiveHeadless, agent, summaryLength, client, foldNonce
   );
 
   const sessDir = createSessionMetadata(taskId, effectiveProject, {
@@ -188,7 +196,8 @@ async function startSidecar(options) {
       try {
         result = await runHeadless(
           model, systemPrompt, userMessage, taskId, effectiveProject,
-          timeout * 60 * 1000, agent || 'build', { mcp: mcpServers, summaryLength, reasoning, port: opencodePort }
+          timeout * 60 * 1000, agent || 'build',
+          { mcp: mcpServers, summaryLength, reasoning, port: opencodePort, nonce: foldNonce }
         );
       } catch (err) {
         if (!json) { throw err; }
@@ -204,7 +213,7 @@ async function startSidecar(options) {
       logger.info('Launching interactive sidecar', { taskId, model, agent: effectiveAgent });
       result = await runInteractive(
         model, systemPrompt, userMessage, taskId, effectiveProject,
-        { agent, mcp: mcpServers, reasoning, client, windowPosition: position }
+        { agent, mcp: mcpServers, reasoning, client, windowPosition: position, foldNonce }
       );
       summary = result.summary || '';
       if (result.error) { logger.error('Interactive task error', { taskId, error: result.error }); }
@@ -221,7 +230,7 @@ async function startSidecar(options) {
   // Persist OpenCode session ID for resume capability
   if (result && result.opencodeSessionId) {
     meta.opencodeSessionId = result.opencodeSessionId;
-    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
   }
 
   // Map the run result to a definitive terminal status + exit code (single source of truth).
@@ -231,7 +240,7 @@ async function startSidecar(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('Session completed with error', { taskId, error: meta.reason });
   } else {
     // complete / timed-out / aborted: persist the (possibly partial) summary with the correct status.
@@ -243,7 +252,13 @@ async function startSidecar(options) {
   if (runUsage) {
     const m = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
     m.usage = runUsage;
-    fs.writeFileSync(metaPath, JSON.stringify(m, null, 2), { mode: 0o600 });
+    writeFileAtomic(metaPath, JSON.stringify(m, null, 2), { mode: 0o600 });
+    // B24: cross-run spend ledger. Best-effort — appendSpend never throws, but
+    // this run's own success must never hinge on ledger bookkeeping either way.
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      appendSpend({ taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive', usage: runUsage });
+    } catch { /* best-effort */ }
   }
 
   if (json) {

package/src/utils/abort-coordinator.js

@@ -54,18 +54,36 @@ function killPidBestEffort(pid, kill = process.kill.bind(process)) {
   }
 }
 
+/** SIGKILL a pid, swallowing ESRCH. @returns {boolean} signal was sent */
+function killPidHard(pid, kill = process.kill.bind(process)) {
+  if (!pid) { return false; }
+  try { kill(pid, 'SIGKILL'); return true; } catch (err) {
+    if (err.code !== 'ESRCH') {
+      logger.warn('Failed to force-kill process', { pid, error: err.message });
+    }
+    return false;
+  }
+}
+
 /**
  * Wait up to graceMs for the pids to exit on their own (marker-honoring
  * teardown), then SIGTERM any survivor. Early-exits as soon as every target
  * is gone, so a process that honors the marker in ~2s never sees a signal.
  *
+ * Opt-in escalation (B06): pass `escalate` to additionally wait up to
+ * `escalate.killGraceMs` after the SIGTERM for the survivor(s) to exit, then
+ * SIGKILL anyone still alive. Same REF'd poll cadence (`pollMs`) as the TERM
+ * tier. A pid that was already dead at entry, or that exits during the TERM
+ * grace window, is never escalated — escalation only applies to the set that
+ * was actually SIGTERM'd and remained alive.
+ *
  * NOTE: the poll timer is deliberately REF'D. The CLI awaits this call and
  * must stay alive through the grace window; callers that must not block
  * (MCP handler) fire-and-forget the returned promise instead.
  *
  * @param {number|null|Array<number|null>} pids
- * @param {{graceMs?:number, pollMs?:number, deps?:{kill?:Function, sleep?:Function}}} [opts]
- * @returns {Promise<{killed:number[], exited:number[]}>}
+ * @param {{graceMs?:number, pollMs?:number, escalate?:{killGraceMs?:number}, deps?:{kill?:Function, sleep?:Function}}} [opts]
+ * @returns {Promise<{killed:number[], exited:number[], escalated:number[]}>}
  */
 async function waitThenKill(pids, opts = {}) {
   const graceMs = opts.graceMs !== undefined ? opts.graceMs : abortGraceMs();
@@ -82,10 +100,42 @@ async function waitThenKill(pids, opts = {}) {
     remaining = remaining.filter((pid) => isAlive(pid, kill));
   }
   const killed = remaining.filter((pid) => killPidBestEffort(pid, kill));
-  return {
-    killed,
-    exited: targets.filter((pid) => !remaining.includes(pid)),
-  };
+  const exited = targets.filter((pid) => !remaining.includes(pid));
+
+  let escalated = [];
+  if (opts.escalate && killed.length > 0) {
+    const killGraceMs = opts.escalate.killGraceMs !== undefined ? opts.escalate.killGraceMs : 2000;
+    const killDeadline = Date.now() + killGraceMs;
+    let stillAlive = killed.filter((pid) => isAlive(pid, kill));
+    while (stillAlive.length > 0 && Date.now() < killDeadline) {
+      await sleep(pollMs);
+      stillAlive = stillAlive.filter((pid) => isAlive(pid, kill));
+    }
+    // Anyone SIGTERM'd that isn't in the final stillAlive set exited on its
+    // own during the kill-grace window; anyone left gets SIGKILL'd here.
+    escalated = stillAlive.filter((pid) => killPidHard(pid, kill));
+    for (const pid of killed) { exited.push(pid); }
+  }
+
+  return opts.escalate ? { killed, exited, escalated } : { killed, exited };
+}
+
+/**
+ * Check if a session's Node/Go process pair is alive. Thin wrapper over
+ * isAlive — kept here (not sidecar/session-utils.js) so both liveness
+ * checks share one EPERM-aware classification. session-utils.js re-exports
+ * this for backward-compatible imports.
+ * @param {Object} metadata - Session metadata with pid and goPid
+ * @returns {'alive'|'server-dead'|'dead'}
+ */
+function checkSessionLiveness(metadata) {
+  if (!metadata) { return 'dead'; }
+  const nodeAlive = isAlive(metadata.pid);
+  const goAlive = isAlive(metadata.goPid);
+
+  if (nodeAlive && goAlive) { return 'alive'; }
+  if (nodeAlive && !goAlive) { return 'server-dead'; }
+  return 'dead';
 }
 
-module.exports = { abortGraceMs, isAlive, killPidBestEffort, waitThenKill };
+module.exports = { abortGraceMs, isAlive, killPidBestEffort, killPidHard, waitThenKill, checkSessionLiveness };

package/src/utils/abort-result.js

@@ -0,0 +1,36 @@
+/**
+ * @module abort-result
+ * The abort-result document builder for `abort <taskId|--all> --json` (B21-rest).
+ * Split out of result-schema.js purely to stay under the size gate — same
+ * versioning contract (fields only ADDED within a SCHEMA_VERSION) applies here.
+ */
+
+'use strict';
+
+const { SCHEMA_VERSION } = require('./result-schema-version');
+
+/**
+ * Build an abort-result document.
+ * `ok` is true iff at least one session/leg was actually marked aborted by this
+ * call — a no-op (nothing running) is a successful call with an empty list, but
+ * 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 {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
+ */
+function buildAbortResult({ scope, taskId = null, aborted = [] }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'abort',
+    ok: aborted.length > 0 || scope === 'all',
+    scope,
+    taskId,
+    aborted,
+    count: aborted.length,
+  };
+}
+
+module.exports = { buildAbortResult };

package/src/utils/api-key-store.js

@@ -5,7 +5,6 @@
 const fs = require('fs');
 const path = require('path');
 const { validateApiKey, validateOpenRouterKey, VALIDATION_ENDPOINTS } = require('./api-key-validation');
-const { getCompatEnv } = require('./env-compat');
 
 /** Maps provider IDs to environment variable names */
 const PROVIDER_ENV_MAP = {
@@ -23,7 +22,7 @@ const LEGACY_KEY_NAMES = {
 
 /** Get the path to the .env file */
 function getEnvPath() {
-  const envDir = getCompatEnv('ENV_DIR');
+  const envDir = process.env.AMICUS_ENV_DIR;
   if (envDir) {
     const resolved = path.resolve(envDir);
     if (resolved.includes('\0')) {
@@ -32,17 +31,7 @@ function getEnvPath() {
     return path.join(resolved, '.env');
   }
   const homeDir = process.env.HOME || process.env.USERPROFILE;
-  const amicusEnvPath = path.join(homeDir, '.config', 'amicus', '.env');
-  // DEPRECATED(amicus-shim): fall back to the legacy ~/.config/sidecar/.env if it
-  // exists and the new one does not, so pre-rebrand installs keep reading/writing
-  // their existing keys. Remove in a future revision — see docs/SHIMS.md.
-  if (!fs.existsSync(amicusEnvPath)) {
-    const legacyEnvPath = path.join(homeDir, '.config', 'sidecar', '.env');
-    if (fs.existsSync(legacyEnvPath)) {
-      return legacyEnvPath;
-    }
-  }
-  return amicusEnvPath;
+  return path.join(homeDir, '.config', 'amicus', '.env');
 }
 
 /** Parse a .env file into a key-value map (comments/blanks excluded) */