amicus 1.7.7 → 1.8.0

package/src/mcp-server.js

@@ -9,6 +9,7 @@ const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
 const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
 const { readProgress, isStalled } = require('./sidecar/progress');
+const { deriveStage, sanitizePreview } = require('./sidecar/progress-fields');
 const { SharedServerManager } = require('./utils/shared-server');
 const { durationBetween } = require('./utils/result-schema');
 const { canonicalProjectPath } = require('./utils/project-path');
@@ -16,6 +17,7 @@ const { isAllowedProjectRoot } = require('./project-root-allowlist');
 const { recordSession } = require('./utils/session-index');
 const { fileURLToPath } = require('url');
 const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
+const { runWait, registerInProcessRun, settleInProcessRun } = require('./mcp-wait');
 
 /**
  * Elapsed run duration: time between createdAt and the run's end, bounding the
@@ -211,13 +213,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.',
+    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.',
     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.</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.</system-reminder>';
+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>';
 
 /** Spawn an Amicus CLI process (fire-and-forget) */
 function spawnSidecarProcess(args, sessionDir) {
@@ -322,6 +324,12 @@ const handlers = {
           goPid: server.goPid || null,
           createdAt: new Date().toISOString(),
           headless: true, model: resolvedModel,
+          // F6: agent-visible provenance at creation. The CLI path writes these
+          // via createSessionMetadata; the shared-server path has no CLI child,
+          // so without them status/list/read show a briefing-less, mode-less run.
+          mode: 'headless',
+          agent: agent || 'build',
+          briefing: input.prompt,
         }, null, 2), { mode: 0o600 });
 
         // Build context from parent conversation (unless --no-context)
@@ -359,6 +367,10 @@ const handlers = {
 
         const timeoutMs = (input.timeout || 15) * 60 * 1000;
 
+        // amicus_wait fast path: this process owns the run promise; settle wakes
+        // any pending wait the moment finalize lands (poll fallback covers the rest).
+        registerInProcessRun(taskId);
+
         // Fire-and-forget: runHeadless with shared server's client
         runHeadless(resolvedModel, systemPrompt, userMessage, taskId, cwd,
           timeoutMs, agent, {
@@ -389,6 +401,13 @@ const handlers = {
           } catch (writeErr) {
             logger.warn('Failed to write error metadata', { error: writeErr.message });
           }
+        }).finally(() => {
+          // Guaranteed settle: runs after the .then/.catch bodies above (which
+          // write terminal metadata first), even if removeSession or another
+          // in-chain step throws — otherwise a pending amicus_wait leaks its
+          // waiter and the throw becomes an unhandled rejection. No-op if the
+          // taskId was never registered or was already settled.
+          settleInProcessRun(taskId);
         });
 
         // Return immediately
@@ -403,6 +422,7 @@ const handlers = {
         if (sessionId) {
           sharedServer.removeSession(sessionId);
         }
+        settleInProcessRun(taskId); // clear a dangling waiter (no-op if never registered)
         // Fall through to spawn path below
       }
     }
@@ -427,6 +447,10 @@ const handlers = {
         fs.writeFileSync(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
+          // CLI child's createSessionMetadata overwrite (or if it crashes first).
+          mode: input.noUi ? 'headless' : 'interactive',
+          briefing: input.prompt,
         }, null, 2), { mode: 0o600 });
       }
     }
@@ -464,6 +488,10 @@ const handlers = {
           leg.messages = p.messages;
           leg.latestActivity = p.latest;
           leg.stalled = leg.status === 'running' && isStalled(p.lastActivityMs);
+          leg.stage = p.stage;                                  // raw lifecycle stage
+          leg.phase = deriveStage(leg.status, p.stage);         // coarse: starting|generating|folding|terminal
+          leg.latestPreview = p.latestPreview;
+          leg.lastActivityAt = p.lastActivityAt;
         } catch { /* no progress yet — leave base fields only */ }
         return leg;
       });
@@ -537,9 +565,17 @@ const handlers = {
     };
     if (metadata.model) { response.model = metadata.model; }
 
+    // F6: agent-visible mode (headless|interactive). metadata.mode is written at
+    // creation (CLI createSessionMetadata; MCP paths since F6); fall back to the
+    // headless boolean for records created before that.
+    if (metadata.mode) { response.mode = metadata.mode; }
+    else if (metadata.headless !== undefined) { response.mode = metadata.headless ? 'headless' : 'interactive'; }
+
     if (metadata.status === 'running') {
       const progress = readProgress(sessionDir);
-      Object.assign(response, progress);
+      Object.assign(response, progress); // messages/latest/lastActivity/lastActivityMs/lastActivityAt/latestPreview/stage
+      response.messageCount = progress.messages;                       // stable agent-facing alias
+      response.phase = deriveStage(metadata.status, progress.stage);   // coarse lifecycle
 
       // Stall detection: flag when no activity for 2+ minutes
       const STALL_THRESHOLD_MS = 120000;
@@ -554,6 +590,8 @@ const handlers = {
       if (metadata.headless) {
         response.next_poll = computeNextPoll();
       }
+    } else {
+      response.phase = deriveStage(metadata.status, undefined);        // 'terminal'
     }
     if (metadata.status === 'crashed' || metadata.status === 'error') {
       response.reason = metadata.reason || 'Unknown error';
@@ -566,6 +604,14 @@ const handlers = {
     return { content };
   },
 
+  async amicus_wait(input, project) {
+    // statusFn injection avoids a circular require and inherits amicus_status's
+    // crash detection + wave leg rollup on every poll tick.
+    return runWait(input, project, {
+      statusFn: (i, p) => handlers.amicus_status(i, p),
+    });
+  },
+
   async amicus_read(input, project) {
     const cwd = project || getProjectDir(input.project);
     const sessionDir = safeSessionDir(cwd, input.taskId);
@@ -646,11 +692,25 @@ const handlers = {
         if (!fs.existsSync(metaPath)) { continue; }
         try {
           const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-          byId.set(d, {
+          const entry = {
             id: d, model: meta.model, status: meta.status, agent: meta.agent,
-            briefing: (String(meta.briefing || '')).slice(0, 80),
+            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
         }
@@ -733,18 +793,47 @@ const handlers = {
       return textResult(`Session ${input.taskId} is not running (status: ${metadata.status}).`);
     }
 
-    if (metadata.pid) {
-      try { process.kill(metadata.pid, 'SIGTERM'); } catch (err) {
-        if (err.code !== 'ESRCH') {
-          logger.warn('Failed to kill Amicus process', { pid: metadata.pid, error: err.message });
-        }
+    const sessionDir = safeSessionDir(cwd, input.taskId);
+    const { markAborted } = require('./utils/session-abort');
+    const { waitThenKill } = require('./utils/abort-coordinator');
+
+    if (metadata.type === 'wave') {
+      // Order is load-bearing: mark every running leg aborted BEFORE any kill
+      // or wave-status write. A TerminateProcess'd orchestrator (Windows
+      // process.kill) runs no signal handlers, and writing the wave status
+      // first falsifies the crash-cascade gate in amicus_status — both used
+      // to strand legs 'running' forever. Legs poll their own marker (~2s),
+      // so a live orchestrator settles gracefully during the grace window.
+      let legsAborted = 0;
+      for (const legId of metadata.legs || []) {
+        try {
+          const legMeta = readMetadata(legId, cwd);
+          if (legMeta && legMeta.status === 'running' &&
+              markAborted(safeSessionDir(cwd, legId), 'wave abort (MCP)')) {
+            legsAborted++;
+          }
+        } catch { /* skip unreadable leg */ }
       }
+      markAborted(sessionDir, 'manual abort (MCP)');
+      // Fallback only: SIGTERM the orchestrator + its OWNED OpenCode server
+      // if they outlive the grace window. Fire-and-forget — the tool result
+      // must not block on the grace period.
+      waitThenKill([metadata.pid, metadata.goPid]).catch(() => { /* best-effort */ });
+      return textResult(JSON.stringify({
+        taskId: input.taskId, status: 'aborted', legsAborted,
+        message: `Wave abort requested. ${legsAborted} running leg(s) marked aborted; ` +
+          'the fan-out process will terminate shortly.',
+      }));
     }
-    const sessionDir = safeSessionDir(cwd, input.taskId);
-    const metaPath = path.join(sessionDir, 'metadata.json');
-    metadata.status = 'aborted';
-    metadata.abortedAt = new Date().toISOString();
-    fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
+
+    // Single session: marker FIRST — the headless loop and the interactive
+    // abort watch honor it within ~2s and tear down gracefully (mirror flush,
+    // usage persist, server-side abortSession). SIGTERM only a process that
+    // outlives the grace window. NEVER touch goPid here: on the shared-server
+    // path it is the server every session shares (pid is null there, so that
+    // path is marker-only by construction).
+    markAborted(sessionDir, 'manual abort (MCP)');
+    waitThenKill(metadata.pid).catch(() => { /* best-effort */ });
 
     return textResult(JSON.stringify({
       taskId: input.taskId, status: 'aborted',
@@ -885,10 +974,16 @@ const handlers = {
   async amicus_guide() { return textResult(getGuideText()); },
 };
 
-// DEPRECATED(amicus-shim): also register each tool under its legacy sidecar_*
-// name so existing agent scripts keep working. Remove in a future revision.
+// 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',
@@ -899,6 +994,11 @@ const LEGACY_TOOL_ALIASES = {
   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');
@@ -909,6 +1009,9 @@ 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(
@@ -926,7 +1029,7 @@ async function startMcpServer() {
       }
     );
     register(tool.name);
-    if (LEGACY_TOOL_ALIASES[tool.name]) { register(LEGACY_TOOL_ALIASES[tool.name]); }
+    if (withLegacyAliases && LEGACY_TOOL_ALIASES[tool.name]) { register(LEGACY_TOOL_ALIASES[tool.name]); }
   }
   process.on('SIGTERM', () => {
     sharedServer.shutdown();
@@ -943,5 +1046,5 @@ async function startMcpServer() {
 
 module.exports = {
   handlers, startMcpServer, getProjectDir, resolveProjectDir, getClientRoot,
-  LEGACY_TOOL_ALIASES,
+  LEGACY_TOOL_ALIASES, legacyAliasesEnabled,
 };

package/src/mcp-tools.js

@@ -130,6 +130,30 @@ function getTools() {
       ),
     },
   },
+  {
+    name: 'amicus_wait',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    description:
+      'Wait (block inside one tool call) until an Amicus session or fan-out wave ' +
+      'reaches a terminal state, or until timeoutMs elapses. Returns the same JSON ' +
+      'shape as amicus_status plus {timedOut, waitedMs} (and {hint} on timeout), with ' +
+      'next_poll stripped/replaced. PREFER this over sleep+amicus_status polling for ' +
+      'headless runs: one call replaces many polls. If it returns timedOut: true the ' +
+      'run is still going — simply call amicus_wait again. Works for any session or ' +
+      'wave, including ones started by other processes.',
+    inputSchema: {
+      taskId: safeTaskId.optional().describe('The session task ID (or wave ID) to wait on.'),
+      waveId: safeTaskId.optional().describe('Alias for taskId when waiting on a fan-out wave.'),
+      timeoutMs: z.number().int().min(1000).max(110000).optional().describe(
+        'Max wait in milliseconds. Default 50000; capped at 110000 so the call ' +
+        'returns before typical MCP client kill windows. On expiry the tool ' +
+        'returns {timedOut: true} instead of erroring.'
+      ),
+      project: z.string().optional().describe(
+        'Optional project directory path. Auto-detected from working directory if omitted.'
+      ),
+    },
+  },
   {
     name: 'amicus_read',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -400,6 +424,9 @@ Amicus spawns parallel conversations with different LLMs and folds results back
 5. amicus_read to get the summary once complete
 6. 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.)
+
 **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.
 
 ### Interactive Mode (noUi: false, default)
@@ -412,7 +439,7 @@ Amicus spawns parallel conversations with different LLMs and folds results back
 ### 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)
+2. sleep 25, then amicus_status with the waveId (repeat until done), or call amicus_wait with the waveId
 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.
 

package/src/mcp-wait.js

@@ -0,0 +1,163 @@
+/**
+ * Engine for the amicus_wait MCP tool: blocks inside one tool call until a session/wave reaches a terminal state or the wait window closes.
+ * @module mcp-wait
+ *
+ * Two wake sources, one loop:
+ *  - disk polling of amicus_status (spawn-path CLI children, other-process
+ *    sessions, waves), and
+ *  - an in-process run registry: shared-server runs owned by THIS MCP process
+ *    settle their waiter the moment finalizeHeadlessResult lands, waking the
+ *    loop immediately instead of at the next poll tick.
+ *
+ * Client-timeout budget: the MCP TS SDK's default request timeout is 60s
+ * (DEFAULT_REQUEST_TIMEOUT_MSEC in @modelcontextprotocol/sdk shared/protocol).
+ * Claude Code can raise it via MCP_TOOL_TIMEOUT but we cannot assume it did,
+ * so the DEFAULT wait returns {timedOut:true} at 50s — before a 60s client
+ * kill — and the hard cap is 110s for clients with ~2min budgets.
+ */
+
+'use strict';
+
+const { versionWarning } = require('./utils/version-info');
+
+const DEFAULT_WAIT_MS = Number(process.env.AMICUS_WAIT_DEFAULT_MS) || 50000;
+const MAX_WAIT_MS = Number(process.env.AMICUS_WAIT_MAX_MS) || 110000;
+const MIN_WAIT_MS = 1000;
+const WAIT_POLL_INTERVAL_MS = Number(process.env.AMICUS_WAIT_POLL_INTERVAL_MS) || 2000;
+
+/** taskId -> {promise, resolve} for runs owned by this process. */
+const _inProcessRuns = new Map();
+
+/** Register a deferred for a run this process owns (shared-server path). */
+function registerInProcessRun(taskId) {
+  let resolve;
+  const promise = new Promise((r) => { resolve = r; });
+  _inProcessRuns.set(taskId, { promise, resolve });
+}
+
+/** Settle (and forget) a run's waiter. Safe for unknown ids / double calls. */
+function settleInProcessRun(taskId) {
+  const w = _inProcessRuns.get(taskId);
+  if (w) { _inProcessRuns.delete(taskId); w.resolve(); }
+}
+
+/** @returns {boolean} test hook */
+function hasInProcessRun(taskId) { return _inProcessRuns.has(taskId); }
+
+/** Clamp a requested timeout into [MIN, MAX]; default when absent/invalid. */
+function clampTimeout(requested) {
+  const n = Number(requested);
+  if (!Number.isFinite(n) || n <= 0) { return Math.min(DEFAULT_WAIT_MS, MAX_WAIT_MS); }
+  return Math.max(MIN_WAIT_MS, Math.min(n, MAX_WAIT_MS));
+}
+
+/** unref'd sleep so a pending wait never holds the MCP process open. */
+function defaultSleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (t.unref) { t.unref(); }
+  });
+}
+
+/** Parse the JSON payload out of an amicus_status result, or null. */
+function parseStatusPayload(statusResult) {
+  try { return JSON.parse(statusResult.content[0].text); } catch { return null; }
+}
+
+/**
+ * Terminal check over a parsed amicus_status payload. Any status other than
+ * running/unknown is terminal (TERMINAL_STATUSES omits 'timed-out', so an
+ * allowlist would miss the canonical single-session timeout status). Waves:
+ * terminal status wins; while the wave record still says 'running',
+ * all-legs-terminal also counts (aggregator may still be writing wave.json,
+ * but every leg has ended — the caller can read the legs).
+ */
+function isTerminalSnapshot(s) {
+  const statusTerminal = !!s.status && s.status !== 'running' && s.status !== 'unknown';
+  if (s.type === 'wave') {
+    return statusTerminal
+      || (Number.isFinite(s.legsTotal) && s.legsTotal > 0 && s.legsComplete >= s.legsTotal);
+  }
+  return statusTerminal;
+}
+
+/** Build the amicus_wait MCP result: status payload + {timedOut, waitedMs}. */
+function buildWaitResult(snapshot, timedOut, waitedMs) {
+  const body = { ...snapshot, timedOut, waitedMs };
+  delete body.next_poll; // amicus_wait replaces the sleep-25 polling protocol
+  if (timedOut) {
+    body.hint = 'Run still in progress when the wait window closed. Call amicus_wait again to continue waiting.';
+  }
+  const content = [{ type: 'text', text: JSON.stringify(body) }];
+  const warn = versionWarning();
+  if (warn) { content.push({ type: 'text', text: warn }); }
+  return { content };
+}
+
+/**
+ * Wait for a session/wave to reach a terminal state, or time out.
+ * @param {{taskId?:string, waveId?:string, timeoutMs?:number, project?:string}} input
+ * @param {string} project resolved project dir
+ * @param {{statusFn:Function, sleep?:Function, now?:Function, pollIntervalMs?:number}} deps
+ *   statusFn(input, project) must be the amicus_status handler (or compatible).
+ * @returns {Promise<object>} MCP tool result
+ */
+async function runWait(input, project, deps) {
+  const { statusFn } = deps;
+  const sleep = deps.sleep || defaultSleep;
+  const now = deps.now || Date.now;
+  const pollIntervalMs = deps.pollIntervalMs || WAIT_POLL_INTERVAL_MS;
+
+  const taskId = input.taskId || input.waveId;
+  if (!taskId) {
+    return { isError: true, content: [{ type: 'text', text: "amicus_wait requires 'taskId' (or 'waveId')." }] };
+  }
+
+  const timeoutMs = clampTimeout(input.timeoutMs);
+  const started = now();
+  const deadline = started + timeoutMs;
+
+  // 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.
+  let lastSnapshot = null;
+  let lastFailure = null;
+
+  for (;;) {
+    let snapshot = null;
+    try {
+      const statusResult = await statusFn({ taskId, project: input.project }, project);
+      if (statusResult.isError) { return statusResult; } // e.g. session not found — pinned behavior, unchanged
+      snapshot = parseStatusPayload(statusResult);
+      if (!snapshot) { lastFailure = `amicus_wait: unparseable status for ${taskId}.`; }
+    } catch (err) {
+      lastFailure = `amicus_wait: statusFn threw for ${taskId}: ${err.message}`;
+    }
+
+    if (snapshot) {
+      lastSnapshot = snapshot;
+      if (isTerminalSnapshot(snapshot)) { return buildWaitResult(snapshot, false, now() - started); }
+    }
+
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      if (lastSnapshot) { return buildWaitResult(lastSnapshot, true, now() - started); }
+      return { isError: true, content: [{ type: 'text', text: lastFailure || `amicus_wait: no valid status for ${taskId} before deadline.` }] };
+    }
+    const delay = Math.min(pollIntervalMs, remaining);
+    const waiter = _inProcessRuns.get(taskId);
+    // The waiter only ACCELERATES the wake — the sleep arm keeps the loop live
+    // for evicted/never-settled runs (disk polling stays authoritative).
+    await (waiter ? Promise.race([waiter.promise, sleep(delay)]) : sleep(delay));
+  }
+}
+
+module.exports = {
+  runWait, registerInProcessRun, settleInProcessRun, hasInProcessRun,
+  clampTimeout, isTerminalSnapshot, parseStatusPayload, buildWaitResult,
+  DEFAULT_WAIT_MS, MAX_WAIT_MS, WAIT_POLL_INTERVAL_MS,
+};

package/src/sidecar/conversation-mirror.js

@@ -44,6 +44,7 @@ function mirrorMessages(messages, state, opts = {}) {
   let currentAssistantMsgId = null;
   let assistantFinished = false;
   let sessionError = null;
+  let reasoningActivity = false;
   const list = Array.isArray(messages) ? messages : [];
   const messageCount = list.length;
 
@@ -127,15 +128,27 @@ function mirrorMessages(messages, state, opts = {}) {
         if (part.text.length > prevLen) {
           state.reasoningOutput += part.text.slice(prevLen);
           state.seenReasoningParts.set(partId, part.text.length);
-          if (!state.receivingReported) {
-            state.receivingReported = true;
-            progressUpdates.push({ stage: 'receiving', extra: { messagesReceived: 1 } });
-          }
+          reasoningActivity = true; // F6d: growth this poll = the model is thinking
         }
       }
     }
   }
 
+  // F6d: thinking IS activity. Emit ONE progress tick per poll with reasoning
+  // growth (only when no text/tool update already fired) so heartbeat/status
+  // show "Thinking…" and the stall detector resets during long pre-text
+  // reasoning — while a poll with NO growth still writes nothing, keeping
+  // genuine-stall detection intact. OpenCode's getMessages() exposes these
+  // deltas as growing part.type === 'reasoning' text.
+  if (reasoningActivity && progressUpdates.length === 0) {
+    const assistantCount = list.filter(m => m.info && m.info.role === 'assistant').length;
+    progressUpdates.push({
+      stage: 'receiving',
+      extra: { messagesReceived: Math.max(assistantCount, 1), stageLabel: 'Thinking…' },
+    });
+    state.receivingReported = true;
+  }
+
   // assistantFinished = true only when the LAST assistant message is complete
   // (earlier messages may finish while the model continues in new messages)
   const lastAssistant = list.filter(m => m.info && m.info.role === 'assistant').pop();

package/src/sidecar/interactive-abort.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logger } = require('../utils/logger');
+
+const DEFAULT_INTERVAL_MS = 2000;
+
+/**
+ * Watch a session's metadata.json for an external abort marker
+ * (status === 'aborted', written by `amicus abort` or MCP amicus_abort) and
+ * tear the interactive session down when it appears:
+ *   1. best-effort server-side abortSession (stops token spend immediately),
+ *   2. SIGTERM the Electron process (killIfAlive).
+ * Teardown then completes through the EXISTING Electron close handler
+ * (mirror.stop → usage persist, server.close) — this watcher triggers
+ * teardown but never owns it. Best-effort: read/parse errors keep polling.
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionDir
+ * @param {() => Promise<void>} opts.abortOpenCodeSession
+ * @param {() => void} opts.killElectron
+ * @param {number} [opts.intervalMs=2000]
+ * @returns {{ stop: () => void, wasAborted: () => boolean }}
+ */
+function startAbortWatch({ sessionDir, abortOpenCodeSession, killElectron, intervalMs = DEFAULT_INTERVAL_MS }) {
+  const metaPath = path.join(sessionDir, 'metadata.json');
+  let timer = null;
+  let stopped = false;
+  let aborted = false;
+
+  const schedule = () => {
+    if (stopped) { return; }
+    timer = setTimeout(tick, intervalMs);
+    if (timer.unref) { timer.unref(); }
+  };
+
+  async function tick() {
+    if (stopped) { return; }
+    try {
+      if (fs.existsSync(metaPath)) {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        if (meta.status === 'aborted') {
+          aborted = true;
+          stopped = true;
+          logger.info('External abort marker detected — tearing down interactive session', { sessionDir });
+          try { await abortOpenCodeSession(); } catch (err) {
+            logger.warn('abortSession failed during interactive abort', { error: err.message });
+          }
+          try { killElectron(); } catch (err) {
+            logger.warn('Electron kill failed during interactive abort', { error: err.message });
+          }
+          return; // teardown continues via the Electron close handler
+        }
+      }
+    } catch (err) {
+      logger.debug('Abort watch poll failed (best-effort)', { error: err.message });
+    }
+    schedule();
+  }
+
+  schedule();
+  return {
+    stop() { stopped = true; if (timer) { clearTimeout(timer); timer = null; } },
+    wasAborted() { return aborted; },
+  };
+}
+
+/**
+ * Fold the abort-watch outcome into the runInteractive result so
+ * resolveTerminalState() maps a marker-triggered GUI teardown to 'aborted' —
+ * never 'error' (SIGTERM'd Electron exits non-zero) and never 'complete'
+ * (Electron exiting 0 after the marker landed).
+ */
+function markResultAborted(result, wasAborted) {
+  if (wasAborted) {
+    result.aborted = true;
+    result.completed = false;
+  }
+  return result;
+}
+
+/**
+ * Best-effort, ONE-SHOT read of metadata.json to check for a durable
+ * 'aborted' marker written by `amicus abort` / MCP amicus_abort.
+ *
+ * Closes a race the poll-based startAbortWatch cannot: the marker can land
+ * and Electron can exit naturally before the watch's next ~2s tick (or the
+ * close handler can already be past markResultAborted, awaiting
+ * mirror.stop()). In that window abortWatch.wasAborted() reads false even
+ * though the session WAS aborted, so resolveTerminalState resolves
+ * 'complete' and finalizeSession clobbers the on-disk 'aborted' status.
+ * Callers should OR this into their aborted flag immediately before
+ * markResultAborted. Missing/corrupt metadata reads as false (best-effort,
+ * matches startAbortWatch's own error handling).
+ *
+ * @param {string} sessionDir
+ * @returns {boolean} true iff metadata.json exists and status === 'aborted'
+ */
+function readAbortedMarker(sessionDir) {
+  try {
+    const metaPath = path.join(sessionDir, 'metadata.json');
+    if (!fs.existsSync(metaPath)) { return false; }
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    return meta.status === 'aborted';
+  } catch (err) {
+    logger.debug('readAbortedMarker: metadata read failed (best-effort)', { error: err.message });
+    return false;
+  }
+}
+
+module.exports = { startAbortWatch, markResultAborted, readAbortedMarker, DEFAULT_INTERVAL_MS };