amicus 1.7.6 → 1.8.0

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 };

package/src/sidecar/interactive.js

@@ -4,17 +4,20 @@
  */
 
 const path = require('path');
+const fs = require('fs');
 const { spawn } = require('child_process');
 
 const { startOpenCodeServer } = require('./session-utils');
-const { createSession, sendPromptAsync, getMessages } = require('../opencode-client');
+const { createSession, sendPromptAsync, getMessages, abortSession } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { logger } = require('../utils/logger');
 const { getCompatEnv } = require('../utils/env-compat');
 const { startInteractiveMirror } = require('./interactive-mirror');
+const { startAbortWatch, markResultAborted, readAbortedMarker } = require('./interactive-abort');
 const { getSessionDir } = require('../session-manager');
 const { canonicalProjectPath } = require('../utils/project-path');
 const { ensureElectron } = require('./electron-ensure');
+const { writeProgress } = require('./progress');
 
 /** Resolve the Electron binary path ONLY when the exe actually exists on disk.
  *  #54: path.txt surviving (require('electron') resolving) is NOT enough — a
@@ -115,6 +118,14 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
 
   const { agent, isResume, conversation, mcp, reasoning, opencodeSessionId, client } = options;
 
+  // F6c: mirror headless's lifecycle stages (best-effort — a write failure must
+  // never break the GUI) so the heartbeat/status never read "Starting up...".
+  const sessionDir = getSessionDir(project, taskId);
+  const progressStage = (stage) => {
+    try { fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 }); writeProgress(sessionDir, stage); } catch { /* best-effort */ }
+  };
+  progressStage('initializing');
+
   // Scope the OpenCode session to the project/--cwd (#45). The SDK Session
   // object echoes a `directory`, but createSession() returns only the id, so we
   // use the canonicalized --cwd CONSISTENTLY for BOTH the create scope and the
@@ -133,6 +144,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     });
     ocClient = result.client;
     server = result.server;
+    progressStage('server_ready');
   } catch (error) {
     logger.error('Failed to start OpenCode server', { error: error.message });
     return {
@@ -148,9 +160,11 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       // Resume: reconnect to existing OpenCode session
       sessionId = opencodeSessionId;
       logger.info('Reconnecting to existing session', { sessionId });
+      progressStage('session_created');
     } else {
       // New session: create and send initial prompt, scoped to --cwd (#45).
       sessionId = await createSession(ocClient, sessionDirectory);
+      progressStage('session_created');
 
       // System prompt is set on agent config (hidden from UI).
       // Do NOT pass system here — promptAsync's system field is visible in the UI.
@@ -165,6 +179,7 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       if (reasoning) { promptOptions.reasoning = reasoning; }
 
       await sendPromptAsync(ocClient, sessionId, promptOptions);
+      progressStage('prompt_sent');
     }
     logger.debug('Interactive session ready', { sessionId, isResume: !!isResume });
   } catch (error) {
@@ -199,13 +214,21 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
     onActivity: () => watchdog.touch(),
   });
 
-  const sessionDir = getSessionDir(project, taskId);
   const mirror = startInteractiveMirror({
     getMessages: () => getMessages(ocClient, sessionId, sessionDirectory),
     sessionDir,
     onActivity: () => watchdog.touch(),
   });
 
+  // Phase 3: external aborts (CLI `amicus abort` / MCP amicus_abort) write a
+  // metadata marker; nothing in the GUI path watched it before. On marker:
+  // server-side abort + SIGTERM Electron; the close handler finishes teardown.
+  const abortWatch = startAbortWatch({
+    sessionDir,
+    abortOpenCodeSession: () => abortSession(ocClient, sessionId, sessionDirectory),
+    killElectron: () => killIfAlive(electronProcess),
+  });
+
   return new Promise((resolve, _reject) => {
     // Prefer the path ensureElectron() resolved: a same-process first-use
     // provision can leave require('electron') cached as a stale null (#55).
@@ -248,6 +271,13 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       process.removeListener('SIGTERM', killChildOnParentDeath);
       watchdog.cancel();
       activityPoller.stop();
+      abortWatch.stop();
+      // Close a race the poll-based watch can miss: the marker can land and
+      // Electron can exit naturally before the next ~2s tick. Re-read the
+      // on-disk marker ONCE here and OR it in so a durable 'aborted' status
+      // is never clobbered to 'complete' below (phase-3 final review, FIX 2).
+      const wasAborted = abortWatch.wasAborted() || readAbortedMarker(sessionDir);
+      markResultAborted(result, wasAborted);
       try {
         const { usage } = await mirror.stop();
         if (usage) { result.usage = usage; }

package/src/sidecar/progress-fields.js

@@ -0,0 +1,60 @@
+/**
+ * @module progress-fields
+ * Derived, agent-facing progress fields shared by the MCP status/list
+ * handlers, the `amicus status` CLI, and readProgress(): a sanitized preview
+ * of the newest assistant text, and a coarse lifecycle stage.
+ */
+
+'use strict';
+
+/** Coarse stages surfaced to agents. */
+const COARSE_STAGES = ['starting', 'generating', 'folding', 'terminal'];
+
+/**
+ * Collapse whitespace and defang fence/tag characters so the preview can be
+ * embedded in a one-line JSON status without opening a code fence or tag
+ * (prompt-injection hygiene: the FULL text is only available via amicus_read,
+ * which wraps it in the untrusted-output fence).
+ * @param {string} text @param {number} [max=120] @returns {string}
+ */
+function sanitizePreview(text, max = 120) {
+  const collapsed = String(text).replace(/[`<>]/g, '').replace(/\s+/g, ' ').trim();
+  return collapsed.length > max ? collapsed.slice(0, max) + '…' : collapsed;
+}
+
+/**
+ * The newest assistant TEXT content from parsed conversation.jsonl entries,
+ * sanitized to ~120 chars. Tool-use/result lines are skipped. Null when no
+ * assistant text exists yet.
+ * @param {object[]} entries @returns {string|null}
+ */
+function latestAssistantPreview(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e && e.role === 'assistant' && typeof e.content === 'string' && e.content.trim()) {
+      return sanitizePreview(e.content);
+    }
+  }
+  return null;
+}
+
+/**
+ * Map (metadata.status, progress.stage) to the coarse agent-facing stage.
+ *  - terminal metadata status -> 'terminal'
+ *  - progress 'receiving' -> 'generating'
+ *  - progress 'complete' while metadata still says running -> 'folding'
+ *    (mirror stopped; summary/conflict finalize in flight)
+ *  - anything else -> 'starting'
+ * @param {string|undefined} metadataStatus @param {string|undefined} progressStage
+ * @returns {string}
+ */
+function deriveStage(metadataStatus, progressStage) {
+  if (metadataStatus && metadataStatus !== 'running' && metadataStatus !== 'unknown') {
+    return 'terminal';
+  }
+  if (progressStage === 'receiving') { return 'generating'; }
+  if (progressStage === 'complete') { return 'folding'; }
+  return 'starting';
+}
+
+module.exports = { sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES };

package/src/sidecar/progress.js

@@ -2,12 +2,14 @@
  * Sidecar Progress Reader
  *
  * Reads conversation.jsonl and progress.json from a session directory
- * and returns progress info: message count, last activity time, latest action,
- * and lifecycle stage.
+ * and returns progress info: message count, last activity (relative string,
+ * raw ms, and absolute ISO), latest action, a sanitized preview of the
+ * newest assistant text, and lifecycle stage.
  */
 
 const fs = require('fs');
 const path = require('path');
+const { latestAssistantPreview } = require('./progress-fields');
 
 /** Lifecycle stage labels */
 const STAGE_LABELS = {
@@ -122,7 +124,9 @@ function writeProgress(sessionDir, stage, extra = {}) {
  * Read progress from a session's conversation.jsonl and progress.json files.
  *
  * @param {string} sessionDir - Path to the session directory
- * @returns {{ messages: number, lastActivity: string, latest: string, stage?: string }}
+ * @returns {{ messages: number, lastActivity: string, latest: string,
+ *   lastActivityMs: number|null, lastActivityAt: string|null,
+ *   latestPreview: string|null, stage?: string }}
  */
 function readProgress(sessionDir) {
   const convPath = path.join(sessionDir, 'conversation.jsonl');
@@ -159,63 +163,63 @@ function readProgress(sessionDir) {
     ? computeLastActivity(convStat.mtime)
     : 'never';
 
-  // Read progress.json for lifecycle stage info
-  let stage;
-
+  // Read + parse progress.json ONCE; stage/latest/lastActivity below and the
+  // newestActivity computation all derive from this single parse.
+  let progress = null;
   if (fs.existsSync(progressPath)) {
     try {
-      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
-      stage = progress.stage;
+      progress = JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
+    } catch {
+      // Ignore malformed progress file
+    }
+  }
 
-      // Use progress stage label when no assistant entries exist yet
-      if (messages === 0 && progress.stageLabel) {
-        latest = progress.stageLabel;
-      }
+  // Lifecycle stage info from progress.json
+  let stage;
 
-      // Use progress.json latestTool for better latest when extractLatest
-      // returns a generic fallback (tool_use entries without name)
-      if (messages > 0 && progress.latestTool && (latest === 'Working...' || latest === 'Executing tool call...')) {
-        latest = `Calling tool: ${progress.latestTool}`;
-      }
+  if (progress) {
+    stage = progress.stage;
 
-      // Use messagesReceived from progress when conversation has no assistant entries
-      if (messages === 0 && progress.messagesReceived !== undefined) {
-        messages = progress.messagesReceived;
-      }
+    // Use progress stage label when no assistant entries exist yet
+    if (messages === 0 && progress.stageLabel) {
+      latest = progress.stageLabel;
+    }
 
-      // Use progress updatedAt for lastActivity if more recent
-      if (progress.updatedAt) {
-        const progressTime = new Date(progress.updatedAt);
-        if (!convStat || progressTime > convStat.mtime) {
-          lastActivity = computeLastActivity(progressTime);
-        }
-      }
-    } catch {
-      // Ignore malformed progress file
+    // Use progress.json latestTool for better latest when extractLatest
+    // returns a generic fallback (tool_use entries without name)
+    if (messages > 0 && progress.latestTool && (latest === 'Working...' || latest === 'Executing tool call...')) {
+      latest = `Calling tool: ${progress.latestTool}`;
     }
-  }
 
-  // Compute raw lastActivityMs for stall detection
-  let lastActivityMs = null;
-  if (convStat) {
-    lastActivityMs = Date.now() - convStat.mtime.getTime();
-  }
-  // Use progress.json updatedAt if more recent
-  if (fs.existsSync(progressPath)) {
-    try {
-      const progress = JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
-      if (progress.updatedAt) {
-        const progressMs = Date.now() - new Date(progress.updatedAt).getTime();
-        if (lastActivityMs === null || progressMs < lastActivityMs) {
-          lastActivityMs = progressMs;
-        }
+    // Use messagesReceived from progress when conversation has no assistant entries
+    if (messages === 0 && progress.messagesReceived !== undefined) {
+      messages = progress.messagesReceived;
+    }
+
+    // Use progress updatedAt for lastActivity if more recent
+    if (progress.updatedAt) {
+      const progressTime = new Date(progress.updatedAt);
+      if (!convStat || progressTime > convStat.mtime) {
+        lastActivity = computeLastActivity(progressTime);
       }
-    } catch {
-      // Ignore — already handled above
     }
   }
 
-  const result = { messages, lastActivity, latest, lastActivityMs };
+  // Newest activity timestamp across BOTH sources (conv mtime, progress.updatedAt):
+  // feeds lastActivityMs (stall detection) AND lastActivityAt (absolute ISO for
+  // agents) from one value so they can never disagree.
+  let newestActivity = convStat ? convStat.mtime : null;
+  if (progress && progress.updatedAt) {
+    const t = new Date(progress.updatedAt);
+    if (!newestActivity || t > newestActivity) { newestActivity = t; }
+  }
+  const lastActivityMs = newestActivity ? Date.now() - newestActivity.getTime() : null;
+
+  const result = {
+    messages, lastActivity, latest, lastActivityMs,
+    lastActivityAt: newestActivity ? newestActivity.toISOString() : null,
+    latestPreview: latestAssistantPreview(entries),
+  };
   if (stage !== undefined) {
     result.stage = stage;
   }

package/src/sidecar/resume.js

@@ -110,7 +110,10 @@ function updateSessionStatus(sessionDir, status) {
   return meta;
 }
 
-/** Resume a previous sidecar session - Spec Reference: §4.3, §8.3 */
+/**
+ * Resume a previous sidecar session - Spec Reference: §4.3, §8.3
+ * @returns {Promise<number>} process exit code
+ */
 async function resumeSidecar(options) {
   const {
     taskId, project = process.cwd(), headless = false, timeout = 15,
@@ -163,6 +166,7 @@ async function resumeSidecar(options) {
     heartbeat = createHeartbeat();
 
     let summary;
+    let result;
     const effectiveAgent = metadata.agent || 'Build';
 
     // Load conversation for both paths (interactive already did this, headless didn't)
@@ -173,7 +177,7 @@ async function resumeSidecar(options) {
 
     if (headless) {
       const userMessage = buildResumeUserMessage(metadata.briefing || '', existingConversation);
-      const result = await runHeadless(
+      result = await runHeadless(
         metadata.model, resumePrompt, userMessage,
         taskId, project, timeout * 60 * 1000, effectiveAgent, { mcp: mcpServers }
       );
@@ -184,7 +188,7 @@ async function resumeSidecar(options) {
     } else {
       logger.info('Launching interactive resume', { taskId, model: metadata.model });
 
-      const result = await runInteractive(
+      result = await runInteractive(
         metadata.model, resumePrompt, metadata.briefing || '',
         taskId, project,
         {
@@ -202,10 +206,22 @@ async function resumeSidecar(options) {
     // Output summary
     outputSummary(summary);
 
-    // Finalize session (use updatedMetadata which has resumedAt). Pass status
-    // explicitly to preserve the pre-#36 default ('complete') and stay out of
-    // the empty-summary guard — interactive resume legitimately has no summary.
-    finalizeSession(sessionDir, summary, project, updatedMetadata, { status: 'complete' });
+    // Map the run result to the canonical terminal status + exit code —
+    // mirrors start.js. Explicit status preserves the interactive
+    // empty-summary carve-out (the #36 guard never re-classifies it).
+    const { resolveTerminalState } = require('./session-finalize');
+    const terminal = resolveTerminalState(result);
+    const metaPath = SessionPaths.metadataFile(sessionDir);
+    if (terminal.status === 'error') {
+      updatedMetadata.status = 'error';
+      updatedMetadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+      updatedMetadata.completedAt = new Date().toISOString();
+      fs.writeFileSync(metaPath, JSON.stringify(updatedMetadata, null, 2), { mode: 0o600 });
+      logger.error('Resume completed with error', { taskId, error: updatedMetadata.reason });
+    } else {
+      finalizeSession(sessionDir, summary, project, updatedMetadata, { status: terminal.status });
+    }
+    return terminal.exitCode; // finally below still releases the lock first
   } finally {
     if (heartbeat) { heartbeat.stop(); }
     releaseLock(sessionDir);

package/src/sidecar/start.js

@@ -23,6 +23,7 @@ const { acquireLock, releaseLock } = require('../utils/session-lock');
 const { loadMcpConfig, parseMcpSpec } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { discoverParentMcps } = require('../utils/mcp-discovery');
+const { stripSelfMcpEntries } = require('../utils/mcp-self-identity');
 
 /** Generate a unique 8-character hex task ID */
 function generateTaskId() {
@@ -117,13 +118,11 @@ function buildMcpConfig(options) {
     }
   }
 
-  // Always exclude the sidecar itself to prevent recursive spawning.
-  // When launched from Cowork, the discovered MCP list includes "sidecar"
-  // which would cause an infinite spawn loop.
-  if (mcpServers && mcpServers.sidecar) {
-    delete mcpServers.sidecar;
-    logger.debug('Auto-excluded sidecar MCP (recursive spawn prevention)');
-  }
+  // Always exclude amicus itself — under ANY registered name or aliased
+  // invocation — to prevent recursive spawning. When launched from Cowork or
+  // Claude Code the discovered list includes 'amicus'/'sidecar' (and possibly
+  // a user alias), which would cause an infinite spawn loop.
+  if (mcpServers) { stripSelfMcpEntries(mcpServers, logger); }
 
   // Apply explicit exclusions
   if (excludeMcp && Array.isArray(excludeMcp) && mcpServers) {

package/src/utils/abort-coordinator.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Marker-first abort coordination (Phase 3 abort overhaul).
+ *
+ * Contract: the caller writes the metadata marker (status='aborted') FIRST,
+ * gives the running process a grace window to honor it (the headless loop and
+ * the interactive abort watch both poll metadata every ~2s and tear down
+ * gracefully — mirror flush, usage persist, server-side abortSession), and
+ * only SIGTERMs a process that is STILL alive after the grace window.
+ *
+ * Windows: process.kill() is TerminateProcess — no handlers run — but libuv
+ * job objects kill non-detached children with the parent, so the fallback
+ * kill still reaps the tree. The grace window is what keeps the common path
+ * graceful.
+ */
+
+const { logger } = require('./logger');
+
+/**
+ * Grace window before the fallback SIGTERM. Env-overridable (tests).
+ * AMICUS_ABORT_GRACE_MS='0' is treated as UNSET and falls back to the 5000ms
+ * default — Number.isFinite(0) && 0 > 0 is false, so an explicit "no grace"
+ * is not currently expressible via this env var (adjudicated deviation, 3.3).
+ */
+function abortGraceMs() {
+  const n = Number(process.env.AMICUS_ABORT_GRACE_MS);
+  return (Number.isFinite(n) && n > 0) ? n : 5000;
+}
+
+/**
+ * @returns {boolean} true when a process with this pid exists. EPERM means
+ * the pid exists but the caller lacks permission to signal it — that's
+ * ALIVE, not dead; only ESRCH (and other non-EPERM errors) mean dead.
+ */
+function isAlive(pid, kill = process.kill.bind(process)) {
+  if (!pid) { return false; }
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM' ? true : false;
+  }
+}
+
+/** SIGTERM a pid, swallowing ESRCH. @returns {boolean} signal was sent */
+function killPidBestEffort(pid, kill = process.kill.bind(process)) {
+  if (!pid) { return false; }
+  try { kill(pid, 'SIGTERM'); return true; } catch (err) {
+    if (err.code !== 'ESRCH') {
+      logger.warn('Failed to kill process', { pid, error: err.message });
+    }
+    return false;
+  }
+}
+
+/**
+ * Wait up to graceMs for the pids to exit on their own (marker-honoring
+ * teardown), then SIGTERM any survivor. Early-exits as soon as every target
+ * is gone, so a process that honors the marker in ~2s never sees a signal.
+ *
+ * NOTE: the poll timer is deliberately REF'D. The CLI awaits this call and
+ * must stay alive through the grace window; callers that must not block
+ * (MCP handler) fire-and-forget the returned promise instead.
+ *
+ * @param {number|null|Array<number|null>} pids
+ * @param {{graceMs?:number, pollMs?:number, deps?:{kill?:Function, sleep?:Function}}} [opts]
+ * @returns {Promise<{killed:number[], exited:number[]}>}
+ */
+async function waitThenKill(pids, opts = {}) {
+  const graceMs = opts.graceMs !== undefined ? opts.graceMs : abortGraceMs();
+  const pollMs = opts.pollMs || 250;
+  const deps = opts.deps || {};
+  const kill = deps.kill || process.kill.bind(process);
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+
+  const targets = [...new Set((Array.isArray(pids) ? pids : [pids]).filter(Boolean))];
+  const deadline = Date.now() + graceMs;
+  let remaining = targets.filter((pid) => isAlive(pid, kill));
+  while (remaining.length > 0 && Date.now() < deadline) {
+    await sleep(pollMs);
+    remaining = remaining.filter((pid) => isAlive(pid, kill));
+  }
+  const killed = remaining.filter((pid) => killPidBestEffort(pid, kill));
+  return {
+    killed,
+    exited: targets.filter((pid) => !remaining.includes(pid)),
+  };
+}
+
+module.exports = { abortGraceMs, isAlive, killPidBestEffort, waitThenKill };

package/src/utils/error-doc.js

@@ -48,6 +48,9 @@ function failJson(useJson, { code, message, hint = null, command = null }) {
     process.stdout.write(JSON.stringify(buildErrorDoc({ code, message, hint, command }), null, 2) + '\n');
   } else {
     process.stderr.write(message + '\n');
+    // Parity with --json (whose envelope carries error.hint): surface the
+    // actionable hint to humans too, in doctor's arrow style.
+    if (hint) { process.stderr.write(`  → ${hint}\n`); }
   }
   return 1;
 }