ashlr-plugin 1.36.4 → 1.37.1

package/scripts/doctor.ts

@@ -10,11 +10,15 @@
  * signatures stable.
  */
 
+import { describePhantomExec, detectPhantomExec } from "../servers/_phantom-exec.ts";
+import { type CompanionResult, type CompanionRunner, detectCompanions } from "../servers/_companions.ts";
+import { preflightMode, runPhantomPreflight, type PreflightRunner } from "../servers/_phantom-preflight.ts";
 import { spawn } from "bun";
+import { runWithTimeout } from "../servers/_run-with-timeout.ts";
 import { existsSync, statSync } from "fs";
 import { readFile } from "fs/promises";
 import { devNull, homedir } from "os";
-import { dirname, join, resolve } from "path";
+import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { c, sym, box, isColorEnabled } from "./ui.ts";
 import { bunBinaryOnDisk } from "./bun-resolve.mjs";
@@ -23,7 +27,8 @@ import { selectProvider } from "../servers/_llm-providers/index.ts";
 import { proTokenCachePath, isProAssumeEnabled } from "../servers/_pro.ts";
 import { getDoctorHookHealth } from "./hook-timings-report.ts";
 
-export type Status = "ok" | "warn" | "fail";
+/** `info` is shown with its fix hint but never counted as a warning or failure. */
+export type Status = "ok" | "warn" | "fail" | "info";
 export interface Line {
   status: Status;
   label: string;
@@ -37,11 +42,44 @@ export interface Section {
 export interface Report {
   header: string;
   sections: Section[];
+  companions: CompanionResult[];
   warnings: number;
   failures: number;
 }
 
-const GLYPH: Record<Status, string> = { ok: sym.check, warn: sym.warn, fail: sym.cross };
+/**
+ * The shared `ashlr.doctor` v1 wrapper (ashlr-stack docs/ashlr-handshake.md,
+ * "Doctor JSON") for `--json`. Additive: header, sections, companions,
+ * warnings and failures stay, and the exit code does not change. Mapping:
+ * failures > 0 is fail, else warnings > 0 is warn. `checks` flatten the
+ * section lines (`id` is the section and label in kebab case).
+ */
+export function withDoctorEnvelope(report: Report) {
+  const kebab = (s: string) =>
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "check";
+  const checks = report.sections.flatMap((sec) =>
+    sec.lines.map((l) => ({
+      id: kebab(`${sec.title}-${l.label}`),
+      status: l.status,
+      summary: l.detail ? `${l.label}: ${l.detail}` : l.label,
+    })),
+  );
+  const status = report.failures > 0 ? "fail" : report.warnings > 0 ? "warn" : "ok";
+  return {
+    ...report,
+    kind: "ashlr.doctor" as const,
+    schema_version: 1 as const,
+    tool: "ashlr-plugin",
+    status,
+    native_status: report.failures > 0 ? "failures" : report.warnings > 0 ? "warnings" : "ok",
+    checks,
+  };
+}
+
+const GLYPH: Record<Status, string> = { ok: sym.check, warn: sym.warn, fail: sym.cross, info: sym.dot };
 
 /** Colored glyph for TTY rendering; falls back to the plain glyph otherwise. */
 function coloredGlyph(status: Status): string {
@@ -49,6 +87,7 @@ function coloredGlyph(status: Status): string {
   if (!isColorEnabled()) return g;
   if (status === "ok") return c.green(g);
   if (status === "warn") return c.yellow(g);
+  if (status === "info") return c.dim(g);
   return c.red(g);
 }
 
@@ -108,10 +147,22 @@ export interface ProbeResult {
   error?: string;
 }
 
+/**
+ * The bun binary to run probes with. Prefer the binary running doctor right
+ * now (`process.execPath`) over a PATH lookup: a PATH `bun` can be a shell
+ * shim that runs the real binary as a grandchild. Falls back to "bun" when
+ * doctor itself is not running under bun.
+ */
+export function realBunBinary(execPath: string = process.execPath): string {
+  const base = basename(execPath).toLowerCase();
+  return base === "bun" || base === "bun.exe" || base.startsWith("bun-") ? execPath : "bun";
+}
+
 export async function probeServer(
   name: string,
   scriptPath: string,
   perServerTimeoutMs = 2000,
+  signal?: AbortSignal,
 ): Promise<ProbeResult> {
   if (!existsSync(scriptPath)) {
     return { server: name, ok: false, tools: [], error: "server script missing" };
@@ -125,34 +176,20 @@ export async function probeServer(
   const listReq = { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} };
   const payload = JSON.stringify(initReq) + "\n" + JSON.stringify(listReq) + "\n";
 
-  const proc = spawn({
-    cmd: ["bun", "run", scriptPath],
-    stdin: "pipe",
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env },
+  // runWithTimeout spawns the probe in its own process group and kills the
+  // whole group on timeout or abort. `proc.kill()` on a Bun.spawn child only
+  // reached the direct child, so when `bun` on PATH is a shell shim (pnpm and
+  // npm global installs) the real bun ran as a grandchild and survived,
+  // spinning at full CPU long after doctor or the test runner exited.
+  const res = await runWithTimeout({
+    command: realBunBinary(),
+    args: ["run", scriptPath],
+    env: { ...process.env } as Record<string, string>,
+    input: payload,
+    timeoutMs: perServerTimeoutMs,
+    signal,
   });
-
-  const timer = setTimeout(() => {
-    try { proc.kill(); } catch {}
-  }, perServerTimeoutMs);
-
-  try {
-    proc.stdin.write(payload);
-    await proc.stdin.end();
-  } catch {
-    // proc may already be dead
-  }
-
-  let out = "";
-  try {
-    out = await new Response(proc.stdout).text();
-  } catch {
-    // stream errored
-  }
-  // best-effort: we've already captured stdout and only need the process to settle; exit-code and signal reasons are not used in the probe.
-  await proc.exited.catch(() => {});
-  clearTimeout(timer);
+  const out = res.stdout;
 
   const tools: string[] = [];
   let sawListResult = false;
@@ -179,17 +216,26 @@ export async function probeAll(
   totalCapMs = 5000,
   perServerTimeoutMs = 2000,
 ): Promise<ProbeResult[]> {
-  const work = Promise.all(servers.map((s) => probeServer(s.name, s.script, perServerTimeoutMs)));
-  const cap = new Promise<ProbeResult[]>((resolveP) =>
-    setTimeout(
-      () =>
-        resolveP(
-          servers.map((s) => ({ server: s.name, ok: false, tools: [], error: "total probe cap exceeded" })),
-        ),
-      totalCapMs,
-    ),
+  // When the total cap wins the race, abort every probe still running so no
+  // server process (or its descendants) outlives this call.
+  const abort = new AbortController();
+  const work = Promise.all(
+    servers.map((s) => probeServer(s.name, s.script, perServerTimeoutMs, abort.signal)),
   );
-  return await Promise.race([work, cap]);
+  let capTimer: ReturnType<typeof setTimeout> | undefined;
+  const cap = new Promise<ProbeResult[]>((resolveP) => {
+    capTimer = setTimeout(() => {
+      abort.abort();
+      resolveP(
+        servers.map((s) => ({ server: s.name, ok: false, tools: [], error: "total probe cap exceeded" })),
+      );
+    }, totalCapMs);
+  });
+  try {
+    return await Promise.race([work, cap]);
+  } finally {
+    clearTimeout(capTimer);
+  }
 }
 
 // ---------- project hint check ----------
@@ -299,6 +345,25 @@ export interface CloudPingResult {
   error?: string;
 }
 
+/**
+ * Metadata-only probe for the optional Phantom CLI. Runs `phantom --version`
+ * and nothing else: it never runs reveal, never reads the vault or .env
+ * files, and never touches secret values. Returns the first line of output,
+ * or null when the binary is missing or fails.
+ */
+export async function getPhantomVersion(bin = "phantom"): Promise<string | null> {
+  try {
+    const proc = spawn([bin, "--version"], { stdout: "pipe", stderr: "ignore", stdin: "ignore" });
+    const out = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    if (code !== 0) return null;
+    const line = out.trim().split("\n")[0]?.trim();
+    return line ? line.slice(0, 80) : null;
+  } catch {
+    return null;
+  }
+}
+
 export interface BuildOpts {
   root: string;
   home?: string;
@@ -309,6 +374,14 @@ export interface BuildOpts {
   probe?: (servers: Array<{ name: string; script: string }>) => Promise<ProbeResult[]>;
   bunVersion?: () => Promise<string | null>;
   bunOffPath?: () => Promise<string | null>;
+  /** Override for testing the phantom check (returns version string or null). */
+  phantomVersion?: () => Promise<string | null>;
+  /** Environment to inspect for a phantom exec session (defaults to process.env). */
+  env?: Record<string, string | undefined>;
+  /** Runner for the opt-in `phantom agent doctor --json --strict` preflight (tests). */
+  phantomPreflight?: PreflightRunner;
+  /** Runner for the `--ashlr-handshake` companion probes (tests). */
+  companionRunner?: CompanionRunner;
   /** Override for testing cloud ping without real network calls */
   pingCloud?: (url: string, timeoutMs: number) => Promise<CloudPingResult>;
 }
@@ -376,6 +449,7 @@ export async function buildReport(opts: BuildOpts): Promise<Report> {
   const probe = opts.probe ?? ((servers) => probeAll(servers));
   const bunVersionFn = opts.bunVersion ?? getBunVersion;
   const bunOffPathFn = opts.bunOffPath ?? getBunOffPath;
+  const phantomVersionFn = opts.phantomVersion ?? (() => getPhantomVersion());
 
   const plugin = await readPluginJson(root);
   const currentVersion = plugin?.version ?? "unknown";
@@ -445,8 +519,59 @@ export async function buildReport(opts: BuildOpts): Promise<Report> {
       detail: `@modelcontextprotocol/sdk@${mcpSdkPkg.version ?? "?"} · @ashlr/core-efficiency@${corePkg.version ?? "?"}`,
     });
   }
+  // Optional Phantom CLI: presence and version only, never secret values.
+  const phantomVersion = await phantomVersionFn();
+  install.push(
+    phantomVersion
+      ? { status: "ok", label: "phantom", detail: `${phantomVersion} (installed; run tools via \`phantom exec -- <cmd>\`)` }
+      : { status: "ok", label: "phantom", detail: "not installed (optional)" },
+  );
+  // Value-free: names, phm prefixes and proxy host/port only; never reveals.
+  {
+    const pe = detectPhantomExec(opts.env ?? process.env);
+    install.push({
+      status: pe.warnings.length ? "warn" : "ok",
+      label: "phantom exec",
+      detail: describePhantomExec(pe),
+      ...(pe.warnings.length ? { fix: pe.warnings.join(" ") } : {}),
+    });
+  }
+  // Opt-in (ASHLR_PHANTOM_PREFLIGHT=1 or strict): Phantom's value-free agent
+  // preflight. Verdict and check ids only.
+  {
+    const pf = runPhantomPreflight(preflightMode(opts.env ?? process.env), opts.phantomPreflight);
+    if (pf) {
+      install.push({
+        status: pf.status,
+        label: "phantom preflight",
+        detail: pf.detail,
+        ...(pf.status !== "ok" ? { fix: "run `phantom agent doctor` for details and fix commands" } : {}),
+      });
+    }
+  }
   sections.push({ title: "install", lines: install });
 
+  // ----- ashlr companions (informational, never warn/fail) -----
+  const companions = await detectCompanions(opts.companionRunner);
+  sections.push({
+    title: "companions",
+    lines: companions.map((cmp): Line => {
+      const caps = cmp.capabilities.length ? ` [${cmp.capabilities.join(", ")}]` : "";
+      const detail =
+        cmp.state === "ready" ? `${cmp.version ?? "?"} ready${caps}`
+        : cmp.state === "degraded" ? `${cmp.version ?? "?"} health: ${cmp.health ?? "unknown"}${caps}`
+        : cmp.state === "outdated" ? "installed, too old for --ashlr-handshake"
+        : cmp.state === "unknown" ? "installed, handshake unreadable or timed out"
+        : "not installed";
+      return {
+        status: cmp.state === "ready" ? "ok" : "info",
+        label: cmp.name,
+        detail,
+        ...(cmp.fix ? { fix: cmp.fix } : {}),
+      };
+    }),
+  });
+
   // ----- mcp servers -----
   const servers = [
     { name: "efficiency", script: join(root, "servers/efficiency-server.ts") },
@@ -818,7 +943,7 @@ export async function buildReport(opts: BuildOpts): Promise<Report> {
           detail = `provider: onnx (offline summarizer)${overrideNote}`;
           break;
         case "local":
-          detail = `provider: local (${process.env.ASHLR_LLM_URL ?? "http://localhost:1234/v1"})${overrideNote}`;
+          detail = `provider: local (${process.env.ASHLR_LLM_URL ?? "http://127.0.0.1:1234/v1"})${overrideNote}`;
           break;
         case "none":
         default:
@@ -917,7 +1042,7 @@ export async function buildReport(opts: BuildOpts): Promise<Report> {
     }
   }
 
-  return { header, sections, warnings, failures };
+  return { header, sections, companions, warnings, failures };
 }
 
 // ---------- formatting ----------
@@ -983,6 +1108,10 @@ async function main(): Promise<number> {
     return 2;
   }
   const report = await buildReport({ root });
+  if (process.argv.includes("--json")) {
+    process.stdout.write(JSON.stringify(withDoctorEnvelope(report), null, 2) + "\n");
+    return report.failures > 0 ? 1 : 0;
+  }
   process.stdout.write(formatReport(report) + "\n");
   return report.failures > 0 ? 1 : 0;
 }

package/scripts/genome-auto-consolidate.ts

@@ -30,12 +30,14 @@ import {
   writeFileSync,
 } from "fs";
 import { homedir } from "os";
+import { anthropicBaseUrl, openaiBaseUrl } from "../servers/_base-urls.ts";
 import { dirname, join, resolve } from "path";
 // Imported for API-surface parity with the MCP server; the auto-consolidator
 // uses the direct-fallback path so it stays offline and deterministic.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { consolidateProposals } from "@ashlr/core-efficiency/genome";
 import { summarizeIfLarge as _summarizeIfLargeImpl, PROMPTS, type SummarizeResult, type SummarizeOpts } from "../servers/_summarize";
+import { safeKeyedFetch } from "../servers/_gateway-target.ts";
 
 // Mutable hook container so tests can inject stubs:
 //   _hooks.summarizeIfLarge  — controls LLM synthesis
@@ -77,7 +79,7 @@ async function isLlmReachable(): Promise<boolean> {
   // ANTHROPIC_API_KEY — probe the models endpoint
   if (process.env["ANTHROPIC_API_KEY"]) {
     try {
-      const res = await fetch("https://api.anthropic.com/v1/models", {
+      const res = await safeKeyedFetch(`${anthropicBaseUrl()}/v1/models`, {
         method: "GET",
         headers: { "x-api-key": process.env["ANTHROPIC_API_KEY"]!, "anthropic-version": "2023-06-01" },
         signal: AbortSignal.timeout(2_000),
@@ -91,7 +93,7 @@ async function isLlmReachable(): Promise<boolean> {
   // OPENAI_API_KEY — probe the models endpoint
   if (process.env["OPENAI_API_KEY"]) {
     try {
-      const res = await fetch("https://api.openai.com/v1/models", {
+      const res = await safeKeyedFetch(`${openaiBaseUrl()}/models`, {
         method: "GET",
         headers: { "Authorization": `Bearer ${process.env["OPENAI_API_KEY"]!}` },
         signal: AbortSignal.timeout(2_000),

package/scripts/genome-init.ts

@@ -24,6 +24,7 @@ import {
   writeSection,
 } from "@ashlr/core-efficiency/genome";
 import { scan, type Baseline } from "./baseline-scan.ts";
+import { ollamaBaseUrl } from "../servers/_base-urls.ts";
 import { Spinner, ProgressBar, c, sym, isColorEnabled } from "./ui.ts";
 
 // ---------------------------------------------------------------------------
@@ -214,7 +215,6 @@ export interface WorkspaceGraph {
 // Local model summarization (Ollama)
 // ---------------------------------------------------------------------------
 
-const OLLAMA_BASE_URL = "http://localhost:11434";
 const OLLAMA_TIMEOUT_MS = 2000;
 const OLLAMA_GENERATE_TIMEOUT_MS = 30000;
 /** Max chars of CLAUDE.md to pass to the LLM. Avoids loading huge files. */
@@ -234,7 +234,7 @@ async function resolveOllamaModel(): Promise<string | null> {
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), OLLAMA_TIMEOUT_MS);
-    const res = await fetch(`${OLLAMA_BASE_URL}/api/tags`, {
+    const res = await fetch(`${ollamaBaseUrl()}/api/tags`, {
       signal: controller.signal,
     });
     clearTimeout(timer);
@@ -269,7 +269,7 @@ async function summarizeWithOllama(
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), OLLAMA_GENERATE_TIMEOUT_MS);
-    const res = await fetch(`${OLLAMA_BASE_URL}/api/chat`, {
+    const res = await fetch(`${ollamaBaseUrl()}/api/chat`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({

package/scripts/genome-key.ts

@@ -5,12 +5,14 @@
  * Usage:
  *   bun run scripts/genome-key.ts generate <genomeId>
  *   bun run scripts/genome-key.ts export   <genomeId>
- *   bun run scripts/genome-key.ts import   <genomeId> <base32>
+ *   bun run scripts/genome-key.ts import   <genomeId>          (key from stdin: paste, or pipe it)
  *   bun run scripts/genome-key.ts rotate   <genomeId>
  *
  * Keys are stored at ~/.ashlr/team-keys/<genomeId>.key (mode 0600, 32 raw bytes).
  * Export/import uses base32 (RFC 4648) for human-friendly sharing over Signal,
- * 1Password, etc.
+ * 1Password, etc. `import` reads the key from stdin (hidden when typed or
+ * pasted at a terminal) so it never lands in argv or shell history. A key
+ * given as a third argument still works but prints a warning.
  *
  * Key rotation procedure:
  *   1. Reads all sections from the remote genome via the API.
@@ -75,6 +77,50 @@ async function promptConfirm(question: string): Promise<boolean> {
   });
 }
 
+/**
+ * Read one key line from stdin. At a terminal the input is not echoed (raw
+ * mode); piped input is read to the first newline. The key never touches
+ * argv, the environment or any output.
+ */
+async function readKeyFromStdin(): Promise<string> {
+  const stdin = process.stdin;
+  const tty = stdin.isTTY === true && typeof stdin.setRawMode === "function";
+  if (tty) process.stderr.write("Paste the team genome key, then press Enter (input is hidden): ");
+  return new Promise((resolve) => {
+    let buf = "";
+    const finish = () => {
+      stdin.removeListener("data", onData);
+      stdin.removeListener("end", finish);
+      if (tty) {
+        stdin.setRawMode(false);
+        process.stderr.write("\n");
+      }
+      stdin.pause();
+      resolve(buf.trim());
+    };
+    const onData = (chunk: Buffer | string) => {
+      for (const ch of String(chunk)) {
+        if (ch === "\n" || ch === "\r") return finish();
+        if (tty && ch === "\u0003") {
+          stdin.setRawMode(false);
+          process.stderr.write("\n");
+          process.exit(130);
+        }
+        if (tty && (ch === "\u007f" || ch === "\b")) {
+          buf = buf.slice(0, -1);
+          continue;
+        }
+        buf += ch;
+      }
+    };
+    if (tty) stdin.setRawMode(true);
+    stdin.setEncoding("utf-8");
+    stdin.on("data", onData);
+    stdin.once("end", finish);
+    stdin.resume();
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -109,7 +155,8 @@ async function cmdExport(genomeId: string): Promise<void> {
   info("=====================================");
   info("");
   info("Share this with team members. They import it with:");
-  info(`  bun run scripts/genome-key.ts import ${genomeId} <key>`);
+  info(`  bun run scripts/genome-key.ts import ${genomeId}`);
+  info("  (then paste the key; or pipe it in, e.g. from a password manager CLI)");
 }
 
 async function cmdImport(genomeId: string, base32Key: string): Promise<void> {
@@ -117,7 +164,9 @@ async function cmdImport(genomeId: string, base32Key: string): Promise<void> {
   try {
     key = decodeBase32(base32Key);
   } catch (err) {
-    die(`Invalid base32 key: ${String(err)}`);
+    // The decoder's message quotes the offending character; never echo key material.
+    void err;
+    die("Invalid base32 key. Make sure you copied the full key.");
   }
   if (key.length !== 32) {
     die(`Key must be 32 bytes when decoded (got ${key.length}). Make sure you copied the full key.`);
@@ -206,7 +255,7 @@ if (!command || !genomeId) {
     "Usage:\n" +
     "  bun run scripts/genome-key.ts generate <genomeId>\n" +
     "  bun run scripts/genome-key.ts export   <genomeId>\n" +
-    "  bun run scripts/genome-key.ts import   <genomeId> <base32>\n" +
+    "  bun run scripts/genome-key.ts import   <genomeId>   (key from stdin)\n" +
     "  bun run scripts/genome-key.ts rotate   <genomeId>\n",
   );
   process.exit(1);
@@ -220,8 +269,16 @@ switch (command) {
     await cmdExport(genomeId);
     break;
   case "import": {
-    const b32 = rest[0];
-    if (!b32) die("Missing base32 key argument.");
+    let b32 = rest[0];
+    if (b32) {
+      process.stderr.write(
+        "warning: a key passed as an argument is visible to other local users (ps) and is kept in shell history. " +
+        `Next time run \`bun run scripts/genome-key.ts import ${genomeId}\` and paste or pipe the key on stdin.\n`,
+      );
+    } else {
+      b32 = await readKeyFromStdin();
+    }
+    if (!b32) die("No key given. Paste the key, or pipe it on stdin.");
     await cmdImport(genomeId, b32);
     break;
   }

package/scripts/handshake.mjs

@@ -0,0 +1,51 @@
+/**
+ * Ashlr companion handshake v1 (`ashlr-plugin --ashlr-handshake`): one JSON
+ * object naming the plugin, its protocols and capabilities, local health and
+ * the files it may edit, so `phm companions` / `phm doctor` stop guessing
+ * from `--help`. Contract: docs/ashlr-handshake.md (shared with ashlr-stack
+ * and locus).
+ *
+ * Answered by the node launcher before it looks for bun, so it works (and
+ * reports bun as missing) on a machine without bun. No network, no token
+ * files read, no secret values.
+ */
+
+/**
+ * @param {string} version
+ * @param {{ bun: boolean, phantom: boolean }} found
+ */
+export function buildHandshake(version, found) {
+	return {
+		kind: "ashlr.handshake",
+		schema_version: 1,
+		name: "ashlr-plugin",
+		command: "ashlr-plugin",
+		version,
+		protocols: { "ashlr.handshake": 1, "phantom.agent.preflight": 1 },
+		capabilities: [
+			"token-efficient-tools",
+			"mcp-server",
+			"claude-code-plugin",
+			"codex-install",
+			"savings-stats",
+			"agent-preflight",
+			"doctor",
+		],
+		health: {
+			status: found.bun ? "ok" : "degraded",
+			checks: [
+				// The CLI, hooks and MCP server run under bun.
+				{ id: "bun-on-path", status: found.bun ? "ok" : "missing" },
+				// Only ASHLR_PHANTOM_PREFLIGHT needs it.
+				{ id: "phantom-on-path", status: found.phantom ? "ok" : "absent" },
+			],
+		},
+		edits: ["~/.ashlr/", "~/.claude/settings.json", "~/.codex/config.toml"],
+		receipts: [],
+	};
+}
+
+/** True when argv (without node and the script) asks for the handshake. */
+export function wantsHandshake(argv) {
+	return argv.includes("--ashlr-handshake");
+}