nomarmy 0.1.0-alpha.2 → 0.1.0-alpha.21

package/lib/sandbox-vm.mjs

@@ -0,0 +1,32 @@
+// `nomarmy sandbox`: the Podman VM every sandbox, verification run and image
+// build shares on macOS and Windows (on Linux, Podman runs natively and
+// there's no VM to size). Pure decisions here; bin/nomarmy.mjs runs Podman.
+
+import { MIN_PODMAN_VM_MB } from "./doctor.mjs";
+
+/** The machine to act on from `podman machine inspect` output: the running one, else the first. */
+export function pickMachine(inspectJson) {
+  let machines;
+  try { machines = JSON.parse(inspectJson || "[]"); } catch { return null; }
+  if (!Array.isArray(machines) || !machines.length) return null;
+  const m = machines.find((x) => x.State === "running") ?? machines[0];
+  return { name: m.Name ?? null, state: m.State ?? null, cpus: m.Resources?.CPUs ?? null, memoryMb: Number(m.Resources?.Memory) || null, diskGb: m.Resources?.DiskSize ?? null };
+}
+
+/**
+ * What resizing the VM to `gib` would do, or why it won't.
+ * @returns {{ ok: boolean, problems: string[], warnings: string[], memoryMb: number, commands: string[][] }}
+ */
+export function planResize({ gib, machine, hostMemoryMb, runningJobs = 0 }) {
+  const problems = [], warnings = [];
+  const memoryMb = Math.round(Number(gib) * 1024);
+  if (!machine) problems.push("no Podman machine found: run `podman machine init`, or on Linux there's no VM to size");
+  if (!Number.isFinite(memoryMb) || memoryMb <= 0 || !Number.isInteger(Number(gib))) problems.push(`--memory takes a whole number of GiB (got "${gib}")`);
+  else if (memoryMb < MIN_PODMAN_VM_MB) problems.push(`${gib} GiB is below the ${MIN_PODMAN_VM_MB / 1024} GiB nomArmy needs`);
+  else if (hostMemoryMb && memoryMb > hostMemoryMb * 0.75) problems.push(`${gib} GiB is more than three quarters of this machine's ${Math.round(hostMemoryMb / 1024)} GiB`);
+  else if (hostMemoryMb && memoryMb > hostMemoryMb / 2) warnings.push(`${gib} GiB is more than half of this machine's ${Math.round(hostMemoryMb / 1024)} GiB; a local model needs room too`);
+  if (runningJobs > 0) problems.push(`${runningJobs} nomArmy job(s) are running; resizing restarts the VM and would kill their sandboxes`);
+  const name = machine?.name;
+  const commands = name ? [["machine", "stop", name], ["machine", "set", "--memory", String(memoryMb), name], ["machine", "start", name]] : [];
+  return { ok: problems.length === 0, problems, warnings, memoryMb, commands };
+}

package/lib/scan.mjs

@@ -451,6 +451,10 @@ const IGNORED_DIRS = new Set([
 // label that specific finding as sample data once it's found. Deliberately
 // narrower than "tests"/"__tests__" alone; see the comment at its call site.
 const FIXTURE_PATH_RE = /(^|\/)(fixtures?|__fixtures__|testdata|test-data)(\/|$)/i;
+export function isFixturePath(relPath) {
+  // path.relative uses backslashes on Windows, while repository paths use '/'.
+  return FIXTURE_PATH_RE.test(relPath.replaceAll("\\", "/"));
+}
 
 const GREPPABLE_EXT = new Set([
   ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts",
@@ -1392,7 +1396,7 @@ export function scanRepository(repoDir, options = {}) {
   // there, and that evidence should still be reported normally. Labeled,
   // not excluded, from the evidence itself -- this scan still answers "what
   // did you find", any narrower proposal built from it decides what to trust.
-  const fixturePaths = [...new Set(matched.filter((f) => FIXTURE_PATH_RE.test(f.relPath)).map((f) => f.relPath))];
+  const fixturePaths = [...new Set(matched.filter((f) => isFixturePath(f.relPath)).map((f) => f.relPath))];
   for (const source of fixturePaths) {
     raw.notes.push({ level: "info", message: "path looks like test fixture data, not real repository infrastructure -- excluded from any automated .nomarmy.yml proposal", source });
   }

package/lib/schema.mjs

@@ -12,6 +12,7 @@
 //     approval before the job runs. See `collectElevated`.
 
 import { z } from "zod";
+import { typeError, isMissingField, isUnknownDiscriminator } from "./zod-issues.mjs";
 import { armySchema } from "./army.mjs";
 
 export const SERVICE_SOURCES = Object.freeze([
@@ -57,12 +58,12 @@ export const SERVICE_FIELDS = Object.freeze({
 // the dotted path, so repeating it reads as stutter.
 const requiredString = () =>
   z
-    .string({ required_error: "is required", invalid_type_error: "must be a string" })
+    .string({ error: typeError("a string") })
     .refine((value) => value.trim().length > 0, { message: "must not be empty" });
 
 const enumOf = (values) =>
   z.enum(values, {
-    errorMap: () => ({ message: `must be one of ${values.join(", ")}` }),
+    error: `must be one of ${values.join(", ")}`,
   });
 
 // A plain hostname: no scheme, no path, no port, no whitespace.
@@ -90,7 +91,7 @@ export function hostnameProblem(value) {
 }
 
 const hostnameSchema = z
-  .string({ invalid_type_error: "must be a string hostname" })
+  .string({ error: typeError("a string hostname") })
   .superRefine((value, ctx) => {
     const problem = hostnameProblem(value);
     if (problem) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem });
@@ -162,7 +163,7 @@ export const serviceSchema = z.discriminatedUnion("source", [
 export const pythonEnvironmentSchema = z
   .object({
     requirements: z
-      .array(requiredString(), { invalid_type_error: "must be an array of strings" })
+      .array(requiredString(), { error: typeError("an array of strings") })
       .min(1, "must list at least one requirements file"),
   })
   .strict();
@@ -211,10 +212,7 @@ export const verificationProfileSchema = z
   .object({
     environment: enumOf(ENVIRONMENT_LEVELS).default("none"),
     commands: z
-      .array(requiredString(), {
-        required_error: "is required",
-        invalid_type_error: "must be an array of strings",
-      })
+      .array(requiredString(), { error: typeError("an array of strings") })
       .min(1, "must list at least one command"),
   })
   .strict();
@@ -235,14 +233,24 @@ export const environmentRetentionSchema = z
     debug: enumOf(RETENTION_ACTIONS).default(DEFAULT_RETENTION.debug),
   })
   .strict()
-  .default({});
+  .prefault({});
 
 // ---------------------------------------------------------------------------
 // root
 // ---------------------------------------------------------------------------
 
+// Mutation testing on the changed lines (lib/mutation.mjs): opt in per repo,
+// since every mutant costs one run of the verification profile.
+export const mutationSchema = z
+  .object({
+    mutants: z.number({ error: typeError("a number") }).int("must be a whole number").min(1, "must be at least 1").max(20, "must be at most 20").default(5),
+    max_seconds: z.number({ error: typeError("a number") }).int("must be a whole number").min(30, "must be at least 30").max(3600, "must be at most 3600").default(300),
+  })
+  .strict();
+
 export const configSchema = z
   .object({
+    harnesses: z.array(z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/)).optional(),
     environment: environmentSchema.optional(),
     verification: verificationSchema.optional(),
     environment_retention: environmentRetentionSchema,
@@ -250,6 +258,7 @@ export const configSchema = z
     // which merges it with the global and .nomarmy.local.yml layers.
     army: armySchema.optional(),
     policy: policySchema.optional(),
+    mutation: mutationSchema.optional(),
   })
   .strict();
 
@@ -294,11 +303,11 @@ export function formatIssues(error) {
       lines.push(`${where}: unexpected field(s) ${keys}`);
       continue;
     }
-    if (issue.code === "invalid_union_discriminator") {
+    if (isUnknownDiscriminator(issue)) {
       lines.push(`${where}: must be one of ${SERVICE_SOURCES.join(", ")}`);
       continue;
     }
-    if (issue.code === "invalid_type" && issue.received === "undefined") {
+    if (isMissingField(issue)) {
       lines.push(`${where}: is required`);
       continue;
     }

package/lib/scout.mjs

@@ -435,8 +435,25 @@ export function isScoutReportUnusable(report) {
  * already found -- never asks it to look further, since a fresh read pass is
  * exactly the cost a scout exists to avoid paying twice.
  */
-export function scoutReportRecoveryPrompt({ report = { targetTokens: 600, hardCapTokens: 1024 } } = {}) {
-  return `Your previous reply ended without the required SCOUT REPORT, or was cut off before reaching END.\n\nDo not repeat, redo, retry, or explore further. Do not call any tool. Based only on what you already found, reply with ONLY the report below, nothing before it, nothing after it:\n\nSCOUT REPORT\nQUESTION: <the question restated in one line>\nCONFIDENCE: high | medium | low\nFINDING: <one sentence> [src/example.js:10-24]\nNOT_FOUND: none | <what you looked for and could not find>\nEND\n\nIf you did not actually find anything worth a FINDING, say so under NOT_FOUND rather than inventing one. Target ${report.targetTokens} tokens; ${report.hardCapTokens} is the hard cap.`;
+// The recovery call carries the question itself: a reply cut off mid-run can
+// leave the resumed session without it, and a scout told only to "restate the
+// question" then came back with an empty report (a live PM scout, twice).
+// A recovery call can't count on seeing the first run's work: when OpenClaw's
+// cleanup crashes ("state ownership retained"), the follow-up starts a fresh
+// session, and a scout told "report only what you already found" came back
+// with nothing after nine minutes of real research. So the recovery carries
+// what the first run left: its cut-off reply and the files it read, which it
+// may re-read to confirm line numbers, and nothing else.
+const EARLIER_REPLY_CHARS = 12000;
+export function scoutReportRecoveryPrompt({ report = { targetTokens: 600, hardCapTokens: 1024 }, question = null, acceptance = [], earlierReply = "", filesRead = [] } = {}) {
+  const asked = question ? `\n\nThe question you were answering:\n${String(question).trim()}${acceptance?.length ? `\n\nA complete answer covers:\n${acceptance.map((a) => `- ${a}`).join("\n")}` : ""}` : "";
+  const reply = String(earlierReply ?? "").trim();
+  const earlier = reply ? `\n\nYour earlier reply, as far as it got${reply.length > EARLIER_REPLY_CHARS ? " (its last part)" : ""}:\n${reply.length > EARLIER_REPLY_CHARS ? reply.slice(-EARLIER_REPLY_CHARS) : reply}` : "";
+  const files = filesRead?.length ? `\n\nFiles you read during that work: ${filesRead.slice(0, 60).join(", ")}` : "";
+  const tools = filesRead?.length
+    ? "Do not explore further. You may re-read the files listed above to confirm exact line numbers for what you found; call no other tool."
+    : "Do not repeat, redo, retry, or explore further. Do not call any tool.";
+  return `Your previous reply ended without the required SCOUT REPORT, or was cut off before reaching END.${asked}${earlier}${files}\n\n${tools} Based on what you already found, reply with ONLY the report below, nothing before it, nothing after it:\n\nSCOUT REPORT\nQUESTION: <the question restated in one line>\nCONFIDENCE: high | medium | low\nFINDING: <one sentence> [src/example.js:10-24]\nNOT_FOUND: none | <what you looked for and could not find>\nEND\n\nIf you did not actually find anything worth a FINDING, say so under NOT_FOUND rather than inventing one. Target ${report.targetTokens} tokens; ${report.hardCapTokens} is the hard cap.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -515,7 +532,8 @@ export function renderScoutReport({ report, verified, outcome, baseSha }) {
   if (!supported.length) parts.push("  none");
   supported.forEach((f, i) => {
     const weakLabel = f.unrelated ? "  [WEAK: the cited lines do not mention this finding's terms]" : f.weak ? "  [file-level citation only]" : "";
-    parts.push(`${i + 1}. ${f.text}${weakLabel}`);
+    const jevLabel = f.jev ? `  [JEV: the cited lines may not support this (${f.jev.verdict}, ${f.jev.probability.toFixed(2)})]` : "";
+    parts.push(`${i + 1}. ${f.text}${weakLabel}${jevLabel}`);
     for (const c of f.citations) {
       if (c.status !== "ok") { parts.push(`   ${citeLabel(c)}  -- ${c.status}`); continue; }
       const fileNote = c.granularity === "file"

package/lib/server-context.mjs

@@ -1,8 +1,17 @@
 import os from "node:os";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 
+// The repository jobs run against: NOMARMY_PROJECT_DIR (set by `nomarmy
+// connect cursor` to Cursor's ${workspaceFolder}), else Claude Code's
+// CLAUDE_PROJECT_DIR, else the folder the server was started in (Claude Code
+// and Codex start it in the open project; Cursor starts a global server in
+// the home folder). A value still holding an unexpanded ${...} counts as
+// unset, and a leading ~ is the home folder (Cursor fills ${workspaceFolder}
+// in as "~/...", and nothing on the way expands it).
 export function createServerContext({ env = process.env, homedir = os.homedir(), cwd = process.cwd() } = {}) {
-  const projectDir = path.resolve(env.CLAUDE_PROJECT_DIR || cwd);
+  const fromEnv = [env.NOMARMY_PROJECT_DIR, env.CLAUDE_PROJECT_DIR].find((v) => v && !v.includes("${"));
+  const projectDir = path.resolve(fromEnv ? fromEnv.replace(/^~(?=$|[\\/])/, homedir) : cwd);
   const stateRoot = env.NOMARMY_AGENT_STATE || path.join(homedir, ".local", "share", "nomarmy-local-agents");
   const jobsRoot = path.join(stateRoot, "jobs");
   const runsRoot = path.join(stateRoot, "runs");
@@ -11,3 +20,14 @@ export function createServerContext({ env = process.env, homedir = os.homedir(),
   const slotsRoot = path.join(stateRoot, "slots");
   return Object.freeze({ projectDir, stateRoot, jobsRoot, runsRoot, leasesRoot, slotsRoot });
 }
+
+/**
+ * Why jobs can't run against projectDir, or null. Jobs need a git
+ * repository (worktrees, nomArmy's commits); anything else, like the home
+ * folder a coordinator started the server in, is refused before dispatch.
+ */
+export function projectDirProblem(projectDir, { run = (args) => spawnSync("git", args, { encoding: "utf8" }) } = {}) {
+  const result = run(["-C", projectDir, "rev-parse", "--is-inside-work-tree"]);
+  if (result.status === 0 && String(result.stdout).trim() === "true") return null;
+  return `nomArmy's project folder is ${projectDir}, which isn't a git repository, so no job was sent. The coordinator started nomArmy's server outside the project: set NOMARMY_PROJECT_DIR to the repository in its MCP settings (\`nomarmy connect cursor\` does this for Cursor), or start the coordinator from inside the repository.`;
+}

package/lib/setup-steps.mjs

@@ -0,0 +1,55 @@
+// `nomarmy setup`: the setup playbook as a checklist. Each step says whether
+// it's done and which `nomarmy` command does it; the runner shows the list,
+// runs the first unfinished step once the operator says yes, and repeats.
+// All observations are injected functions; importing this module reads no state.
+export function setupSteps(probes) {
+  const mode = probes.mode();
+  const profile = mode.profile;
+  const hosted = profile === "hosted";
+  const installation = probes.install(profile);
+  const agents = probes.agents().filter((name) => name !== "local");
+  const army = probes.army();
+  const roles = Object.values(army?.roles ?? {});
+  const rolesDone = roles.length > 0 && (!hosted || roles.every((role) => role.agent !== "local"));
+  const repo = probes.repo();
+  const step = (id, title, status, detail, command) => ({ id, title, status, detail, command });
+  const modeDetail = !profile ? "choose where models run" : profile === "remote" ? `remote ${mode.host}:${mode.port}` : ["hosted", "bedrock"].includes(profile) ? profile : `local ${profile}`;
+  const installed = installation.marker ? installation.marker.profile === profile : Boolean(installation.version && installation.registered);
+  return [
+    step("mode", "Where models run", profile ? "done" : "todo", modeDetail, ["setup", "--choose"]),
+    step("install", "Installed", installed ? "done" : "todo", installation.version || "OpenClaw not found", ["install"]),
+    step("agents", "Agents", agents.length ? "done" : hosted ? "todo" : "skipped", agents.length ? agents.join(", ") : hosted ? "add a hosted agent" : "optional: the local model works without one", ["agents", "add"]),
+    step("roles", "Roles", rolesDone ? "done" : "todo", rolesDone ? `${roles.length} role${roles.length === 1 ? "" : "s"}` : !agents.length ? (hosted ? "add an agent first" : "every role on the local model") : hosted && roles.length ? "roles must use a hosted agent" : "define an army", agents.length ? ["army", "init", "--agent", agents[0], "--force", ...(army?.repairLayer ? [`--${army.repairLayer}`] : [])] : ["army", "init", "--agent", "local", "--force"]),
+    step("repo", "This repo", !repo.inside ? "skipped" : repo.configured ? "done" : "todo", !repo.inside ? "run nomarmy setup inside a project to set it up" : repo.configured ? ".nomarmy.yml exists" : "configure this project", ["init"]),
+    step("check", "Check", "todo", "verify the installation", ["doctor"]),
+  ];
+}
+
+export function formatSetupSteps(steps) {
+  const first = steps.findIndex((step) => step.status === "todo");
+  return steps.map((step, i) => `${step.status === "done" ? "✓" : step.status === "skipped" ? "–" : i === first ? "→" : " "} ${step.title}: ${step.detail}`).join("\n");
+}
+
+export async function runSetupPlaybook({ evaluate, ask, run, print }) {
+  for (;;) {
+    const steps = await evaluate();
+    print(formatSetupSteps(steps));
+    const next = steps.find((step) => step.status === "todo");
+    if (!next) return 0;
+    const answer = (await ask(`Run \`nomarmy ${next.command.join(" ")}\` now? [Y/n] `)).trim().toLowerCase();
+    if (answer && answer !== "y" && answer !== "yes") {
+      print("Resume with: nomarmy setup");
+      return 0;
+    }
+    const code = await run(next.command);
+    if (code !== 0) {
+      print(`Setup step failed: ${next.title} (exit ${code})`);
+      return code;
+    }
+    if (next.id === "check") {
+      print("Setup complete");
+      print("Restart Claude Code in the project and ask it to use nomArmy.");
+      return 0;
+    }
+  }
+}

package/lib/share.mjs

@@ -0,0 +1,82 @@
+// Sharing what nomArmy verified, where people already look: a block for a
+// pull request's description, and a README badge. Every number comes from
+// the job records (lib/stats.mjs), never from a worker's report, so what
+// gets shared is evidence, not a claim.
+
+const REPO_URL = "https://github.com/rayson-tech/nomarmy";
+
+/** Claims that held up and those caught, from computeStats' claimVsEvidence. */
+function claims(stats) {
+  const cv = stats.claimVsEvidence;
+  const caught = cv.verificationFailed + cv.revertStillPassed;
+  return { total: cv.claimedDone, caught, held: cv.claimedDone - caught, cv };
+}
+
+/**
+ * Markdown for a pull request (or anywhere): what the workers claimed, what
+ * nomArmy caught, the tests shown to catch their change, and high-stakes
+ * reviews. `scope` names what it covers ("this feature run", "the last 7 days").
+ */
+export function shareMarkdown(stats, { scope = null } = {}) {
+  const { total, caught, held, cv } = claims(stats);
+  const rows = [];
+  if (total) {
+    const why = [cv.verificationFailed && `${cv.verificationFailed} failed when nomArmy ran the tests itself`, cv.revertStillPassed && `${cv.revertStillPassed} had tests that pass with the change reverted`].filter(Boolean).join(", ");
+    rows.push(["Worker claims checked", `${held} of ${total} "done, tests pass" claims held up${caught ? `; ${caught} caught (${why})` : ""}`]);
+  } else rows.push(["Worker claims checked", "none reported \"done, tests pass\""]);
+  if (cv.provenTestFiles) rows.push(["Tests proven", `${cv.provenTestFiles} new test file(s) shown to fail without their change`]);
+  if (stats.code?.committedJobs) rows.push(["Work committed", `${stats.code.committedJobs} verified job(s), +${stats.code.linesAdded} / -${stats.code.linesRemoved} lines`]);
+  if (stats.highStakes?.jobs) rows.push(["High-stakes changes", `${stats.highStakes.jobs}, ${stats.highStakes.reviewed === stats.highStakes.jobs ? "all" : stats.highStakes.reviewed} independently reviewed`]);
+  return [
+    `### ✓ Verified by nomArmy${scope ? ` (${scope})` : ""}`,
+    "",
+    "| | |",
+    "|---|---|",
+    ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+    "",
+    `<sub>From nomArmy's verified job records, not the workers' own reports. [What is nomArmy?](${REPO_URL})</sub>`,
+  ].join("\n");
+}
+
+const esc = (s) =>
+  String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+// Verdana 11px, the badge convention: rough widths by letter shape, plus padding.
+function textWidth(s) {
+  let w = 0;
+  for (const ch of String(s)) w += /[mwMW]/.test(ch) ? 10.5 : /[ijlI|.,:;!' ]/.test(ch) ? 3.8 : /[frt]/.test(ch) ? 4.8 : /[A-Z]/.test(ch) ? 7.6 : /[0-9]/.test(ch) ? 7 : ch === "·" ? 4.5 : 6.6;
+  return Math.round(w + 14);
+}
+
+/**
+ * A shields-style SVG: "nomArmy | 78 claims checked · 11 caught". Caught
+ * claims are the point of running nomArmy, not something to hide, so the
+ * color is a neutral blue, and green when every claim held up.
+ */
+export function badgeSvg(stats) {
+  const { total, caught } = claims(stats);
+  const label = "nomArmy";
+  const message = !total ? "verified" : caught ? `${total} claims checked · ${caught} caught` : `${total} claims checked, all held up`;
+  const color = total && !caught ? "#2da44e" : "#0969da";
+  const lw = textWidth(label), mw = textWidth(message), w = lw + mw;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="20" role="img" aria-label="${esc(`${label}: ${message}`)}">
+  <title>${esc(`${label}: ${message}`)}</title>
+  <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
+  <clipPath id="r"><rect width="${w}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)"><rect width="${lw}" height="20" fill="#555"/><rect x="${lw}" width="${mw}" height="20" fill="${color}"/><rect width="${w}" height="20" fill="url(#s)"/></g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+    <text x="${lw / 2}" y="14">${esc(label)}</text>
+    <text x="${lw + mw / 2}" y="14">${esc(message)}</text>
+  </g>
+</svg>
+`;
+}
+
+/** The README line for a committed badge, linking to nomArmy. */
+export function badgeMarkdown(relPath) {
+  return `[![nomArmy](${relPath})](${REPO_URL})`;
+}

package/lib/stale-sessions.mjs

@@ -0,0 +1,60 @@
+// Which open coordinator sessions still run an older nomArmy. Each Claude
+// Code, Codex or Cursor session starts its own nomArmy server and keeps the
+// code it started with, so after an update "restart your sessions" wasn't
+// enough: one real afternoon had a session on alpha.14 for hours and four
+// more, days old, on alpha.6 to alpha.12. This names each one.
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+// The installed copy's server, or the portable `nomarmy mcp` launcher.
+const SERVER_RE = /nomarmy-local-worker[\\/]mcp[\\/]server\.mjs|\bnomarmy(?:\.mjs)?\s+mcp\b/;
+
+/** `ps -A -o pid=,ppid=,tty=,lstart=,args=` lines. lstart reads "Sun Sep 27 21:33:11 2026" on macOS and Linux alike. */
+export function parsePs(text) {
+  const out = [];
+  for (const line of String(text ?? "").split("\n")) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}:\d{2}:\d{2})\s+(\d{4})\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const startedAt = new Date(`${m[4]} ${m[5]} ${m[7]} ${m[6]}`).getTime();
+    if (!Number.isFinite(startedAt)) continue;
+    out.push({ pid: Number(m[1]), ppid: Number(m[2]), tty: /^\?+$/.test(m[3]) ? null : m[3], startedAt, args: m[8].trim() });
+  }
+  return out;
+}
+
+/** The app a server belongs to, from its parent's command line. */
+export function appName(args) {
+  const first = String(args ?? "").split(/\s+/)[0] ?? "";
+  const base = path.basename(first).toLowerCase();
+  if (base === "claude" || /claude/.test(base)) return "Claude Code";
+  if (base === "codex" || /codex/.test(base)) return "Codex";
+  if (/cursor/i.test(first)) return "Cursor";
+  return base || "a session";
+}
+
+/** Servers that started before the copy they'd now load was installed. */
+export function staleSessions(procs, { installedAt }) {
+  if (!Number.isFinite(installedAt)) return [];
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  return procs
+    .filter((p) => SERVER_RE.test(p.args) && p.startedAt < installedAt)
+    .map((p) => {
+      const parent = byPid.get(p.ppid);
+      return { pid: p.pid, appPid: parent?.pid ?? p.ppid, app: appName(parent?.args), tty: p.tty ?? parent?.tty ?? null, startedAt: p.startedAt };
+    })
+    .sort((a, b) => a.startedAt - b.startedAt);
+}
+
+/** Running processes, or null where `ps` isn't available (Windows). */
+export function listProcesses({ run = spawnSync, platform = process.platform } = {}) {
+  if (platform === "win32") return null;
+  const res = run("ps", ["-A", "-o", "pid=,ppid=,tty=,lstart=,args="], { encoding: "utf8", timeout: 10000 });
+  return res.status === 0 ? parsePs(res.stdout) : null;
+}
+
+export function formatStaleSessions(list, { now = Date.now() } = {}) {
+  const when = (ms) => new Date(ms).toLocaleString("en-US", { weekday: "short", hour: "numeric", minute: "2-digit" });
+  const age = (ms) => { const h = Math.round((now - ms) / 3600000); return h < 24 ? `${h}h ago` : `${Math.round(h / 24)}d ago`; };
+  return list.map((s) => `  ${s.app}${s.tty ? ` on ${s.tty}` : ""}, started ${when(s.startedAt)} (${age(s.startedAt)}), pid ${s.appPid}`);
+}