@a2f0/agent-tool 0.1.30 → 0.1.32

package/README.md

@@ -4,8 +4,8 @@ agent-tool is a command-line tool and a set of portable skills for repositories
 where Claude Code, Codex, or OpenCode make the changes. It provides shared Git,
 GitHub, review, validation, and release workflows: independent agent reviews of
 a committed branch, guarded pushes and squash merges of the exact reviewed
-commit, package versioning, brand image rendering, and compact output for noisy
-commands. Repository policy stays in `agent-tool.json`; the portable skills
+commit, package versioning, brand image rendering, screenshot staging with a
+framework-free gallery, and compact output for noisy commands. Repository policy stays in `agent-tool.json`; the portable skills
 coordinate independently reviewed changes.
 
 ## Quick start
@@ -85,6 +85,8 @@ validation suite, and release procedures.
 - [Development](docs/development.md): setup, source layout, validation, and release
   procedures for this package.
 - [Images](docs/images.md): declarative brand sources and generated outputs.
+- [Screenshots](docs/screenshots.md): staging captured screenshots into a
+  website, and the gallery and carousel web components that show them.
 - [Permissions](docs/permissions.md): which commands run without approval in
   Claude Code and Codex, and the dependency commands that enforce it.
 - [Dependency maintenance](docs/dependency-upgrades.md): active compatibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
@@ -15,6 +15,12 @@
   "bin": {
     "agent-tool": "src/index.ts"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./screenshots/gallery": "./src/screenshots/gallery.ts",
+    "./screenshots/gallery.css": "./src/screenshots/gallery.css",
+    "./screenshots/manifest": "./src/screenshots/manifest.ts"
+  },
   "files": [
     "src",
     "skills",
@@ -29,12 +35,14 @@
     "agent:run": "bun src/index.ts run",
     "agent:logs": "bun src/index.ts logs",
     "test": "bun test --parallel src scripts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.browser.json",
     "generate": "bun scripts/build/bundle-skills.ts",
     "build": "bun run generate && bun build --compile --minify src/index.ts --outfile dist/agent-tool"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "21.0.4",
     "@types/bun": "1.4.3",
+    "happy-dom": "21.0.4",
     "typescript": "7.0.2"
   },
   "dependencies": {

package/skills/open-pr/SKILL.md

@@ -33,4 +33,5 @@ open PRs and requires the branch to be pushed at its local HEAD. It does not
 push for you. Resolve a fork's head/base identities explicitly if the repository
 uses fork PRs; the initial open helper supports same-repository branches.
 
-Report the created PR link and any remaining validation or review work.
+Report the created PR link and any remaining validation or review work. Run
+`agent-tool teardown` first, stop what the work started, and report what remains.

package/skills/reset/SKILL.md

@@ -39,6 +39,8 @@ switch, and update by fast-forward only. Never discard or automatically stash
 edits, force a diverged default branch, or infer shipping from Git ancestry after
 a squash merge.
 
+Run `agent-tool teardown` and stop what the finished work left running
+(`teardown --apply` for recorded processes); report anything that remains.
 Run the repository's documented dependency/hook setup if required. When copied
 hooks are configured, use `agent-tool hooks check` and `hooks install --apply`;
 inspect unmanaged hooks before an explicit `--adopt`, which backs them up.

package/skills/ship-pr/SKILL.md

@@ -23,6 +23,9 @@ machine-readable receipts and review findings visible by running `versions
 prepare`, `review`, and other commands whose output drives a decision directly.
 Prefer documented compact test reporters when they preserve required evidence;
 do not reduce test scope, skip checks, silence warnings, or mask failures.
+Start servers, watchers, and other long-running processes with
+`agent-tool proc start --label <name> -- <command>`, never a backgrounded shell
+command, so they can be found and stopped.
 
 1. Finish the requested change on a feature branch. Use
    `agent-tool branch create <branch> --base <base-branch> --remote <remote>`
@@ -73,8 +76,15 @@ do not reduce test scope, skip checks, silence warnings, or mask failures.
    live checks. Report deployment failures
    separately from a successful merge; follow project policy for repairs.
 
+Before the final report, run `agent-tool teardown` in each repository this work
+touched. Stop what the work started (`teardown --apply`, `proc stop`), stop any
+untracked process it started, and remove worktrees it added. Report what
+remains and why; the work is not done while teardown fails for anything it
+started.
+
 Never infer a clean review from process success alone or carry a review across
 content changes. Do not weaken configured CI policy to get a merge through.
 If a step fails, preserve useful intermediate work and report the concrete
 remaining issue. Report PR link, merged commit, review verdict, validation, final
-checkout state, and whether the shipped local branch was pruned or preserved.
+checkout state, the teardown result, and whether the shipped local branch was
+pruned or preserved.

package/src/cli.ts

@@ -6,6 +6,7 @@ import { doctor } from "./doctor";
 import { checkTerraformPlan } from "./dependencies/terraformPlan";
 import { dependencyDiff } from "./dependencies/diff";
 import { checkGraph } from "./graph/check";
+import { buildScreenshots, describeScreenshots } from "./screenshots/build";
 import { review } from "./harnesses";
 import { runAgentToolAction } from "./runAgentToolAction";
 import { BUNDLED_SKILLS } from "./skills/bundled";
@@ -27,6 +28,7 @@ import { hooksCommand } from "./workflows/hooks";
 import { repoCommand, policyCommand, toolchainCommand } from "./workflows/repository";
 import { prWorkflowCommand } from "./workflows/pr";
 import { releaseCommand } from "./release/commands";
+import { procCommand, teardownCommand } from "./processes/commands";
 
 export const HELP = `agent-tool ${metadata.version}
 
@@ -34,6 +36,9 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
 
   run [--label text] [--max-bytes N] [--tail-lines N] -- <command> [args...]
   run-group <plan.json>                  Sequential checks with durable source-bound receipts
+  proc start [--label text] [--keep] -- <command> [args...]  Recorded long-running process
+  proc list | stop <id...>|--all [--grace-ms N]
+  teardown [--apply]                     What this checkout still runs; --apply stops recorded processes
   runs list [--head oid] [--branch name] [--since ISO-date]
   branch check [name...|--pre-push] | status
   branch create <name> [--base branch] [--remote origin]
@@ -73,6 +78,7 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   permissions check [--harness <all|claude|codex>]
   images list [target...]               JSON files each image target writes
   images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
+  screenshots build [target...] [--out <dir>] [--json]  Stage guarded captures and a gallery manifest
   graph check                           Import cycles and layer violations per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
@@ -111,6 +117,8 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
   if (command === "run") return runCommand(args);
   if (command === "ci") { usage(args.shift() === "gate", "Usage: ci gate <needs.json|-> [--policy policy.json]"); return gateCommand(args); }
   if (command === "release") return releaseCommand(args);
+  if (command === "proc") return procCommand(args);
+  if (command === "teardown") return teardownCommand(args);
   if (command === "logs") return inspectLog(args);
   if (command === "dependencies" && args[0] === "diff") {
     usage(args.length === 3 && args[1] === "--base" && !!args[2] && !args[2].startsWith("-"), "Usage: agent-tool dependencies diff --base <ref>");
@@ -151,6 +159,21 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
       output(action === "list" ? listImages(images, names) : await buildImages(process.cwd(), images, names, out)); return 0;
     });
   }
+  if (command === "screenshots") {
+    const action = args.shift();
+    usage(action === "build", "Usage: agent-tool screenshots build [target...] [--out <dir>] [--json]");
+    const names: string[] = [];
+    let out: string | undefined, json = false;
+    while (args.length) {
+      const value = args.shift()!;
+      if (value === "--out") { usage(out === undefined && !!args[0] && !args[0].startsWith("--"), "--out requires one directory."); out = args.shift(); }
+      else if (value === "--json") { usage(!json, "Duplicate --json."); json = true; }
+      else { usage(!value.startsWith("-"), `Unknown screenshots argument '${value}'.`); names.push(value); }
+    }
+    const receipt = buildScreenshots(process.cwd(), loadConfig().screenshots, names, out);
+    if (json) output(receipt); else writeSync(1, describeScreenshots(receipt));
+    return 0;
+  }
   if (command === "graph") {
     usage(args.length === 1 && args[0] === "check", "Usage: agent-tool graph check");
     const report = checkGraph(process.cwd(), loadConfig().graph);

package/src/commands/run.ts

@@ -6,7 +6,7 @@ import { createLog } from "./logFile";
 
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
 
-export interface RunReceipt { status: string; label?: string; exitCode: number; signal: string | null; durationMs: number; outputBytes: number; log: string }
+export interface RunReceipt { status: string; label?: string; exitCode: number; signal: string | null; durationMs: number; outputBytes: number; log: string; leftoverProcessGroup?: number }
 
 /** Run directly into a private file: child output never accumulates in memory. */
 export async function runCommand(args: string[], record?: (receipt: RunReceipt) => void, options: { quiet?: boolean; reraiseChildSignal?: boolean } = {}): Promise<number> {
@@ -79,9 +79,18 @@ export async function runCommand(args: string[], record?: (receipt: RunReceipt)
       forward("SIGKILL");
     }
     const exitCode = signal ? 128 + (constants.signals[signal] ?? 0) : status ?? 1;
-    const receipt: RunReceipt = { status: exitCode === 0 ? "passed" : "failed", ...(label ? { label } : {}), exitCode, signal, durationMs: Math.round(performance.now() - started), outputBytes: fstatSync(fd).size, log };
+    // A finite command that left processes behind in its group, such as `server &`, is reported:
+    // nothing else would notice them before the work is called done.
+    let leftover: number | undefined;
+    if (grouped && !interrupted && child.pid) {
+      // EPERM still means the group exists, now holding a process this user cannot signal.
+      try { process.kill(-child.pid, 0); leftover = child.pid; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "EPERM") leftover = child.pid; }
+    }
+    const receipt: RunReceipt = { status: exitCode === 0 ? "passed" : "failed", ...(label ? { label } : {}), exitCode, signal, durationMs: Math.round(performance.now() - started), outputBytes: fstatSync(fd).size, log, ...(leftover ? { leftoverProcessGroup: leftover } : {}) };
     record?.(receipt);
     if (!options.quiet) writeSync(1, `${JSON.stringify(receipt)}\n`);
+    if (leftover) writeSync(2, `Processes this command started are still running in its process group ${leftover} (\`kill -TERM -${leftover}\`). Stop them, or start long-running processes with \`agent-tool proc start\`.\n`);
     if (exitCode !== 0) printLogTail(log, limits, 2);
   } finally {
     if (timer) clearTimeout(timer);

package/src/config.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { GRAPH_DEFAULTS, parseGraph, type GraphConfig } from "./graph/config";
 import { parseImages, type ImagesConfig } from "./images/config";
 import { CLASSES, type PermissionClass } from "./permissions/catalog";
+import { parseScreenshots, SCREENSHOTS_DEFAULTS, type ScreenshotsConfig } from "./screenshots/config";
 import { WORKFLOW_DEFAULTS, validateWorkflowConfig, type WorkflowConfig } from "./workflows/config";
 
 export interface RequiredCheck {
@@ -18,6 +19,7 @@ export interface AgentToolConfig extends WorkflowConfig {
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
   pr: { rejectClaudeBranding: boolean };
   images: ImagesConfig;
+  screenshots: ScreenshotsConfig;
   graph: GraphConfig;
   permissions: { executables: Record<string, PermissionClass> };
 }
@@ -38,6 +40,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
   images: { targets: {} },
+  screenshots: structuredClone(SCREENSHOTS_DEFAULTS),
   graph: structuredClone(GRAPH_DEFAULTS),
   permissions: { executables: {} },
 };
@@ -72,6 +75,7 @@ export function parseConfig(source: string): AgentToolConfig {
     Object.assign(result[section], settings);
   }
   if (input.images !== undefined) result.images = parseImages(input.images);
+  if (input.screenshots !== undefined) result.screenshots = parseScreenshots(input.screenshots);
   if (input.graph !== undefined) result.graph = parseGraph(input.graph);
   if (input.branch !== undefined && !Object.hasOwn(input.branch as object, "enforce")) result.branch.enforce = true;
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };

package/src/images/build.ts

@@ -1,12 +1,12 @@
 import { initWasm, Resvg } from "@resvg/resvg-wasm";
 import wasm from "@resvg/resvg-wasm/index_bg.wasm" with { type: "file" };
-import { randomUUID } from "node:crypto";
-import { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { composeSvg, type Canvas } from "./compose";
 import { expand, format, SOURCE_DIRECTORY, verbatim, type ImageOutput, type ImagesConfig, type ImageTarget } from "./config";
 import { encodeIco, encodePng, fromPremultiplied, type Pixels } from "./png";
 import { parseSvg, type SvgSource } from "./svg";
+import { assertNoLinks, replaceFile } from "../system/files";
 
 let ready: Promise<void> | undefined;
 
@@ -85,49 +85,6 @@ function select(config: ImagesConfig, names: string[], writable: boolean): [stri
   return selected.map(name => [name, config.targets[name]!]);
 }
 
-/** Refuses symbolic links below the base, so a committed link cannot redirect a write outside it. */
-function assertNoLinks(base: string, destination: string): void {
-  let current = base;
-  for (const part of path.relative(base, destination).split(path.sep)) {
-    current = path.join(current, part);
-    let link: boolean;
-    try { link = lstatSync(current).isSymbolicLink(); } catch { return; }
-    if (link) throw new Error(`Refusing to write through symbolic link ${path.relative(base, current)}.`);
-  }
-}
-
-/**
- * Replaces a file atomically through an unpredictable, exclusively created
- * temporary name, so no committed link can stand in for it. Sandboxed build
- * phases, such as Xcode's, may write only their declared outputs; there the
- * file is rewritten in place, refusing to follow a link.
- */
-export function replaceFile(destination: string, bytes: Uint8Array): void {
-  const temporary = `${destination}.${randomUUID()}.tmp`;
-  let created = false;
-  try {
-    writeFileSync(temporary, bytes, { flag: "wx" });
-    created = true;
-    renameSync(temporary, destination);
-  } catch (error) {
-    if (created || !["EACCES", "EPERM"].includes((error as NodeJS.ErrnoException).code ?? "")) {
-      // Best effort: the original error matters more than a temporary file left behind.
-      try { rmSync(temporary, { force: true }); } catch {}
-      throw error;
-    }
-    // Nothing was created, and a sandbox may refuse even an attempt to remove an undeclared path.
-    const descriptor = openSync(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW);
-    try {
-      // A hard link would share the file with a path outside the output, so only a sole link is rewritten.
-      const stats = fstatSync(descriptor);
-      if (!stats.isFile() || stats.nlink !== 1) throw new Error(`Refusing to rewrite ${destination}, which is not a file with a single link.`);
-      ftruncateSync(descriptor, 0);
-      // writeFileSync on a descriptor repeats short writes until every byte is written.
-      writeFileSync(descriptor, bytes);
-    } finally { closeSync(descriptor); }
-  }
-}
-
 function directory(name: string, target: ImageTarget, out: string | undefined): string {
   const dir = out ?? target.dir;
   if (dir === null) throw new Error(`Image target '${name}' has no dir; pass --out <directory>.`);

package/src/images/png.ts

@@ -88,6 +88,16 @@ export function encodePng({ width, height, channels, data }: Pixels): Uint8Array
   ]);
 }
 
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+/** Pixel size from a PNG's header: the signature, then IHDR's big-endian width and height. */
+export function pngSize(bytes: Uint8Array): { width: number; height: number } | null {
+  if (bytes.length < 24 || SIGNATURE.some((byte, index) => bytes[index] !== byte) || new TextDecoder().decode(bytes.subarray(12, 16)) !== "IHDR") return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16), height = view.getUint32(20);
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
 /** A Windows icon that stores one PNG per size, which every current browser reads. */
 export function encodeIco(images: readonly Pixels[]): Uint8Array {
   const pngs = images.map(encodePng);

package/src/permissions/catalog.ts

@@ -19,12 +19,13 @@ export type Decision = "allow" | "ask";
 export interface CatalogEntry { command: string; class: PermissionClass; applyClass?: PermissionClass }
 
 export const CATALOG: CatalogEntry[] = [
-  ...["--help", "--version", "logs", "runs list", "doctor", "config show", "branch check", "branch status", "commits check", "checks binaries", "repo context", "policy check", "toolchain check", "ci gate", "release plan", "release verify", "pr context", "pr checks", "pr logs", "pr preflight", "pr threads list", "versions plan", "versions check", "dependencies check-terraform-plan", "dependencies diff", "skills list", "skills check", "hooks check", "images list", "graph check", "permissions show", "permissions check"]
+  ...["--help", "--version", "logs", "runs list", "doctor", "config show", "branch check", "branch status", "commits check", "checks binaries", "repo context", "policy check", "toolchain check", "ci gate", "release plan", "release verify", "pr context", "pr checks", "pr logs", "pr preflight", "pr threads list", "versions plan", "versions check", "dependencies check-terraform-plan", "dependencies diff", "skills list", "skills check", "hooks check", "images list", "graph check", "permissions show", "permissions check", "proc list"]
     .map(command => ({ command, class: "read" as const })),
-  ...["bun install", "bun update", "bun remove", "bun test", "branch create", "versions bump", "versions prepare", "versions resolve-conflicts", "images build", "review", "init"]
+  ...["bun install", "bun update", "bun remove", "bun test", "branch create", "versions bump", "versions prepare", "versions resolve-conflicts", "images build", "screenshots build", "review", "init", "proc stop"]
     .map(command => ({ command, class: "local" as const })),
   { command: "skills install", class: "read", applyClass: "local" },
   { command: "hooks install", class: "read", applyClass: "local" },
+  { command: "teardown", class: "read", applyClass: "local" },
   { command: "permissions install", class: "read", applyClass: "policy" },
   ...["branch push", "pr open", "pr threads reply", "pr threads resolve"].map(command => ({ command, class: "share" as const })),
   { command: "pr merge", class: "release" },
@@ -36,7 +37,7 @@ export const CATALOG: CatalogEntry[] = [
   { command: "openPr", class: "share" },
   { command: "squashMerge", class: "release" },
 ];
-// `run` and `run-group` execute arbitrary commands, so they stay unclassified and keep the harness default.
+// `run`, `run-group` and `proc start` execute arbitrary commands, so they stay unclassified and keep the harness default.
 // `bun x` runs only executables that `permissions.executables` classifies; project.ts adds those.
 // Package scripts are not classified, so `bun run` keeps the harness default.
 

package/src/processes/commands.ts

@@ -0,0 +1,283 @@
+// `proc start|list|stop` and `teardown`: long-running processes started through agent-tool are
+// recorded so they can be found and stopped, and teardown reports everything a piece of work
+// may have left running in the repository before an agent says it is done.
+import { spawn } from "node:child_process";
+import { closeSync, realpathSync } from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { createLog } from "../commands/logFile";
+import { plainText } from "../commands/output";
+import { assert, git, output } from "../workflows/core";
+import { claimedBy, ledgerDirectory, membersOf, newId, observe, readRecords, removeRecord, saveRecord, type ProcessRecord, type ProcessState } from "./ledger";
+import { ancestors, carrying, listeningPorts, processTable, startOf, workingDirectories, type ProcessRow } from "./table";
+
+const STOP_GRACE_MS = 5000;
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+// A bound on another wait that does not itself keep the process alive once that wait is over.
+const bound = (ms: number) => new Promise<undefined>(resolve => { (setTimeout(resolve, ms) as unknown as NodeJS.Timeout).unref(); });
+
+function within(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function signal(pid: number, value: NodeJS.Signals, group: boolean): void {
+  try { process.kill(group ? -pid : pid, value); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+}
+
+interface Described { id: string; label: string | null; state: ProcessState; keep: boolean; pid: number; command: string[]; cwd: string; log: string; startedAt: string; members: { pid: number; command: string }[]; ports: string[] }
+
+// Read-only: `proc list` and report-only `teardown` never write records.
+function describe(record: ProcessRecord, table: Map<number, ProcessRow>, ports: Map<number, string[]>, others: ProcessRecord[]): Described {
+  const { state, members } = membersOf(record, table, others);
+  return {
+    id: record.id, label: record.label, state, keep: record.keep, pid: record.pid, command: record.command, cwd: record.cwd, log: record.log, startedAt: record.startedAt,
+    members: members.map(row => ({ pid: row.pid, command: row.command })),
+    ports: [...new Set(members.flatMap(row => ports.get(row.pid) ?? []))].sort(),
+  };
+}
+
+const alive = (state: ProcessState) => state === "running" || state === "orphaned";
+
+/**
+ * Stops one record's processes: SIGTERM to its group and to members outside it, then SIGKILL
+ * after the grace period. Every member seen is remembered with its start time, so a descendant
+ * that left the group and outlived its parent is still signalled, and only while it is the same
+ * process; the group is signalled only while its leader, or a member of it, is ours.
+ */
+async function stopRecord(directory: string, record: ProcessRecord, grace = STOP_GRACE_MS): Promise<{ id: string; stopped: boolean; remaining: number[] }> {
+  const known = new Map<number, string>();
+  const look = () => {
+    const table = processTable(), others = readRecords(directory).records, { state, members } = membersOf(record, table, others);
+    observe(directory, record, state, members);
+    for (const member of members) known.set(member.pid, member.started);
+    const claimed = claimedBy(record, table, others);
+    const live = [...known].filter(([pid, started]) => table.get(pid)?.started === started && !claimed.has(pid)).map(([pid]) => table.get(pid)!);
+    // The group id is ours while our leader runs, or while a member we know still holds it;
+    // otherwise it may name someone else's group, and members are signalled one by one.
+    return { group: state === "running" || live.some(member => member.pgid === record.pid), live };
+  };
+  const send = (value: NodeJS.Signals) => {
+    const { group, live } = look();
+    if (group) signal(record.pid, value, true);
+    for (const member of live) if (!group || member.pgid !== record.pid) signal(member.pid, value, false);
+  };
+  const running = () => { const { group, live } = look(); return group || live.length > 0; };
+  send("SIGTERM");
+  const deadline = performance.now() + grace;
+  while (performance.now() < deadline && running()) await sleep(50);
+  send("SIGKILL");
+  for (let tries = 0; tries < 20 && running(); tries += 1) await sleep(50);
+  const { group, live } = look();
+  const stopped = !group && live.length === 0;
+  // observe() may have rewritten the record while stopping; remove it only after the last look.
+  if (stopped) removeRecord(directory, record.id);
+  return { id: record.id, stopped, remaining: stopped ? [] : live.map(row => row.pid) };
+}
+
+/**
+ * The members of a launcher's group that are provably its own once the launcher has exited and
+ * the group id could name another group: those carrying the record's id, or started while the
+ * launcher ran, to the second `ps` reports with a second's margin either side.
+ */
+export function adoptable(candidates: ProcessRow[], tagged: Set<number>, spawnedAt: number, exitedAt: number): ProcessRow[] {
+  const from = Math.floor(spawnedAt / 1000) * 1000 - 1000, until = exitedAt + 1000;
+  return candidates.filter(row => {
+    const at = Date.parse(`${row.started} UTC`);
+    return tagged.has(row.pid) || (at >= from && at <= until);
+  });
+}
+
+async function start(args: string[]): Promise<number> {
+  let label: string | null = null, keep = false;
+  while (args.length && args[0] !== "--") {
+    const flag = args.shift();
+    if (flag === "--label") {
+      const value = args.shift();
+      assert(value && value.length <= 120, "--label requires 1 to 120 characters.");
+      label = plainText(value);
+    } else if (flag === "--keep") keep = true;
+    else throw new Error(`Unknown proc start argument '${flag}'.`);
+  }
+  assert(args.shift() === "--" && args[0], "Usage: agent-tool proc start [--label text] [--keep] -- <command> [args...]");
+  const directory = ledgerDirectory();
+  // Without a working ps nothing started could be identified, recorded or stopped later.
+  try { processTable(); }
+  catch (error) { throw new Error(`Cannot inspect processes with ps, so nothing was started: ${(error as Error).message}`); }
+  const id = newId(), { log, fd } = createLog("agent-tool-proc-");
+  let record: ProcessRecord | undefined;
+  try {
+    // Its own process group, so stopping it reaches everything it starts that stays in the group.
+    const spawnedAt = Date.now();
+    let exitedAt: number | undefined;
+    const child = spawn(args[0]!, args.slice(1), { cwd: process.cwd(), detached: true, stdio: ["ignore", fd, fd], env: { ...process.env, AGENT_TOOL_PROCESS: id } });
+    const exited = new Promise<{ code: number | null; signal?: NodeJS.Signals | null; error?: string }>(resolve => {
+      child.once("error", error => resolve({ code: (error as NodeJS.ErrnoException).code === "ENOENT" ? 127 : 126, error: error.message }));
+      child.once("exit", (code, signal) => { exitedAt = Date.now(); resolve({ code, signal }); });
+    });
+    if (child.pid) {
+      const started = startOf(child.pid);
+      if (started) {
+        record = { schemaVersion: 1, id, label, pid: child.pid, started, command: [...args], cwd: process.cwd(), log, startedAt: new Date().toISOString(), keep };
+        try { saveRecord(directory, record); }
+        catch (error) {
+          // An unrecorded process could never be found and stopped by teardown.
+          signal(child.pid, "SIGKILL", true);
+          await Promise.race([exited, bound(2000)]);
+          throw new Error(`Could not record the process, so it was stopped: ${(error as Error).message}`);
+        }
+      } else if (!(await Promise.race([exited, bound(300)]))) {
+        // Running, but its identity could not be read, so it could never be stopped safely later.
+        signal(child.pid, "SIGKILL", true);
+        await Promise.race([exited, bound(2000)]);
+        throw new Error("Could not read the started process's identity with ps; stopped it. Nothing was recorded.");
+      }
+    }
+    // A command that fails at once is reported here rather than found later.
+    const early = await Promise.race([exited, bound(300)]);
+    child.unref();
+    if (child.pid) {
+      const table = processTable();
+      if (table.get(child.pid)?.started === record?.started && record) {
+        const { state, members } = membersOf(record, table, readRecords(directory).records);
+        observe(directory, record, state, members);
+      } else if (!table.has(child.pid)) {
+        // The launcher exited, perhaps before its identity could be read, and its group id may
+        // already name another group. A member is ours when it carries this record's id, or
+        // started while the launcher ran (to the second `ps` reports, with a second's margin).
+        const candidates = [...table.values()].filter(row => row.pgid === child.pid);
+        const survivors = adoptable(candidates, carrying(candidates.map(row => row.pid), "AGENT_TOOL_PROCESS", id), spawnedAt, exitedAt ?? Date.now());
+        if (survivors.length) {
+          record ??= { schemaVersion: 1, id, label, pid: child.pid, started: "", command: [...args], cwd: process.cwd(), log, startedAt: new Date().toISOString(), keep };
+          record.members = survivors.map(row => ({ pid: row.pid, started: row.started }));
+          try { saveRecord(directory, record); }
+          catch (error) {
+            for (const row of survivors) signal(row.pid, "SIGKILL", false);
+            throw new Error(`Could not record the processes the command left running, so they were stopped: ${(error as Error).message}`);
+          }
+        }
+      }
+    }
+    const receipt = { id, ...(label ? { label } : {}), pid: child.pid ?? null, keep, log, ...(early ? { exited: early.code, ...(early.signal ? { signal: early.signal } : {}), ...(early.error ? { error: early.error } : {}) } : {}) };
+    if (early && record && !alive(membersOf(record, processTable()).state)) removeRecord(directory, id);
+    output(receipt);
+    if (early?.signal) return 128 + (constants.signals[early.signal] ?? 0);
+    return early && early.code !== 0 ? (early.code ?? 1) : 0;
+  } finally { closeSync(fd); }
+}
+
+function parseStopTargets(args: string[]): { all: boolean; ids: string[]; grace: number } {
+  let all = false, grace = STOP_GRACE_MS;
+  const ids: string[] = [];
+  while (args.length) {
+    const value = args.shift()!;
+    if (value === "--all") all = true;
+    else if (value === "--grace-ms") {
+      grace = Number(args.shift());
+      assert(Number.isInteger(grace) && grace >= 0 && grace <= 60_000, "--grace-ms requires 0 to 60000.");
+    } else { assert(/^[a-f0-9]{8}$/.test(value), `Unknown process id '${value}'.`); ids.push(value); }
+  }
+  assert(all !== ids.length > 0, "Usage: agent-tool proc stop <id...>|--all [--grace-ms N]");
+  return { all, ids, grace };
+}
+
+export async function procCommand(args: string[]): Promise<number> {
+  const action = args.shift();
+  if (action === "start") return start(args);
+  const directory = ledgerDirectory();
+  if (action === "list") {
+    assert(args.length === 0, "Usage: agent-tool proc list");
+    const { records, skipped } = readRecords(directory), table = processTable(), { ports } = listeningPorts();
+    output({ processes: records.map(record => describe(record, table, ports, records)), skipped });
+    return 0;
+  }
+  assert(action === "stop", "Usage: agent-tool proc <start|list|stop>");
+  const { all, ids, grace } = parseStopTargets(args);
+  const { records, skipped } = readRecords(directory);
+  for (const id of ids) assert(records.some(record => record.id === id), `No recorded process '${id}'.`);
+  const results = [];
+  for (const record of records.filter(record => all || ids.includes(record.id))) results.push(await stopRecord(directory, record, grace));
+  output({ stopped: results, skipped });
+  // An unreadable record may name processes --all could not stop.
+  return results.every(result => result.stopped) && (!all || skipped.length === 0) ? 0 : 1;
+}
+
+export interface TeardownReport {
+  ok: boolean;
+  applied: boolean;
+  root: string;
+  /** Recorded processes still running: they fail teardown unless started with --keep. */
+  leftover: Described[];
+  kept: Described[];
+  /** Records whose processes have ended; --apply removes them. */
+  finished: { id: string; label: string | null; state: ProcessState }[];
+  stopped: { id: string; stopped: boolean; remaining: number[] }[];
+  /** Processes started some other way whose working directory is in the repository. Listeners fail teardown. */
+  untracked: { pid: number; command: string; cwd: string; ports: string[] }[];
+  worktrees: { path: string; branch: string | null }[];
+  unavailable: string[];
+  skipped: { file: string; reason: string }[];
+}
+
+function survey(root: string, directory: string): Omit<TeardownReport, "ok" | "applied" | "stopped"> {
+  const table = processTable(), { records, skipped } = readRecords(directory);
+  const listening = listeningPorts(), cwd = workingDirectories(table.keys());
+  const described = records.map(record => describe(record, table, listening.ports, records));
+  const owned = new Set(described.flatMap(item => alive(item.state) ? item.members.map(member => member.pid) : []));
+  const excluded = ancestors(table);
+  const untracked = [...cwd.cwd].flatMap(([pid, directoryOf]) => {
+    const row = table.get(pid);
+    if (!row || excluded.has(pid) || owned.has(pid) || !within(root, directoryOf)) return [];
+    // Processes this command started to look (ps, lsof) are its children.
+    if (row.ppid === process.pid) return [];
+    const ports = listening.ports.get(pid) ?? [];
+    // A pipeline's other commands (`agent-tool teardown | jq`) share its shell and group; one that
+    // listens is still reported, since a server backgrounded from the same shell looks alike.
+    const self = table.get(process.pid);
+    if (self && row.pgid === self.pgid && row.ppid === self.ppid && ports.length === 0) return [];
+    return [{ pid, command: row.command, cwd: directoryOf, ports }];
+  }).sort((a, b) => a.pid - b.pid);
+  const worktrees: { path: string; branch: string | null }[] = [];
+  let current: { path: string; branch: string | null } | undefined;
+  for (const line of git(["worktree", "list", "--porcelain"]).split("\n")) {
+    if (line.startsWith("worktree ")) worktrees.push(current = { path: line.slice(9), branch: null });
+    else if (line.startsWith("branch ") && current) current.branch = line.slice(7).replace(/^refs\/heads\//, "");
+  }
+  return {
+    root,
+    leftover: described.filter(item => alive(item.state) && !item.keep),
+    kept: described.filter(item => alive(item.state) && item.keep),
+    finished: described.filter(item => !alive(item.state)).map(item => ({ id: item.id, label: item.label, state: item.state })),
+    untracked,
+    // The first entry is the main worktree; the rest were added and may need removing.
+    worktrees: worktrees.slice(1),
+    unavailable: [...(listening.available ? [] : ["listening ports (lsof)"]), ...(cwd.available ? [] : ["working directories (lsof)"])],
+    skipped,
+  };
+}
+
+export async function teardownCommand(args: string[]): Promise<number> {
+  let apply = false;
+  for (const value of args) {
+    assert(value === "--apply" && !apply, "Usage: agent-tool teardown [--apply]");
+    apply = true;
+  }
+  const root = realpathSync(git(["rev-parse", "--show-toplevel"])), directory = ledgerDirectory();
+  const stopped: TeardownReport["stopped"] = [];
+  if (apply) {
+    const { records } = readRecords(directory), table = processTable();
+    for (const record of records) {
+      const { state, members } = membersOf(record, table, records);
+      observe(directory, record, state, members);
+      if (!alive(state)) removeRecord(directory, record.id);
+      else if (!record.keep) stopped.push(await stopRecord(directory, record));
+    }
+  }
+  const found = survey(root, directory);
+  // A clean report needs every inspection: without lsof a listening server would go unseen.
+  // Unreadable records may name running processes, so they fail teardown too.
+  const ok = found.leftover.length === 0 && found.untracked.every(item => item.ports.length === 0) && found.unavailable.length === 0 && found.skipped.length === 0;
+  output({ ok, applied: apply, ...found, stopped } satisfies TeardownReport);
+  return ok ? 0 : 1;
+}