amicus 1.9.1 → 2.1.0

package/src/mcp-server.js

@@ -1,13 +1,14 @@
 /** @module mcp-server — Amicus MCP Server (stdio transport) */
 const fs = require('fs');
 const path = require('path');
+const { writeFileAtomic } = require('./utils/atomic-write');
 const { spawn } = require('child_process');
 const { getTools, getGuideText } = require('./mcp-tools');
 const { tryResolveModel } = require('./utils/config');
 const os = require('os');
 const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
-const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
+const { getSessionDir, SESSIONS_DIR } = require('./session-manager');
 const { readProgress, isStalled } = require('./sidecar/progress');
 const { deriveStage, sanitizePreview } = require('./sidecar/progress-fields');
 const { SharedServerManager } = require('./utils/shared-server');
@@ -20,6 +21,7 @@ const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
 const { runWait, registerInProcessRun, settleInProcessRun } = require('./mcp-wait');
 const { detectClient } = require('./utils/client-detect');
 const { fenceSidecarOutput } = require('./utils/untrusted-fence');
+const { sliceForRead } = require('./utils/read-slice');
 
 /**
  * Elapsed run duration: time between createdAt and the run's end, bounding the
@@ -42,6 +44,14 @@ function elapsedMs(metadata) {
 // coverage); 'idle-timeout' is the shared-server idle-eviction value.
 const FAILED_TERMINAL_STATUSES = ['error', 'crashed', 'timeout', 'timed-out', 'idle-timeout', 'aborted'];
 
+// 15a.1: the statuses finalizeHeadlessResult's SUCCESS path can commit
+// (resolveTerminalState's complete/aborted/timed-out outcomes — never 'error',
+// which is finalizeHeadlessResult's OWN failure branch and must remain
+// overwritable by a later genuine failure). Once one of these lands, a later
+// throw in the same .then/.catch chain (e.g. removeSession) must not
+// overwrite it with a fresh 'error' — see the shared-server .catch below.
+const TERMINAL_STATUS_SET = new Set(['complete', 'aborted', 'timed-out']);
+
 const sharedServer = new SharedServerManager({ logger });
 
 /**
@@ -195,13 +205,13 @@ function appendVersionWarning(content) {
  */
 function computeNextPoll() {
   return {
-    hint: 'Run `sleep 25` in your shell before calling amicus_status again. This enforces the wait and prevents token-wasting rapid polls. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.',
+    hint: 'Preferred: call amicus_wait with this task ID — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): run `sleep 25` in your shell before calling amicus_status again. This enforces the wait and prevents token-wasting rapid polls.',
     wait_command: 'sleep 25',
   };
 }
 
-const HEADLESS_START_REMINDER = '<system-reminder>IMPORTANT: Before calling amicus_status, you MUST run `sleep 25` in your shell first. This enforces the polling interval and prevents token waste. Do other useful work while waiting, or run `sleep 25` to block until the next poll window. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.</system-reminder>';
-const HEADLESS_STATUS_REMINDER = '<system-reminder>IMPORTANT: This session is still running. Before calling amicus_status again, you MUST run `sleep 25` in your shell first. Each premature poll wastes context tokens for zero benefit. Run `sleep 25` now, then check again. Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true.</system-reminder>';
+const HEADLESS_START_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): before calling amicus_status, you MUST run `sleep 25` in your shell first. This enforces the polling interval and prevents token waste. Do other useful work while waiting, or run `sleep 25` to block until the next poll window.</system-reminder>';
+const HEADLESS_STATUS_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): this session is still running. Before calling amicus_status again, you MUST run `sleep 25` in your shell first. Each premature poll wastes context tokens for zero benefit. Run `sleep 25` now, then check again.</system-reminder>';
 
 /** Spawn an Amicus CLI process (fire-and-forget) */
 function spawnSidecarProcess(args, sessionDir) {
@@ -284,6 +294,7 @@ const handlers = {
         const { buildContext } = require('./sidecar/context-builder');
         const { buildPrompts } = require('./prompt-builder');
         const { runHeadless } = require('./headless');
+        const { generateFoldNonce } = require('./utils/fold-marker');
         const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
         // resolvedModel is already available from validateStartInputs() above
 
@@ -299,7 +310,7 @@ const handlers = {
         recordSession(taskId, cwd); // #40: global index for cross-project lookup
         const metaPath = path.join(sessionDir, 'metadata.json');
         const serverPort = server.url ? new URL(server.url).port : null;
-        fs.writeFileSync(metaPath, JSON.stringify({
+        writeFileAtomic(metaPath, JSON.stringify({
           taskId, status: 'running',
           pid: null, // Shared server path: don't store MCP server PID (abort would kill all sessions)
           opencodeSessionId: sessionId,
@@ -331,9 +342,12 @@ const handlers = {
           }
         }
 
+        // 15b.3: one nonce per run, generated before prompt construction.
+        const foldNonce = generateFoldNonce();
+
         // Build prompts (same as CLI path in start.js)
         const { system: systemPrompt, userMessage } = buildPrompts(
-          input.prompt, context, cwd, true, agent, input.summaryLength
+          input.prompt, context, cwd, true, agent, input.summaryLength, undefined, foldNonce
         );
 
         // Register session with idle eviction
@@ -342,7 +356,7 @@ const handlers = {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
             meta.status = 'idle-timeout';
             meta.completedAt = new Date().toISOString();
-            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+            writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
           } catch (err) {
             logger.warn('Failed to update evicted session metadata', { error: err.message });
           }
@@ -366,6 +380,7 @@ const handlers = {
             // Not yet consumed downstream; threaded here so it's available the
             // moment a consumer (e.g. metadata/fold-output) needs it (12a.1/B02).
             amicusClient: detectedClient,
+            nonce: foldNonce,
           }
         ).then((result) => {
           // Session done — route through resolveTerminalState (same single source
@@ -377,16 +392,38 @@ const handlers = {
           } catch (finErr) {
             logger.warn('Failed to finalize session', { error: finErr.message });
           }
-          sharedServer.removeSession(sessionId);
+          // Guarded: a throw here (e.g. a stale/evicted sessionId) must not
+          // escape into an unhandled rejection, and must not fall into .catch
+          // below and have its error-overwrite clobber the terminal status
+          // finalizeHeadlessResult just committed above.
+          try {
+            sharedServer.removeSession(sessionId);
+          } catch (removeErr) {
+            logger.warn('Failed to remove session from shared server', { taskId, error: removeErr.message });
+          }
         }).catch((err) => {
           logger.error('Shared server session failed', { taskId, error: err.message });
-          sharedServer.removeSession(sessionId);
+          try {
+            sharedServer.removeSession(sessionId);
+          } catch (removeErr) {
+            logger.warn('Failed to remove session from shared server', { taskId, error: removeErr.message });
+          }
           try {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+            // A run that already committed a terminal status (complete/aborted/
+            // timed-out) must never be clobbered by a LATER in-chain throw (e.g.
+            // a bug after finalizeHeadlessResult) — only a genuine pre-terminal
+            // failure (runHeadless itself rejecting) should land here as 'error'.
+            if (TERMINAL_STATUS_SET.has(meta.status)) {
+              logger.warn('Shared server chain error after terminal status already committed — not overwriting', {
+                taskId, existingStatus: meta.status, error: err.message,
+              });
+              return;
+            }
             meta.status = 'error';
             meta.reason = err.message;
             meta.completedAt = new Date().toISOString();
-            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+            writeFileAtomic(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
           } catch (writeErr) {
             logger.warn('Failed to write error metadata', { error: writeErr.message });
           }
@@ -433,7 +470,7 @@ const handlers = {
       recordSession(taskId, cwd); // #40: global index for cross-project lookup
       const metaPath = path.join(sessionDir, 'metadata.json');
       if (!fs.existsSync(metaPath)) {
-        fs.writeFileSync(metaPath, JSON.stringify({
+        writeFileAtomic(metaPath, JSON.stringify({
           taskId, status: 'running', pid: child.pid, createdAt: new Date().toISOString(),
           headless: !!input.noUi,
           // Seed briefing/mode so list/status are informative even before the
@@ -490,27 +527,31 @@ const handlers = {
       // Crash-detection for hard-killed fanout processes: the wave branch
       // returns early, so the single-session pid probe below never runs here.
       if (metadata.status === 'running' && metadata.pid) {
-        try { process.kill(metadata.pid, 0); } catch {
-          const crashedAt = new Date().toISOString();
-          Object.assign(metadata, {
-            status: 'crashed', crashedAt,
-            reason: 'Fan-out process exited unexpectedly',
-          });
-          fs.writeFileSync(path.join(sessionDir, 'metadata.json'),
-            JSON.stringify(metadata, null, 2), { mode: 0o600 });
-          // Cascade to legs whose pollers died with the parent
-          for (const leg of legs) {
-            if (leg.status === 'running') {
-              const legMeta = readMetadata(leg.taskId, cwd);
-              if (legMeta) {
-                Object.assign(legMeta, {
-                  status: 'crashed', crashedAt,
-                  reason: 'Parent fan-out process killed',
-                });
-                fs.writeFileSync(
-                  path.join(getSessionDir(cwd, leg.taskId), 'metadata.json'),
-                  JSON.stringify(legMeta, null, 2), { mode: 0o600 });
-                leg.status = 'crashed';
+        try { process.kill(metadata.pid, 0); } catch (err) {
+          // EPERM means the pid exists but we lack permission to signal it —
+          // that's ALIVE, not dead (mirrors utils/abort-coordinator.js isAlive).
+          if (err.code !== 'EPERM') {
+            const crashedAt = new Date().toISOString();
+            Object.assign(metadata, {
+              status: 'crashed', crashedAt,
+              reason: 'Fan-out process exited unexpectedly',
+            });
+            writeFileAtomic(path.join(sessionDir, 'metadata.json'),
+              JSON.stringify(metadata, null, 2), { mode: 0o600 });
+            // Cascade to legs whose pollers died with the parent
+            for (const leg of legs) {
+              if (leg.status === 'running') {
+                const legMeta = readMetadata(leg.taskId, cwd);
+                if (legMeta) {
+                  Object.assign(legMeta, {
+                    status: 'crashed', crashedAt,
+                    reason: 'Parent fan-out process killed',
+                  });
+                  writeFileAtomic(
+                    path.join(getSessionDir(cwd, leg.taskId), 'metadata.json'),
+                    JSON.stringify(legMeta, null, 2), { mode: 0o600 });
+                  leg.status = 'crashed';
+                }
               }
             }
           }
@@ -536,13 +577,17 @@ const handlers = {
     }
 
     if (metadata.status === 'running' && metadata.pid) {
-      try { process.kill(metadata.pid, 0); } catch {
-        Object.assign(metadata, {
-          status: 'crashed', crashedAt: new Date().toISOString(),
-          reason: 'Process exited unexpectedly',
-        });
-        fs.writeFileSync(path.join(sessionDir, 'metadata.json'),
-          JSON.stringify(metadata, null, 2));
+      try { process.kill(metadata.pid, 0); } catch (err) {
+        // EPERM means the pid exists but we lack permission to signal it —
+        // that's ALIVE, not dead (mirrors utils/abort-coordinator.js isAlive).
+        if (err.code !== 'EPERM') {
+          Object.assign(metadata, {
+            status: 'crashed', crashedAt: new Date().toISOString(),
+            reason: 'Process exited unexpectedly',
+          });
+          writeFileAtomic(path.join(sessionDir, 'metadata.json'),
+            JSON.stringify(metadata, null, 2), { mode: 0o600 });
+        }
       }
     }
 
@@ -619,12 +664,16 @@ const handlers = {
         // Fence the whole wave.json text: it embeds each leg's folded-back
         // summary/error, which is untrusted model prose entering the parent
         // context (same blunt whole-text treatment as the single-session fence).
-        return textResult(fenceSidecarOutput(fs.readFileSync(wavePath, 'utf-8')));
+        // Sliced BEFORE fencing (15a.3/B17) so the fence markup itself is
+        // never truncated.
+        const { body } = sliceForRead(fs.readFileSync(wavePath, 'utf-8'), input);
+        return textResult(fenceSidecarOutput(body));
       }
       const legsTotal = (readMeta.legs || []).length;
       const stillRunning = !readMeta.status || readMeta.status === 'running';
       const msg = stillRunning
-        ? `Wave ${input.taskId} is still running (${legsTotal} legs). Poll amicus_status.`
+        ? `Wave ${input.taskId} is still running (${legsTotal} legs). Preferred: call amicus_wait ` +
+          'with this waveId — one blocking call replaces polling. Fallback: poll amicus_status.'
         : `Wave ${input.taskId} ended with status '${readMeta.status}' before writing wave.json ` +
           '(fan-out may have been killed). Read individual legs by taskId, or use mode \'metadata\'.';
       return textResult(msg);
@@ -632,14 +681,22 @@ const handlers = {
 
     const mode = input.mode || 'summary';
     if (mode === 'metadata') {
-      return textResult(fs.readFileSync(path.join(sessionDir, 'metadata.json'), 'utf-8'));
+      // metadata is small structured JSON: exempt from offset/limit/tail (a
+      // caller slicing JSON would just break parsing), but still cap-defended
+      // defensively — apply the SAME notice convention, left unfenced to
+      // match its unfenced (structured-data) status.
+      const metaText = fs.readFileSync(path.join(sessionDir, 'metadata.json'), 'utf-8');
+      const { body } = sliceForRead(metaText, {});
+      return textResult(body);
     }
     if (mode === 'conversation') {
       const convPath = path.join(sessionDir, 'conversation.jsonl');
       if (!fs.existsSync(convPath)) { return textResult('No conversation recorded.'); }
       // Fence the whole conversation dump in ONE fence (not per-line): it is
-      // untrusted model prose entering the parent context.
-      return textResult(fenceSidecarOutput(fs.readFileSync(convPath, 'utf-8')));
+      // untrusted model prose entering the parent context. Sliced BEFORE
+      // fencing (15a.3/B17) so the fence markup itself is never truncated.
+      const { body } = sliceForRead(fs.readFileSync(convPath, 'utf-8'), input);
+      return textResult(fenceSidecarOutput(body));
     }
     // Default: summary
     const summaryPath = path.join(sessionDir, 'summary.md');
@@ -667,49 +724,47 @@ const handlers = {
     // parent context (inbound mirror of prompt-builder's outbound fence). Same
     // fence also wraps wave-summary and conversation-mode reads above (B03);
     // mode=metadata and every --json contract stay unfenced (structured data).
-    return textResult(fenceSidecarOutput(header + summaryText));
+    // Sliced BEFORE fencing (15a.3/B17). The model header is prepended before
+    // slicing, so it counts against offset/limit/the cap like the rest of the
+    // body — an explicit offset can page past it, same as any other prose.
+    const { body: slicedSummary } = sliceForRead(header + summaryText, input);
+    return textResult(fenceSidecarOutput(slicedSummary));
   },
 
   async amicus_list(input, project) {
     const cwd = project || getProjectDir(input.project);
-    // Scan BOTH roots: canonical amicus first, then legacy sidecar (shim).
-    const roots = [SESSIONS_DIR, LEGACY_SESSIONS_DIR]
-      .map(d => path.join(cwd, '.claude', d))
-      .filter(fs.existsSync);
-    if (roots.length === 0) { return textResult('No amicus sessions found.'); }
+    const root = path.join(cwd, '.claude', SESSIONS_DIR);
+    if (!fs.existsSync(root)) { return textResult('No amicus sessions found.'); }
 
-    // Dedup by task id — amicus (first root) wins over legacy.
     const byId = new Map();
-    for (const root of roots) {
-      for (const d of fs.readdirSync(root)) {
-        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(d)) { continue; }
-        if (byId.has(d)) { continue; }
-        const metaPath = path.join(root, d, 'metadata.json');
-        if (!fs.existsSync(metaPath)) { continue; }
-        try {
-          const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-          const entry = {
-            id: d, model: meta.model, status: meta.status, agent: meta.agent,
-            briefing: sanitizePreview(String(meta.briefing || ''), 80),
-            createdAt: meta.createdAt,
-            mode: meta.mode
-              || (meta.headless === undefined ? undefined : (meta.headless ? 'headless' : 'interactive')),
-          };
-          // Live-progress enrichment for RUNNING sessions only — readProgress
-          // parses conversation.jsonl, so terminal rows stay cheap.
-          if (meta.status === 'running') {
-            try {
-              const p = readProgress(path.join(root, d));
-              entry.phase = deriveStage(meta.status, p.stage);
-              entry.messageCount = p.messages;
-              entry.lastActivityAt = p.lastActivityAt;
-              entry.latestPreview = p.latestPreview;
-            } catch { /* progress optional */ }
-          }
-          byId.set(d, entry);
-        } catch {
-          // Skip unreadable metadata
+    for (const d of fs.readdirSync(root)) {
+      if (!/^[a-zA-Z0-9_-]{1,64}$/.test(d)) { continue; }
+      if (byId.has(d)) { continue; }
+      const metaPath = path.join(root, d, 'metadata.json');
+      if (!fs.existsSync(metaPath)) { continue; }
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        const entry = {
+          id: d, model: meta.model, status: meta.status, agent: meta.agent,
+          briefing: sanitizePreview(String(meta.briefing || ''), 80),
+          createdAt: meta.createdAt,
+          mode: meta.mode
+            || (meta.headless === undefined ? undefined : (meta.headless ? 'headless' : 'interactive')),
+        };
+        // Live-progress enrichment for RUNNING sessions only — readProgress
+        // parses conversation.jsonl, so terminal rows stay cheap.
+        if (meta.status === 'running') {
+          try {
+            const p = readProgress(path.join(root, d));
+            entry.phase = deriveStage(meta.status, p.stage);
+            entry.messageCount = p.messages;
+            entry.lastActivityAt = p.lastActivityAt;
+            entry.latestPreview = p.latestPreview;
+          } catch { /* progress optional */ }
         }
+        byId.set(d, entry);
+      } catch {
+        // Skip unreadable metadata
       }
     }
 
@@ -881,7 +936,7 @@ const handlers = {
       // The prompt goes via file: the spawned command line must NOT carry it,
       // or it re-hits the ~32KB Windows argument cap (F4 spec §4.2).
       fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
-      fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify({
+      writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
         models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
       }, null, 2), { mode: 0o600 });
@@ -915,14 +970,16 @@ const handlers = {
       try {
         const m = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8'));
         Object.assign(m, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
-        fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify(m, null, 2), { mode: 0o600 });
+        writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify(m, null, 2), { mode: 0o600 });
       } catch { /* best-effort */ }
       return textResult(`Failed to start fan-out: ${err.message}`, true);
     }
 
     const body = JSON.stringify({
       waveId, taskIds: legIds, status: 'running', mode: 'headless',
-      message: 'Fan-out started. Poll amicus_status with the waveId; amicus_read the waveId when complete.',
+      message: 'Fan-out started. Preferred: call amicus_wait with the waveId — one blocking call ' +
+        'replaces polling; re-call it while it returns timedOut: true. Fallback: poll amicus_status ' +
+        'with the waveId. Either way, amicus_read the waveId when complete.',
     });
     return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
   },
@@ -970,31 +1027,6 @@ const handlers = {
   async amicus_guide() { return textResult(getGuideText()); },
 };
 
-// DEPRECATED(amicus-shim): legacy sidecar_* twins of each amicus_* tool.
-// OPT-IN since v1.8.0 — registering both names doubled the advertised tool
-// surface (14 -> 28 per server). Set AMICUS_LEGACY_ALIASES=1 in the MCP
-// entry's "env" to restore them. A stdio MCP server cannot learn the
-// client-side registration key it was launched under (initialize carries
-// clientInfo, not the config key), so an env flag is the only reliable
-// switch. Remove entirely in the next major.
-const LEGACY_TOOL_ALIASES = {
-  amicus_start: 'sidecar_start', amicus_status: 'sidecar_status',
-  amicus_wait: 'sidecar_wait',
-  amicus_read: 'sidecar_read', amicus_list: 'sidecar_list',
-  amicus_resume: 'sidecar_resume', amicus_continue: 'sidecar_continue',
-  amicus_setup: 'sidecar_setup', amicus_abort: 'sidecar_abort',
-  amicus_fanout: 'sidecar_fanout',
-  amicus_guide: 'sidecar_guide',
-  amicus_council_tally: 'sidecar_council_tally',
-  amicus_council_stats: 'sidecar_council_stats',
-  amicus_verdict: 'sidecar_verdict',
-};
-
-/** sidecar_* tool aliases are opt-in as of v1.8.0. */
-function legacyAliasesEnabled(env = process.env) {
-  return env.AMICUS_LEGACY_ALIASES === '1';
-}
-
 /** Start the MCP server on stdio transport */
 async function startMcpServer() {
   const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
@@ -1005,9 +1037,6 @@ async function startMcpServer() {
     // can request them (roots/list) when no explicit project is supplied.
     { capabilities: { roots: {} } }
   );
-  // Read once per call (not at module load) so tests and long-lived
-  // processes observe the env deterministically.
-  const withLegacyAliases = legacyAliasesEnabled();
 
   for (const tool of getTools()) {
     const register = (name) => server.registerTool(
@@ -1025,7 +1054,6 @@ async function startMcpServer() {
       }
     );
     register(tool.name);
-    if (withLegacyAliases && LEGACY_TOOL_ALIASES[tool.name]) { register(LEGACY_TOOL_ALIASES[tool.name]); }
   }
   process.on('SIGTERM', () => {
     sharedServer.shutdown();
@@ -1042,5 +1070,4 @@ async function startMcpServer() {
 
 module.exports = {
   handlers, startMcpServer, getProjectDir, resolveProjectDir, getClientRoot,
-  LEGACY_TOOL_ALIASES, legacyAliasesEnabled,
 };

package/src/mcp-tools.js

@@ -9,6 +9,7 @@
 
 const { z } = require('zod');
 const { formatAliasNames } = require('./utils/config');
+const { READ_CAP_BYTES } = require('./utils/read-slice');
 
 /** Zod pattern for safe task IDs (alphanumeric, hyphens, underscores only) */
 const safeTaskId = z.string().regex(
@@ -43,8 +44,11 @@ function getTools() {
       'ALWAYS use HEADLESS (noUi: true) for all of them unless the user ' +
       'explicitly requests interactive. Opening multiple Electron windows ' +
       'at once is disruptive. ' +
-      'For headless mode, ALWAYS run `sleep 25` in your shell before each ' +
-      'amicus_status call to enforce the polling interval. ' +
+      'For headless mode, prefer calling amicus_wait with the task ID — one ' +
+      'blocking call replaces the sleep+status loop; re-call it while it returns ' +
+      'timedOut: true. Fallback (no amicus_wait tool available): ALWAYS run ' +
+      '`sleep 25` in your shell before each amicus_status call to enforce the ' +
+      'polling interval. ' +
       'For interactive mode, do not poll. Wait for the user to tell you ' +
       'they\'ve clicked Fold, then use amicus_read. ' +
       'Call amicus_guide first if you need help choosing a model or writing a good briefing.' +
@@ -60,9 +64,9 @@ function getTools() {
       ),
       agent: z.enum(['Chat', 'Plan', 'Build']).optional()
         .default('Chat').describe(
-          'Agent mode. Chat (default): reads auto, writes ask ' +
-          'permission. Plan: read-only analysis. Build: full auto ' +
-          '(all operations approved).'
+          'Agent mode. Chat (interactive default; headless runs auto-convert ' +
+          'to Build): reads auto, writes ask permission. Plan: read-only ' +
+          'analysis. Build: full auto (all operations approved).'
         ),
       noUi: z.boolean().optional().default(false).describe(
         'Run headless without GUI. Default false (opens Electron window).'
@@ -159,14 +163,35 @@ function getTools() {
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     description:
       'Read the results of a completed Amicus session. Returns the summary ' +
-      'by default, or full conversation history, or session metadata.',
+      'by default, or full conversation history, or session metadata. ' +
+      'Every mode is capped at ~50KB by default; when content exceeds the ' +
+      'cap and no offset/limit/tail is given, the response is the TAIL of ' +
+      'the content with a "[truncated: ...]" notice as the first line — use ' +
+      'offset/limit or tail to page through the rest.',
     inputSchema: {
       taskId: safeTaskId.describe('The task ID to read.'),
       mode: z.enum(['summary', 'conversation', 'metadata']).optional()
         .default('summary').describe(
           'What to read. summary (default): the fold summary. ' +
-          'conversation: full message history. metadata: session info.'
+          'conversation: full message history. metadata: session info ' +
+          '(always small; offset/limit/tail are ignored in this mode).'
         ),
+      offset: z.number().int().min(0).optional().describe(
+        'Byte offset to start reading from (0-based). When given, no cap or ' +
+        'truncation notice applies — the result is simply bounded by `limit` ' +
+        `(default ${READ_CAP_BYTES} bytes). Takes precedence over \`tail\` if ` +
+        'both are given. Ignored in mode "metadata".'
+      ),
+      limit: z.number().int().min(1).max(READ_CAP_BYTES).optional().describe(
+        `Max bytes to return, 1-${READ_CAP_BYTES}. Defaults to the ${READ_CAP_BYTES}-byte ` +
+        'cap. Ignored in mode "metadata".'
+      ),
+      tail: z.boolean().optional().describe(
+        'Return the last `limit` bytes instead of the start. Ignored if ' +
+        '`offset` is also given, and ignored in mode "metadata". This is ' +
+        'also the implicit default when content exceeds the cap and neither ' +
+        '`offset` nor `tail` is set.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -193,7 +218,8 @@ function getTools() {
     description:
       'Reopen a previous Amicus session with full conversation history ' +
       'preserved. The session continues in the same OpenCode session. ' +
-      'Returns a task ID immediately — use amicus_status to poll.',
+      'Returns a task ID immediately — use amicus_wait to block until done ' +
+      '(or poll amicus_status).',
     inputSchema: {
       taskId: safeTaskId.describe(
         'The task ID of the session to resume.'
@@ -216,7 +242,7 @@ function getTools() {
       'Start a new Amicus session that inherits a previous session\'s ' +
       'conversation as context. The previous session\'s messages become ' +
       'read-only background for the new task. Returns a task ID ' +
-      'immediately — use amicus_status to poll.',
+      'immediately — use amicus_wait to block until done (or poll amicus_status).',
     inputSchema: {
       taskId: safeTaskId.describe(
         'The task ID of the previous session to continue from.'
@@ -274,16 +300,20 @@ function getTools() {
     description:
       'Run N models on the SAME prompt in parallel (one shared engine) and ' +
       'aggregate the results. Headless only. Returns {waveId, taskIds[]} ' +
-      'immediately. Poll amicus_status with the waveId (run `sleep 25` between ' +
-      'polls); when done, amicus_read the waveId for the aggregated JSON wave ' +
-      'document (per-leg summaries inside). Each leg is also an ordinary ' +
-      'session readable by taskId.',
+      'immediately. Preferred: call amicus_wait with the waveId — one blocking ' +
+      'call replaces polling; re-call it while it returns timedOut: true. ' +
+      'Fallback (no amicus_wait tool available): poll amicus_status with the ' +
+      'waveId (run `sleep 25` between polls). Either way, amicus_read the waveId ' +
+      'when done for the aggregated JSON wave document (per-leg summaries ' +
+      'inside). Each leg is also an ordinary session readable by taskId.',
     inputSchema: {
       models: z.array(safeModel).min(1).max(10).optional().describe(
         `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
       ),
       council: z.string().optional().describe(
-        "Run a saved council by name (e.g. 'free') instead of 'models'. Expands to the council's members. Mutually exclusive with 'models'."
+        "Run a saved council, or a built-in bench ('free', 'budget', 'frontier'), instead of 'models'. " +
+        "Expands to the council's members; a saved council of the same name shadows a built-in. " +
+        'Mutually exclusive with \'models\'.'
       ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
@@ -418,16 +448,18 @@ Amicus spawns parallel conversations with different LLMs and folds results back
 
 ### Headless Mode (noUi: true)
 1. amicus_start with model + prompt + noUi: true -> get task ID
-2. Run \`sleep 25\` in your shell (this enforces the polling interval)
-3. amicus_status to check progress
-4. If still running, run \`sleep 25\` again before each subsequent amicus_status call
-5. amicus_read to get the summary once complete
-6. Act on findings
+2. **Preferred:** call amicus_wait with the task ID — one blocking call (up to
+   ~50s) replaces the sleep+status loop; re-call it while it returns timedOut: true
+3. amicus_read to get the summary once complete
+4. Act on findings
 
-(Alternative to steps 2-4: call amicus_wait with the task ID — one call blocks
-up to ~50s and returns status; call it again while it returns timedOut: true.)
+**Fallback (only if amicus_wait is unavailable):**
+1. Run \`sleep 25\` in your shell (this enforces the polling interval)
+2. amicus_status to check progress
+3. If still running, run \`sleep 25\` again before each subsequent amicus_status call
+4. amicus_read to get the summary once complete
 
-**IMPORTANT:** Always run \`sleep 25\` before every amicus_status call. This is not optional. Each premature poll wastes context tokens for zero benefit. The sleep command enforces the wait mechanically.
+**IMPORTANT (fallback path only):** Always run \`sleep 25\` before every amicus_status call. This is not optional. Each premature poll wastes context tokens for zero benefit. The sleep command enforces the wait mechanically.
 
 ### Interactive Mode (noUi: false, default)
 1. amicus_start with model + prompt -> get task ID
@@ -439,17 +471,19 @@ up to ~50s and returns status; call it again while it returns timedOut: true.)
 ### Fan-Out (amicus_fanout)
 Run the SAME prompt across 1-10 models in parallel (one shared engine):
 1. amicus_fanout with models + prompt -> {waveId, taskIds[]}
-2. sleep 25, then amicus_status with the waveId (repeat until done), or call amicus_wait with the waveId
+2. **Preferred:** call amicus_wait with the waveId (re-call while timedOut: true). **Fallback:** sleep 25, then amicus_status with the waveId (repeat until done)
 3. amicus_read the waveId -> aggregated JSON wave document (per-leg summaries inside)
 Each leg is an ordinary session: read/resume/continue it by taskId.
 
 ## Agent Selection
 | Agent | Reads | Writes | Bash | Use When |
 |-------|-------|--------|------|----------|
-| Chat (default) | auto | asks | asks | Questions, analysis |
+| Chat (interactive default*) | auto | asks | asks | Questions, analysis |
 | Plan | auto | denied | denied | Read-only analysis |
 | Build | auto | auto | auto | Implementation tasks |
 
+* Headless (\`noUi\`) runs auto-convert Chat to Build — Chat would otherwise stall waiting on write/bash approval with no UI to approve it.
+
 ## Writing Good Briefings
 Include: Objective, Background, Files of interest, Success criteria, Constraints.
 

package/src/mcp-wait.js

@@ -119,11 +119,14 @@ async function runWait(input, project, deps) {
 
   // Torn-read tolerance: a statusFn THROW, or a non-error result whose
   // content[0].text fails to JSON.parse, is a MISSED TICK — not a hard
-  // failure. metadata.json is written with non-atomic fs.writeFileSync by
-  // several writers, and this loop reads it up to ~55x per call (2s cadence),
-  // multiplying exposure to a mid-write torn read vs the old 25s manual
-  // polling. Keep looping on a miss; only surface an error if the deadline
-  // passes without EVER having seen a valid snapshot.
+  // failure. As of Phase 15 all metadata.json writers use writeFileAtomic
+  // (tmp+rename), so a torn read is no longer expected from any current
+  // writer; this tolerance remains as defense-in-depth for metadata.json
+  // files left by pre-upgrade writers and for exotic filesystems where
+  // rename isn't atomic. This loop reads it up to ~55x per call (2s cadence),
+  // multiplying exposure vs the old 25s manual polling. Keep looping on a
+  // miss; only surface an error if the deadline passes without EVER having
+  // seen a valid snapshot.
   let lastSnapshot = null;
   let lastFailure = null;