amicus 1.7.7 → 1.8.0

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/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/legacy-mcp-migration.js

@@ -0,0 +1,119 @@
+// src/utils/legacy-mcp-migration.js
+'use strict';
+
+/**
+ * Legacy 'sidecar' MCP registration cleanup (Phase 4 tool de-bloat).
+ *
+ * Through v1.7.x scripts/postinstall.js registered the SAME stdio MCP server
+ * under two names — 'amicus' and legacy 'sidecar' — in Claude Code
+ * (~/.claude.json) and Claude Desktop/Cowork (claude_desktop_config.json).
+ * Combined with the in-server sidecar_* tool aliases this quadrupled the
+ * client-visible tool surface (13 real tools -> 52).
+ *
+ * This module removes a legacy 'sidecar' server entry, but ONLY when it is
+ * identical-in-effect to the amicus registration: its command must resolve to
+ * an amicus MCP invocation per isAmicusMcpConfig() (./mcp-self-identity,
+ * Phase 1). A 'sidecar' entry pointing anywhere else is user customization
+ * and is NEVER touched.
+ *
+ * Consumers: scripts/postinstall.js (one-shot migration on install/upgrade)
+ * and src/cli-handlers-doctor.js (duplicate check + `doctor --fix`).
+ * All functions are synchronous, never throw, and report via return values.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { writeFileAtomic } = require('./atomic-write');
+
+/** ~/.claude.json — where BOTH Claude Code registration paths (CLI + file fallback) land. */
+function claudeCodeConfigPath() {
+  return path.join(os.homedir(), '.claude.json');
+}
+
+/** claude_desktop_config.json — platform-aware; mirrors postinstall registerClaudeDesktop. */
+function claudeDesktopConfigPath() {
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+  }
+  return path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json');
+}
+
+function defaultTargets(deps = {}) {
+  return [
+    { target: 'Claude Code', configPath: deps.codePath || claudeCodeConfigPath() },
+    { target: 'Claude Desktop', configPath: deps.desktopPath || claudeDesktopConfigPath() },
+  ];
+}
+
+/**
+ * Inspect one config file for a legacy 'sidecar' MCP entry.
+ * @returns {{status:'absent'|'removable'|'customized'|'unreadable', config?:object}}
+ */
+function inspectLegacySidecarEntry(configPath, deps = {}) {
+  const isAmicus = deps.isAmicusMcpConfig
+    || require('./mcp-self-identity').isAmicusMcpConfig;
+  let parsed;
+  try {
+    if (!fs.existsSync(configPath)) { return { status: 'absent' }; }
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    return { status: 'unreadable' };
+  }
+  const entry = parsed && parsed.mcpServers ? parsed.mcpServers.sidecar : undefined;
+  if (!entry) { return { status: 'absent' }; }
+  // 'removable' means VERIFIED duplicate, not just amicus-shaped. Two edges
+  // must fall back to 'customized' (left alone) instead:
+  //  (a) no 'amicus' twin present — this may be the user's ONLY working
+  //      registration (scripts-skipped / manual pre-rebrand install); deleting
+  //      it would leave them with nothing.
+  //  (b) the sidecar entry carries a non-empty `env` (API keys,
+  //      AMICUS_LEGACY_ALIASES itself) — not identical-in-effect to the bare
+  //      'amicus' entry, so removing it would silently lose configuration.
+  const hasAmicusTwin = !!(parsed.mcpServers && parsed.mcpServers.amicus);
+  const hasNonEmptyEnv = !!(entry.env && typeof entry.env === 'object' && Object.keys(entry.env).length > 0);
+  if (!hasAmicusTwin || hasNonEmptyEnv) { return { status: 'customized', config: entry }; }
+  return isAmicus(entry)
+    ? { status: 'removable', config: entry }
+    : { status: 'customized', config: entry };
+}
+
+/**
+ * Remove the legacy 'sidecar' entry from one config file — ONLY when it is an
+ * amicus self-invocation. Preserves every other key in the file.
+ * @returns {'absent'|'removed'|'customized'|'unreadable'|'write-failed'}
+ */
+function removeLegacySidecarEntry(configPath, deps = {}) {
+  const inspected = inspectLegacySidecarEntry(configPath, deps);
+  if (inspected.status !== 'removable') { return inspected.status; }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    delete parsed.mcpServers.sidecar;
+    // Atomic temp+rename write — a crash mid-write must never corrupt the
+    // user's main Claude Code state file. 0o600 is a no-op on NTFS; kept for
+    // parity with addMcpToConfigFile.
+    writeFileAtomic(configPath, JSON.stringify(parsed, null, 2), { mode: 0o600 });
+    return 'removed';
+  } catch {
+    return 'write-failed';
+  }
+}
+
+/** Inspect every known registry (doctor check). */
+function inspectAllLegacySidecarEntries(deps = {}) {
+  return defaultTargets(deps).map((t) => ({ ...t, ...inspectLegacySidecarEntry(t.configPath, deps) }));
+}
+
+/** Remove identical-in-effect legacy entries everywhere. Idempotent. */
+function migrateLegacySidecar(deps = {}) {
+  return defaultTargets(deps).map((t) => ({ ...t, result: removeLegacySidecarEntry(t.configPath, deps) }));
+}
+
+module.exports = {
+  claudeCodeConfigPath, claudeDesktopConfigPath,
+  inspectLegacySidecarEntry, removeLegacySidecarEntry,
+  inspectAllLegacySidecarEntries, migrateLegacySidecar,
+};

package/src/utils/lifecycle.js

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

package/src/utils/remediation-hints.js

@@ -64,6 +64,14 @@ const REMEDIATION_HINTS = Object.freeze({
    * can't loop the way `npm install -g amicus` could when the rollback recurs.
    */
   doctorFix: 'amicus doctor --fix  (self-heal the Electron GUI in place — provisions the binary; no reinstall, so it can\'t loop)',
+
+  /**
+   * Duplicate legacy 'sidecar' MCP registration (Phase 4 de-bloat): pre-1.8
+   * postinstalls registered the same server twice. `doctor --fix` removes the
+   * twin only when it points at amicus; a customized entry is never touched.
+   */
+  removeLegacySidecar:
+    "amicus doctor --fix  (removes the duplicate legacy 'sidecar' MCP entry — same server registered twice; the 'amicus' entry stays)",
 });
 
 module.exports = REMEDIATION_HINTS;