amicus 1.9.0 → 2.0.0

package/src/utils/env-loader.js

@@ -16,11 +16,10 @@ const { readAuthJsonKeys } = require('./auth-json');
  * Sources (in priority order):
  * 1. process.env - already set, never overwritten
  * 2. ~/.config/amicus/.env - user-configured via `amicus setup`
- *    (DEPRECATED(amicus-shim): falls back to ~/.config/sidecar/.env if the amicus .env absent)
  * 3. ~/.local/share/opencode/auth.json - OpenCode SDK fallback
  */
 function loadCredentials() {
-  // Step 1: Load from sidecar .env file
+  // Step 1: Load from amicus .env file
   const fileEntries = loadEnvEntries();
   for (const [, envVar] of Object.entries(PROVIDER_ENV_MAP)) {
     if (!process.env[envVar]) {

package/src/utils/fold-marker.js

@@ -0,0 +1,79 @@
+/**
+ * Fold marker construction/parsing helpers — shared by prompt-builder.js
+ * (instructs the model), headless.js (writes + detects), electron/fold.js
+ * (writes), and src/sidecar/resume.js (re-derives the nonce from a saved
+ * prompt on resume). Centralized here so the marker CONTRACT lives in one
+ * place instead of being duplicated string-literal by string-literal.
+ *
+ * #BL-7 residual: the marker used to be the static string `[SIDECAR_FOLD]`,
+ * so model output that genuinely ends with a bare marker (echoing these
+ * instructions, a prior sidecar summary, or scraped content) could force a
+ * premature fold. A per-run nonce closes that gap — only the exact nonce
+ * generated for THIS run completes THIS run.
+ */
+const crypto = require('crypto');
+
+/** The fixed, public prefix. Intentionally still `[SIDECAR_FOLD` as a
+ *  substring — anything that greps for the OLD literal string still finds
+ *  the new nonced marker; it just no longer matches an ANCHORED bare-bracket
+ *  string (`[SIDECAR_FOLD]`) because a real marker now always carries a
+ *  `:<nonce>` suffix before the closing bracket. */
+const FOLD_MARKER_PREFIX = 'SIDECAR_FOLD';
+
+/** Generate a fresh per-run nonce. 16 hex chars (8 random bytes) — comfortably
+ *  above the brief's 12+ hex char floor, cheap to embed in prompts. */
+function generateFoldNonce() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Build the full marker string for a given nonce: `[SIDECAR_FOLD:<nonce>]`.
+ * @param {string} nonce
+ * @returns {string}
+ */
+function buildFoldMarker(nonce) {
+  return `[${FOLD_MARKER_PREFIX}:${nonce}]`;
+}
+
+/** Escape a string for safe embedding inside a RegExp source. */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build a RegExp that matches `buildFoldMarker(nonce)` as the FINAL
+ * non-empty line of a string (see headless.js findTrailingFoldMarker for the
+ * consuming semantics). Exported so headless.js doesn't hand-roll the same
+ * escaping logic.
+ * @param {string} nonce
+ * @returns {RegExp}
+ */
+function trailingFoldMarkerRegex(nonce) {
+  const escaped = escapeRegExp(buildFoldMarker(nonce));
+  return new RegExp(`^[^\\S\\r\\n]*${escaped}[^\\S\\r\\n]*$(?![\\s\\S]*\\S)`, 'm');
+}
+
+/**
+ * Recover the nonce embedded in a previously-built system prompt (resume.js:
+ * a resumed session re-sends the ORIGINAL prompt text — which already
+ * instructs the model with the nonce baked in at initial `start`/`continue`
+ * time — rather than building a fresh one via buildPrompts). Matches the
+ * FIRST occurrence of the marker anywhere in the text (the prompt's own
+ * instruction line), not a final-line match — this is prompt text, not
+ * model output.
+ * @param {string} text
+ * @returns {string|null} the nonce, or null if no marker is present
+ */
+function extractNonceFromText(text) {
+  if (!text) { return null; }
+  const m = new RegExp(`\\[${FOLD_MARKER_PREFIX}:([0-9a-f]+)\\]`).exec(text);
+  return m ? m[1] : null;
+}
+
+module.exports = {
+  FOLD_MARKER_PREFIX,
+  generateFoldNonce,
+  buildFoldMarker,
+  trailingFoldMarkerRegex,
+  extractNonceFromText,
+};

package/src/utils/idle-watchdog.js

@@ -9,16 +9,13 @@
  *
  * Timeout priority (highest to lowest):
  *   1. Per-mode env var (AMICUS_IDLE_TIMEOUT_HEADLESS, etc.) in minutes
- *      (legacy SIDECAR_IDLE_TIMEOUT_* still honored via env-compat shim)
- *   2. Blanket env var AMICUS_IDLE_TIMEOUT / SIDECAR_IDLE_TIMEOUT in minutes
+ *   2. Blanket env var AMICUS_IDLE_TIMEOUT in minutes
  *   3. Constructor option `timeout` in milliseconds
  *   4. Mode default (headless=15m, interactive=60m, server=30m)
  */
 
 'use strict';
 
-const { getCompatEnv } = require('./env-compat');
-
 /** @type {Object.<string, number>} Default timeouts per mode in milliseconds */
 const MODE_TIMEOUTS = {
   headless: 15 * 60 * 1000,
@@ -26,11 +23,11 @@ const MODE_TIMEOUTS = {
   server: 30 * 60 * 1000,
 };
 
-/** @type {Object.<string, string>} Per-mode env-compat suffixes */
+/** @type {Object.<string, string>} Per-mode env var names */
 const MODE_ENV_MAP = {
-  headless: 'IDLE_TIMEOUT_HEADLESS',
-  interactive: 'IDLE_TIMEOUT_INTERACTIVE',
-  server: 'IDLE_TIMEOUT_SERVER',
+  headless: 'AMICUS_IDLE_TIMEOUT_HEADLESS',
+  interactive: 'AMICUS_IDLE_TIMEOUT_INTERACTIVE',
+  server: 'AMICUS_IDLE_TIMEOUT_SERVER',
 };
 
 /**
@@ -41,16 +38,16 @@ const MODE_ENV_MAP = {
  * @returns {number} Effective timeout in ms, or Infinity if disabled
  */
 function resolveTimeout(mode, optionTimeout) {
-  const modeSuffix = MODE_ENV_MAP[mode];
-  if (modeSuffix !== undefined) {
-    const modeEnv = getCompatEnv(modeSuffix);
+  const modeEnvName = MODE_ENV_MAP[mode];
+  if (modeEnvName !== undefined) {
+    const modeEnv = process.env[modeEnvName];
     if (modeEnv !== undefined) {
       const mins = Number(modeEnv);
       return mins === 0 ? Infinity : mins * 60 * 1000;
     }
   }
 
-  const blanket = getCompatEnv('IDLE_TIMEOUT');
+  const blanket = process.env.AMICUS_IDLE_TIMEOUT;
   if (blanket !== undefined) {
     const mins = Number(blanket);
     return mins === 0 ? Infinity : mins * 60 * 1000;

package/src/utils/lifecycle.js

@@ -12,7 +12,7 @@
 // when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
 // `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
 // interactive Electron flow that must never be force-exited).
-const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor' /* local-only: no OpenCode server, no stray handles */]);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor', 'spend' /* local-only: no OpenCode server, no stray handles */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {

package/src/utils/mcp-discovery.js

@@ -139,6 +139,34 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
   return Object.keys(merged).length > 0 ? merged : null;
 }
 
+/**
+ * Resolve Claude Desktop's per-platform config directory.
+ * Mirrors the 3-way branch in src/environment.js getCoworkRoot (same
+ * APPDATA || homedir-fallback form on win32) but stops one level higher —
+ * getCoworkRoot resolves .../Claude/local-agent-mode-sessions, while this
+ * needs the parent .../Claude dir that holds claude_desktop_config.json.
+ * Kept local rather than imported to avoid depending on an internal
+ * implementation detail (stripping getCoworkRoot's trailing segment).
+ *
+ * @param {string} platform - OS platform (process.platform)
+ * @returns {string} Claude Desktop config directory
+ */
+function getClaudeDesktopConfigDir(platform) {
+  const homedir = os.homedir();
+
+  if (platform === 'darwin') {
+    return path.join(homedir, 'Library', 'Application Support', 'Claude');
+  }
+
+  if (platform === 'win32') {
+    const appdata = process.env.APPDATA || path.join(homedir, 'AppData', 'Roaming');
+    return path.join(appdata, 'Claude');
+  }
+
+  // Linux and other Unix-like systems
+  return path.join(homedir, '.config', 'Claude');
+}
+
 /**
  * Discover MCP servers from Cowork / Claude Desktop config.
  *
@@ -146,11 +174,7 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
  * @returns {object|null} MCP server configs, or null if none found
  */
 function discoverCoworkMcps(configDir) {
-  const baseDir = configDir || (
-    process.platform === 'darwin'
-      ? path.join(os.homedir(), 'Library', 'Application Support', 'Claude')
-      : path.join(os.homedir(), '.config', 'Claude')
-  );
+  const baseDir = configDir || getClaudeDesktopConfigDir(process.platform);
 
   try {
     const configPath = path.join(baseDir, 'claude_desktop_config.json');

package/src/utils/mcp-self-identity.js

@@ -5,15 +5,22 @@
  * Recursive-spawn guard. A child sidecar that inherits an MCP entry launching
  * amicus itself would spawn amicus inside amicus, forever. The shipped server
  * registers as 'amicus' (scripts/postinstall.js, .claude-plugin/plugin.json)
- * plus a deprecated 'sidecar' shim — and users can alias it under ANY name —
- * so we exclude both reserved names AND any entry whose command+args resolve
- * to an amicus MCP invocation.
+ * — and users can alias it under ANY name — so we exclude both reserved
+ * names AND any entry whose command+args resolve to an amicus MCP invocation.
+ *
+ * 'sidecar'/'claude-sidecar' are recognized for BOTH lists even though
+ * package.json's "bin" field no longer ships them as of v2.0.0 (#19): a
+ * stale pre-rebrand global install can still have them linked on a user's
+ * PATH, and a stale claude.json/MCP config can still reference the old
+ * 'sidecar' server name. Recognizing them here only ever prevents a
+ * recursive self-spawn — it never breaks a legitimately different server —
+ * so there is no cost to keeping the wider net.
  */
 
-/** Server names amicus registers itself under. */
+/** Server names amicus registers itself under (current + legacy). */
 const SELF_MCP_NAMES = Object.freeze(['amicus', 'sidecar']);
 
-/** Shipped bin aliases (package.json "bin") → ./bin/amicus.js */
+/** Bin names that resolve to ./bin/amicus.js (current package.json "bin" + legacy pre-v2.0.0 names). */
 const SELF_BIN_NAMES = new Set(['amicus', 'am', 'sidecar', 'claude-sidecar']);
 
 /**

package/src/utils/model-catalog.js

@@ -39,19 +39,52 @@ function readCache() {
   return null;
 }
 
-/** Write the cache atomically (tmp+rename). Best-effort; never throws. @param {Array} models */
-function writeCache(models) {
+/**
+ * Raw cache-doc read for refresh-outcome fields only (#13). Unlike readCache(),
+ * this does NOT require a `models` array — a fresh machine whose first refresh
+ * attempt failed writes a doc with only {lastRefreshAttempt, lastRefreshError}
+ * and no models/fetchedAt, and that outcome still needs to be readable.
+ * @returns {{lastRefreshAttempt?: number, lastRefreshError?: string}|null}
+ */
+function readCacheDocLoose() {
+  try {
+    const raw = fs.readFileSync(catalogPath(), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') { return parsed; }
+  } catch { /* missing/corrupt */ }
+  return null;
+}
+
+/** Write the cache atomically (tmp+rename). Best-effort; never throws. @param {object} doc full cache document */
+function writeCacheDoc(doc) {
   const target = catalogPath();
   const tmp = `${target}.${process.pid}.tmp`;
   try {
     fs.mkdirSync(_getConfigDir(), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(tmp, JSON.stringify({ schemaVersion: CATALOG_SCHEMA_VERSION, fetchedAt: Date.now(), models }, null, 2), { mode: 0o600 });
+    fs.writeFileSync(tmp, JSON.stringify(doc, null, 2), { mode: 0o600 });
     fs.renameSync(tmp, target);
   } catch {
     try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
   }
 }
 
+/** Write a successful fetch: fresh models/fetchedAt, outcome fields cleared. @param {Array} models */
+function writeCache(models) {
+  writeCacheDoc({ schemaVersion: CATALOG_SCHEMA_VERSION, fetchedAt: Date.now(), models });
+}
+
+/**
+ * Record a failed refresh attempt (#13): stamps lastRefreshAttempt/lastRefreshError
+ * onto the existing cache document WITHOUT touching models/fetchedAt — the good
+ * data (if any) stays byte-authoritative. With no prior cache, writes a doc that
+ * carries only the outcome fields (no models/fetchedAt to report).
+ * @param {string} reason short error-class string
+ */
+function writeRefreshFailure(reason) {
+  const existing = readCache() || { schemaVersion: CATALOG_SCHEMA_VERSION };
+  writeCacheDoc({ ...existing, lastRefreshAttempt: Date.now(), lastRefreshError: reason });
+}
+
 /**
  * Force a refresh from the provider APIs and update the cache.
  * @returns {Promise<Array<{id,name}>>} the fetched models (may be [] offline)
@@ -64,7 +97,13 @@ async function refreshCatalog() {
   // refresh — never clobber a previously-good cache with the floor (the
   // "stale cache stands" contract).
   const networkRows = (models || []).filter(m => m && typeof m.id === 'string' && !m.id.startsWith('anthropic/'));
-  if (networkRows.length === 0) { return []; }
+  if (networkRows.length === 0) {
+    const reason = (models || []).length > 0
+      ? 'floor-only: all providers returned no network rows'
+      : 'network-error: all providers unreachable';
+    writeRefreshFailure(reason);
+    return [];
+  }
   writeCache(models);
   return models;
 }
@@ -92,12 +131,21 @@ async function getCatalog(opts = {}) {
 
 /**
  * Catalog rows plus cache timestamp (for UI display).
- * @returns {Promise<{models: Array, fetchedAt: number|null}>}
+ * #13: also threads the last-refresh outcome so callers can tell "current"
+ * apart from "stale because refreshing keeps failing" — null/null when the
+ * last attempt on record succeeded (or none has happened yet).
+ * @returns {Promise<{models: Array, fetchedAt: number|null, lastRefreshAttempt: number|null, lastRefreshError: string|null}>}
  */
 async function getCatalogInfo(opts = {}) {
   const models = await getCatalog(opts);
   const cache = readCache();
-  return { models, fetchedAt: cache ? cache.fetchedAt : null };
+  const doc = readCacheDocLoose(); // outcome fields survive even a models-less doc
+  return {
+    models,
+    fetchedAt: cache ? cache.fetchedAt : null,
+    lastRefreshAttempt: (doc && doc.lastRefreshAttempt) || null,
+    lastRefreshError: (doc && doc.lastRefreshError) || null,
+  };
 }
 
 module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION };

package/src/utils/read-slice.js

@@ -0,0 +1,73 @@
+/**
+ * Byte-bounded slicing for amicus_read (15a.3 / B17).
+ *
+ * amicus_read's conversation/summary/wave-summary/metadata bodies were
+ * previously returned whole and unbounded — a large conversation.jsonl could
+ * flood the calling agent's context. This module applies a default ~50KB cap
+ * to the BODY of every response and exposes offset/limit/tail paging so an
+ * agent can page through the rest.
+ *
+ * Slicing is byte-based (matches the "~50KB" contract agents reason about)
+ * but implemented with JS string slicing over UTF-16 code units, NOT a
+ * Buffer byte slice. A slice boundary landing mid multibyte-character is
+ * tolerated (the string still round-trips through JSON safely; a stray
+ * replacement character at a cut edge is an acceptable trade-off for keeping
+ * this a plain string operation with no encode/decode step). Because the cut
+ * is code-unit based, the returned slice's real UTF-8 byte length can differ
+ * from READ_CAP_BYTES for multibyte content — so the truncation notice
+ * always reports the ACTUAL Buffer.byteLength of the returned slice (never
+ * the nominal cap), alongside the true total byte count. Both figures in the
+ * notice are real, measured byte counts.
+ */
+'use strict';
+
+/** Default cap on the BODY of every amicus_read response mode, in bytes. */
+const READ_CAP_BYTES = 51200; // 50 * 1024
+
+/**
+ * Slice `text` per the offset/limit/tail paging params, applying the default
+ * cap when no explicit params are given and the content exceeds it.
+ *
+ * Precedence when both `offset` and `tail` are given: `offset` wins (`tail`
+ * is ignored) — an explicit offset is a more specific request than "give me
+ * the end".
+ *
+ * @param {string} text - raw content (pre-fence).
+ * @param {{offset?: number, limit?: number, tail?: boolean}} params
+ * @returns {{body: string, truncated: boolean}} body is ready to fence/return.
+ */
+function sliceForRead(text, params = {}) {
+  const totalBytes = Buffer.byteLength(text, 'utf-8');
+  const limit = clampLimit(params.limit);
+  const hasOffset = typeof params.offset === 'number' && params.offset >= 0;
+
+  if (hasOffset) {
+    const slice = text.slice(params.offset, params.offset + limit);
+    return { body: slice, truncated: false };
+  }
+
+  if (params.tail) {
+    const sliceLen = Math.min(limit, text.length);
+    const slice = text.slice(text.length - sliceLen);
+    return { body: slice, truncated: false };
+  }
+
+  // No explicit slicing params: apply the default cap. Under-cap content is
+  // untouched (byte-identical to pre-15a.3 behavior).
+  if (totalBytes <= READ_CAP_BYTES) {
+    return { body: text, truncated: false };
+  }
+  const sliceLen = Math.min(READ_CAP_BYTES, text.length);
+  const tailSlice = text.slice(text.length - sliceLen);
+  const actualSliceBytes = Buffer.byteLength(tailSlice, 'utf-8');
+  const notice = `[truncated: showing last ${actualSliceBytes} of ${totalBytes} bytes — use offset/limit to page]`;
+  return { body: `${notice}\n${tailSlice}`, truncated: true };
+}
+
+/** Clamp an optional caller-supplied limit into [1, READ_CAP_BYTES]. */
+function clampLimit(limit) {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) { return READ_CAP_BYTES; }
+  return Math.max(1, Math.min(READ_CAP_BYTES, Math.floor(limit)));
+}
+
+module.exports = { sliceForRead, READ_CAP_BYTES };

package/src/utils/remediation-hints.js

@@ -72,6 +72,15 @@ const REMEDIATION_HINTS = Object.freeze({
    */
   removeLegacySidecar:
     "amicus doctor --fix  (removes the duplicate legacy 'sidecar' MCP entry — same server registered twice; the 'amicus' entry stays)",
+
+  /**
+   * Orphaned sessions-index.json.*.tmp files (15a.1/B15): a kill between the
+   * atomic tmp-write and rename leaves a stray temp file in the config dir
+   * forever. `doctor --fix` sweeps files older than 60s (never a live writer's
+   * ms-lived tmp).
+   */
+  sweepSessionIndexTmp:
+    'amicus doctor --fix  (sweeps orphaned .sessions-index.json.*.tmp files left by an interrupted write)',
 });
 
 module.exports = REMEDIATION_HINTS;

package/src/utils/result-schema.js

@@ -234,9 +234,13 @@ function buildWaveResultFromSession(project, waveId) {
 
 /**
  * Build a model-catalog document (`models [--search] [--refresh] --json`).
- * @param {{models: Array, fetchedAt: number|null, refreshed?: boolean, search?: string|null}} opts
+ * #13: lastRefreshAttempt/lastRefreshError are additive — null/null when the
+ * last refresh attempt on record succeeded (or none has happened yet).
+ * @param {{models: Array, fetchedAt: number|null, refreshed?: boolean, search?: string|null,
+ *   lastRefreshAttempt?: number|null, lastRefreshError?: string|null}} opts
  */
-function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null }) {
+function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
+  lastRefreshAttempt = null, lastRefreshError = null }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'model-catalog',
@@ -245,6 +249,8 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null }
     search,
     count: models.length,
     models,
+    lastRefreshAttempt: lastRefreshAttempt || null,
+    lastRefreshError: lastRefreshError || null,
   };
 }
 

package/src/utils/session-abort.js

@@ -75,7 +75,7 @@ function idleBackstopTeardown(sessionDir, server, externalServer) {
     fs.writeFileSync(path.join(sessionDir, 'summary.md'),
       'Session timed out — idle backstop fired before completion.\n', { mode: 0o600 });
   } catch { /* best-effort */ }
-  if (!externalServer && server) { try { server.close(); } catch { /* best-effort */ } }
+  if (!externalServer && server) { try { server.close().catch(() => {}); } catch { /* best-effort */ } }
   return 2;
 }
 

package/src/utils/session-index-tmp-sweep.js

@@ -0,0 +1,80 @@
+// src/utils/session-index-tmp-sweep.js
+'use strict';
+
+/**
+ * 15a.1/B15: orphaned sessions-index.json.*.tmp sweep for `amicus doctor --fix`.
+ *
+ * A kill between writeFileAtomic's tmp-write and rename (src/utils/session-index.js
+ * recordSession) leaves a stray `.sessions-index.json.<pid>.<hex>.tmp` file in the
+ * config dir forever — 60-73 were observed accumulating. This module lists and
+ * removes them; src/cli-handlers-doctor.js composes the result into a check line.
+ *
+ * The glob matches BOTH writeFileAtomic's naming and the (identical)
+ * pre-consolidation hand-rolled scheme, so orphans from either era are found.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const HINTS = require('./remediation-hints');
+
+/** Files older than this survive to the next --fix, never a live writer's ms-lived tmp. */
+const AGE_THRESHOLD_MS = 60 * 1000;
+
+/**
+ * List orphaned sessions-index.json.*.tmp files in the config dir.
+ * @returns {Array<{name: string, mtimeMs: number}>}
+ */
+function listSessionIndexTmpFiles() {
+  const { INDEX_FILENAME } = require('./session-index');
+  const dir = require('./config').getConfigDir();
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  const prefix = `.${INDEX_FILENAME}.`;
+  return entries
+    .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
+    .map((name) => {
+      let mtimeMs = null;
+      try { mtimeMs = fs.statSync(path.join(dir, name)).mtimeMs; } catch { /* raced away — skip below */ }
+      return { name, mtimeMs };
+    })
+    .filter((f) => f.mtimeMs !== null);
+}
+
+/** Delete one orphaned tmp file by name (relative to the config dir). */
+function unlinkSessionIndexTmp(name) {
+  const dir = require('./config').getConfigDir();
+  fs.unlinkSync(path.join(dir, name));
+}
+
+/**
+ * Compose the doctor check line for the tmp-orphan sweep. Pure decision logic
+ * (list/sweep side effects come in via `d`); src/cli-handlers-doctor.js wraps
+ * this in guard() the same way it wires the mcp-legacy check's inspect/migrate.
+ * @param {{listSessionIndexTmpFiles: () => Array<{name:string, mtimeMs:number}>,
+ *   fix?: boolean, now: () => number, unlinkSessionIndexTmp: (name: string) => void}} d
+ */
+function evaluateSessionIndexTmpSweep(d) {
+  const id = 'sessions-index-tmp'; const name = 'Session index tmp files';
+  const files = d.listSessionIndexTmpFiles() || [];
+  if (files.length === 0) {
+    return { id, name, status: 'ok', message: '0 orphaned tmp files', hint: null };
+  }
+  if (!d.fix) {
+    return { id, name, status: 'warn', message: `${files.length} orphaned tmp file(s) — run with --fix`, hint: HINTS.sweepSessionIndexTmp };
+  }
+  const nowMs = d.now();
+  const sweepable = files.filter((f) => (nowMs - f.mtimeMs) > AGE_THRESHOLD_MS);
+  let swept = 0;
+  for (const f of sweepable) {
+    try { d.unlinkSessionIndexTmp(f.name); swept += 1; } catch { /* best-effort — report what we got */ }
+  }
+  const remaining = files.length - swept;
+  if (remaining === 0) {
+    return { id, name, status: 'ok', message: `swept ${swept} orphaned tmp file(s)`, hint: null };
+  }
+  return { id, name, status: 'warn', message: `swept ${swept}, ${remaining} remaining (too fresh or unremovable)`, hint: HINTS.sweepSessionIndexTmp };
+}
+
+module.exports = {
+  AGE_THRESHOLD_MS, listSessionIndexTmpFiles, unlinkSessionIndexTmp, evaluateSessionIndexTmpSweep,
+};

package/src/utils/session-index.js

@@ -21,9 +21,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');
 const { getConfigDir } = require('./config');
 const { canonicalProjectPath } = require('./project-path');
+const { writeFileAtomic } = require('./atomic-write');
 
 /** Index filename under the config dir. */
 const INDEX_FILENAME = 'sessions-index.json';
@@ -70,10 +70,9 @@ function recordSession(taskId, project) {
     const index = readIndex(); // already guarded; corrupt -> {}
     index[taskId] = canonical;
     const target = path.join(dir, INDEX_FILENAME);
-    // Unique temp name so concurrent writers never clobber the same temp file.
-    const tmp = path.join(dir, `.${INDEX_FILENAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
-    fs.writeFileSync(tmp, JSON.stringify(index, null, 2), { mode: 0o600 });
-    fs.renameSync(tmp, target); // atomic on a single filesystem
+    // Atomic (temp + rename); writeFileAtomic mints a unique temp name per call
+    // so concurrent writers never clobber the same temp file.
+    writeFileAtomic(target, JSON.stringify(index, null, 2), { mode: 0o600 });
   } catch {
     // Index is a navigation aid; never let its failure break a session start.
   }

package/src/utils/session-path.js

@@ -2,16 +2,16 @@
  * Session path resolution.
  *
  * Resolves the on-disk directory for a session taskId under a project, with the
- * path-traversal guard, the legacy sidecar_sessions shim, and (issue #40) a
- * cross-project fallback via the global session index when the session is not
- * found under the project this lookup defaulted to.
+ * path-traversal guard and (issue #40) a cross-project fallback via the global
+ * session index when the session is not found under the project this lookup
+ * defaulted to.
  *
  * Extracted from validators.js to keep that module under the size gate.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('../session-manager');
+const { SESSIONS_DIR } = require('../session-manager');
 const { lookupSessionProject } = require('./session-index');
 const { canonicalProjectPath } = require('./project-path');
 
@@ -27,19 +27,15 @@ function safeSessionDirUnder(project, root, taskId) {
   return resolved;
 }
 
-/** Probe both roots (canonical, then legacy) under one project; null if neither exists. */
+/** Probe the canonical root under one project; null if it doesn't exist. */
 function existingDirUnderProject(project, taskId) {
   const canonical = safeSessionDirUnder(project, SESSIONS_DIR, taskId);
   if (fs.existsSync(canonical)) { return canonical; }
-  const legacy = safeSessionDirUnder(project, LEGACY_SESSIONS_DIR, taskId);
-  if (fs.existsSync(legacy)) { return legacy; }
   return null;
 }
 
 /**
- * Resolve an EXISTING session path: prefer canonical amicus, fall back to the
- * legacy sidecar_sessions dir (shim). The traversal guard runs against BOTH
- * roots, so a malicious taskId is rejected regardless of root.
+ * Resolve an EXISTING session path under the canonical amicus_sessions dir.
  *
  * On a per-project MISS (#40), consult the global index for the project the
  * taskId was actually recorded under and probe there — so a session created

package/src/utils/shared-server.js

@@ -6,7 +6,6 @@
  */
 
 const { IdleWatchdog } = require('./idle-watchdog');
-const { getCompatEnv } = require('./env-compat');
 
 const MAX_RESTARTS = 3;
 const RESTART_WINDOW = 5 * 60 * 1000;
@@ -26,8 +25,8 @@ class SharedServerManager {
    */
   constructor(options = {}) {
     this.logger = options.logger || console;
-    this.maxSessions = Number(process.env.SIDECAR_MAX_SESSIONS) || 20;
-    this.enabled = getCompatEnv('SHARED_SERVER') !== '0';
+    this.maxSessions = Number(process.env.AMICUS_MAX_SESSIONS) || 20;
+    this.enabled = process.env.AMICUS_SHARED_SERVER !== '0';
 
     /** @type {object|null} Active server handle */
     this.server = null;
@@ -177,7 +176,10 @@ class SharedServerManager {
     this._stopCrashPoll();
     if (this._restartTimer) { clearTimeout(this._restartTimer); this._restartTimer = null; }
     if (this.server) {
-      this.server.close();
+      // close() is async (B06 escalation); shutdown() stays sync so this
+      // remains fire-and-forget — guard against an unhandled rejection.
+      const closeResult = this.server.close();
+      if (closeResult && typeof closeResult.catch === 'function') { closeResult.catch(() => {}); }
       this.server = null;
       this.client = null;
     }
@@ -215,7 +217,7 @@ class SharedServerManager {
   /** Poll the Go engine pid; pid death IS the crash signal (H7). */
   _startCrashPoll(server) {
     this._stopCrashPoll();
-    const interval = Number(getCompatEnv('CRASH_POLL_MS')) || CRASH_POLL_INTERVAL;
+    const interval = Number(process.env.AMICUS_CRASH_POLL_MS) || CRASH_POLL_INTERVAL;
     this._crashPoll = setInterval(() => {
       if (this.server !== server) { this._stopCrashPoll(); return; }
       if (!this._isProcessAlive(server.goPid)) {