amicus 1.9.1 → 2.1.0

package/src/utils/mcp-discovery.js

@@ -12,7 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { logger } = require('./logger');
-const { stripSelfMcpEntries } = require('./mcp-self-identity');
+const { stripSelfMcpEntries, isAmicusMcpConfig } = require('./mcp-self-identity');
 
 /**
  * Normalize .mcp.json to a flat { name: config } map.
@@ -34,17 +34,16 @@ function normalizeMcpJson(raw) {
 }
 
 /**
- * Discover MCP servers from Claude Code's plugin chain AND ~/.claude.json.
- *
- * Discovery sources (merged, in priority order):
- * 1. ~/.claude.json → mcpServers  (servers added via `claude mcp add`)
- * 2. Enabled plugins → .mcp.json entries
+ * Read Claude Code's merged mcpServers map (~/.claude.json + plugin-chain
+ * .mcp.json files) WITHOUT the self-entry strip. Shared raw-read core for
+ * both discoverClaudeCodeMcps (strips) and hasAmicusRegistration (does not —
+ * it needs to SEE the amicus entry the strip would otherwise hide).
  *
  * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
  * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
- * @returns {object|null} Merged MCP server configs, or null if none found
+ * @returns {object} Merged MCP server configs (never stripped); {} if none found
  */
-function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
+function readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath) {
   const baseDir = claudeDir || path.join(os.homedir(), '.claude');
   const jsonPath = claudeJsonPath || path.join(os.homedir(), '.claude.json');
 
@@ -71,14 +70,12 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
     const settingsPath = path.join(baseDir, 'settings.json');
     if (!fs.existsSync(settingsPath)) {
       // No settings.json — skip plugin discovery, may still have claude.json servers
-      const merged = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
-      return Object.keys(merged).length > 0 ? merged : null;
+      return { ...claudeJsonServers };
     }
     const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
     const enabledPlugins = settings.enabledPlugins;
     if (!enabledPlugins || typeof enabledPlugins !== 'object') {
-      const merged = stripSelfMcpEntries({ ...claudeJsonServers }, logger);
-      return Object.keys(merged).length > 0 ? merged : null;
+      return { ...claudeJsonServers };
     }
 
     let installedPlugins = {};
@@ -133,12 +130,79 @@ function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
   }
 
   // Merge: plugin servers first, then claude.json overwrites (higher priority).
-  // Recursive-spawn guard: drop every entry that resolves to amicus itself.
-  const merged = stripSelfMcpEntries({ ...pluginServers, ...claudeJsonServers }, logger);
+  return { ...pluginServers, ...claudeJsonServers };
+}
 
+/**
+ * Discover MCP servers from Claude Code's plugin chain AND ~/.claude.json.
+ *
+ * Discovery sources (merged, in priority order):
+ * 1. ~/.claude.json → mcpServers  (servers added via `claude mcp add`)
+ * 2. Enabled plugins → .mcp.json entries
+ *
+ * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
+ * @returns {object|null} Merged MCP server configs, or null if none found
+ */
+function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
+  // Recursive-spawn guard: drop every entry that resolves to amicus itself.
+  const merged = stripSelfMcpEntries(readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath), logger);
   return Object.keys(merged).length > 0 ? merged : null;
 }
 
+/**
+ * True when Claude Code already has a working amicus MCP registration —
+ * checked against the SAME raw sources discoverClaudeCodeMcps reads, but
+ * WITHOUT stripSelfMcpEntries. discoverClaudeCodeMcps strips every
+ * 'amicus'/'sidecar'-shaped entry as a recursive-spawn guard (src/utils/
+ * mcp-self-identity.js), so code.amicus is ALWAYS undefined downstream —
+ * that check is the wrong consumer to answer "is amicus registered?" (B14).
+ *
+ * True when any entry's key is literally 'amicus' (regardless of its value
+ * shape — an unrecognizable value under that key is still an amicus
+ * registration slot) OR its value passes isAmicusMcpConfig() (covers
+ * aliased keys, e.g. legacy 'sidecar' or a custom name, whose command/args
+ * resolve to an amicus MCP invocation).
+ *
+ * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
+ * @returns {boolean}
+ */
+function hasAmicusRegistration(claudeDir, claudeJsonPath) {
+  const servers = readRawClaudeCodeMcpServers(claudeDir, claudeJsonPath) || {};
+  return Object.entries(servers).some(([name, config]) => (
+    name === 'amicus' || isAmicusMcpConfig(config)
+  ));
+}
+
+/**
+ * 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 +210,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');
@@ -187,5 +247,6 @@ module.exports = {
   discoverParentMcps,
   discoverClaudeCodeMcps,
   discoverCoworkMcps,
+  hasAmicusRegistration,
   normalizeMcpJson
 };

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-version.js

@@ -0,0 +1,14 @@
+/**
+ * @module result-schema-version
+ * The single SCHEMA_VERSION constant shared by result-schema.js and
+ * abort-result.js (split out to avoid a circular require between them).
+ *
+ * Stability contract: fields on any doc built from this version are only
+ * ADDED within a SCHEMA_VERSION; any rename/removal bumps SCHEMA_VERSION.
+ */
+
+'use strict';
+
+const SCHEMA_VERSION = 2;
+
+module.exports = { SCHEMA_VERSION };

package/src/utils/result-schema.js

@@ -1,15 +1,13 @@
-// src/utils/result-schema.js
 'use strict';
 
 /**
  * @module result-schema
  * Versioned, machine-parseable result documents for `--json` output (F4).
- *
- * Stability contract: fields are only ADDED within a SCHEMA_VERSION;
- * any rename/removal bumps SCHEMA_VERSION.
+ * Stability contract: fields are only ADDED within a SCHEMA_VERSION; any
+ * rename/removal bumps SCHEMA_VERSION (defined in ./result-schema-version.js,
+ * split out so ./abort-result.js can depend on it without a circular require).
  */
-
-const SCHEMA_VERSION = 2;
+const { SCHEMA_VERSION } = require('./result-schema-version');
 
 /** Leg/run statuses that count as terminal for wave aggregation. */
 const TERMINAL_STATUSES = ['complete', 'error', 'timeout', 'aborted', 'crashed', 'idle-timeout'];
@@ -159,8 +157,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
  * @param {string} project - Project dir
  * @param {string} taskId
  * @returns {object} run document
- * @throws {Error} if the session does not exist
- * @throws {Error} if metadata.json is missing or corrupt
+ * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
  */
 function buildRunResultFromSession(project, taskId) {
   const fs = require('fs');
@@ -189,8 +186,7 @@ function buildRunResultFromSession(project, taskId) {
  * @param {string} project
  * @param {string} waveId
  * @returns {object} wave document
- * @throws {Error} if the wave session does not exist
- * @throws {Error} if metadata.json is missing or corrupt
+ * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
  */
 function buildWaveResultFromSession(project, waveId) {
   const fs = require('fs');
@@ -234,9 +230,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 +245,8 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null }
     search,
     count: models.length,
     models,
+    lastRefreshAttempt: lastRefreshAttempt || null,
+    lastRefreshError: lastRefreshError || null,
   };
 }
 
@@ -277,6 +279,9 @@ function buildDoctorDoc({ version, timestamp, checks }) {
   };
 }
 
+// buildAbortResult lives in ./abort-result.js (size-gate split); re-exported below.
+const { buildAbortResult } = require('./abort-result');
+
 module.exports = {
   SCHEMA_VERSION,
   TERMINAL_STATUSES,
@@ -291,4 +296,5 @@ module.exports = {
   buildCatalogDoc,
   buildAuditDoc,
   buildDoctorDoc,
+  buildAbortResult,
 };

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)) {