@a2f0/agent-tool 0.1.29 → 0.1.31

package/README.md

@@ -81,7 +81,7 @@ validation suite, and release procedures.
   PR checks/threads, cleanup, CI aggregate gates, release verification, durable
   validation receipts, and toolchain/protection diagnostics.
 - [CLI reference](docs/reference.md): existing review, version, skill installation,
-  command capture, configuration, and distribution contracts.
+  command capture, import-graph checks, configuration, and distribution contracts.
 - [Development](docs/development.md): setup, source layout, validation, and release
   procedures for this package.
 - [Images](docs/images.md): declarative brand sources and generated outputs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",

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/bun/dependencies.ts

@@ -7,7 +7,7 @@ import { assert, flag, option, output } from "../workflows/core";
 import { bunExecute } from "./execute";
 import { pinnedBun, type BunExecutable } from "./toolchain";
 import { lockedWorkspaceVersions, lostWorkspaceReferences } from "../version/lockfileVersions";
-import { packageDirectories, workspacePackage } from "./workspace";
+import { packageDirectories, workspacePackage } from "../system/workspace";
 
 const SECTIONS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"] as const;
 type Section = typeof SECTIONS[number];

package/src/bun/execute.ts

@@ -8,7 +8,7 @@ import { CLASSES } from "../permissions/catalog";
 import { checkPermissions } from "../permissions/install";
 import { projectCommands } from "../permissions/project";
 import { pinnedBun } from "./toolchain";
-import { workspacePackage } from "./workspace";
+import { workspacePackage } from "../system/workspace";
 
 const USAGE = `Usage:
   agent-tool bun test [--cwd <dir>] [--log] [-- args...]

package/src/bun/toolchain.ts

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { outsideExecutable } from "../review/executable";
+import { outsideExecutable } from "../system/executable";
 import { assert } from "../workflows/core";
 
 export interface BunExecutable { path: string; version: string; source: "mise" | "path"; pinned: string | null }

package/src/bun/workspace.ts

@@ -1,40 +1,2 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import path from "node:path";
-import { assert } from "../workflows/core";
-
-/** The checkout root, where the workspace manifest and its lockfile live. */
-export function projectRoot(directory: string): string {
-  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf8" });
-  assert(result.status === 0, "Run Bun commands inside a Git checkout.");
-  return realpathSync(result.stdout.trim());
-}
-
-/** The root package and its declared Bun workspaces: the packages that share the root lockfile. */
-export function packageDirectories(root: string): string[] {
-  const manifest = path.join(root, "package.json");
-  if (!existsSync(manifest)) return [];
-  const value = JSON.parse(readFileSync(manifest, "utf8")) as { workspaces?: unknown };
-  const patterns = Array.isArray(value.workspaces) ? value.workspaces : (value.workspaces as { packages?: unknown } | undefined)?.packages;
-  const list = (Array.isArray(patterns) ? patterns : []).filter((pattern): pattern is string => typeof pattern === "string");
-  // `!pattern` entries exclude directories that the other patterns match.
-  const excluded = list.filter(pattern => pattern.startsWith("!")).map(pattern => new Bun.Glob(pattern.slice(1).replace(/\/$/, "")));
-  const directories = new Set([root]);
-  for (const pattern of list.filter(pattern => !pattern.startsWith("!"))) {
-    for (const match of new Bun.Glob(`${pattern.replace(/\/$/, "")}/package.json`).scanSync({ cwd: root, onlyFiles: true })) {
-      const relative = path.dirname(match);
-      if (!match.split("/").includes("node_modules") && !excluded.some(glob => glob.match(relative))) directories.add(path.join(root, relative));
-    }
-  }
-  return [...directories];
-}
-
-/** Resolve a package directory that belongs to the checkout's workspace, refusing standalone packages. */
-export function workspacePackage(directory: string): { root: string; directory: string } {
-  const resolved = realpathSync(directory);
-  const root = projectRoot(resolved);
-  // Harness rules come from the invoking checkout; --cwd may not reach another repository.
-  assert(root === projectRoot(process.cwd()), "--cwd must name a package in this checkout.");
-  assert(packageDirectories(root).some(item => realpathSync(item) === resolved), "Use the root package or a declared workspace; standalone packages keep their own lockfiles.");
-  return { root, directory: resolved };
-}
+// Moved to the primitives layer; re-exported so existing deep imports keep working.
+export { packageDirectories, projectRoot, workspacePackage } from "../system/workspace";

package/src/cli.ts

@@ -5,6 +5,7 @@ import { DEFAULT_CONFIG, loadConfig } from "./config";
 import { doctor } from "./doctor";
 import { checkTerraformPlan } from "./dependencies/terraformPlan";
 import { dependencyDiff } from "./dependencies/diff";
+import { checkGraph } from "./graph/check";
 import { review } from "./harnesses";
 import { runAgentToolAction } from "./runAgentToolAction";
 import { BUNDLED_SKILLS } from "./skills/bundled";
@@ -26,6 +27,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}
 
@@ -33,6 +35,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]
@@ -72,6 +77,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
+  graph check                           Import cycles and layer violations per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
   doctor                                JSON versions and supported review flags
@@ -109,6 +115,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>");
@@ -149,6 +157,11 @@ 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 === "graph") {
+    usage(args.length === 1 && args[0] === "check", "Usage: agent-tool graph check");
+    const report = checkGraph(process.cwd(), loadConfig().graph);
+    output(report); return report.ok ? 0 : 1;
+  }
   if (command === "skills") {
     const action = args.shift();
     if (action === "list") { usage(args.length === 0, "Usage: agent-tool skills list"); output(Object.keys(BUNDLED_SKILLS)); return 0; }

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

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 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 { WORKFLOW_DEFAULTS, validateWorkflowConfig, type WorkflowConfig } from "./workflows/config";
@@ -17,6 +18,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;
+  graph: GraphConfig;
   permissions: { executables: Record<string, PermissionClass> };
 }
 
@@ -36,6 +38,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
   images: { targets: {} },
+  graph: structuredClone(GRAPH_DEFAULTS),
   permissions: { executables: {} },
 };
 
@@ -69,6 +72,7 @@ export function parseConfig(source: string): AgentToolConfig {
     Object.assign(result[section], settings);
   }
   if (input.images !== undefined) result.images = parseImages(input.images);
+  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}'.`); };
   if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");

package/src/graph/check.ts

@@ -0,0 +1,139 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import type { GraphConfig } from "./config";
+import { relativeImports } from "./scan";
+
+/** Extensions `graph check` scans; declaration files (`.d.ts`, `.d.mts`, `.d.cts`) are skipped. */
+const SOURCE = /\.(?:ts|tsx|mts|cts)$/;
+const DECLARATION = /\.d\.(?:ts|mts|cts)$/;
+// TypeScript resolves an emitted-JavaScript extension to its source.
+const EMITTED: Record<string, string[]> = { ".js": [".ts", ".tsx"], ".jsx": [".tsx"], ".mjs": [".mts"], ".cjs": [".cts"] };
+
+export type Graph = ReadonlyMap<string, ReadonlySet<string>>;
+
+export interface GraphReport {
+  ok: boolean;
+  files: number;
+  imports: number;
+  cycles: string[][];
+  violations: string[];
+  unlayered: string[];
+}
+
+const matcher = (patterns: readonly string[]) => {
+  const globs = patterns.map(pattern => new Bun.Glob(pattern));
+  return (file: string) => globs.some(glob => glob.match(file));
+};
+
+/** Repository-relative POSIX paths of the scanned sources, sorted. */
+export function sourceFiles(root: string, config: GraphConfig): string[] {
+  const excluded = matcher(config.exclude);
+  const files = new Set<string>();
+  for (const pattern of config.include) {
+    // Hidden directories hold sources too; Git metadata and installed packages never do.
+    for (const file of new Bun.Glob(pattern).scanSync({ cwd: root, onlyFiles: true, dot: true })) {
+      const relative = file.split(path.sep).join("/");
+      const parts = relative.split("/");
+      if (SOURCE.test(relative) && !DECLARATION.test(relative) && !parts.includes("node_modules") && !parts.includes(".git") && !excluded(relative)) files.add(relative);
+    }
+  }
+  return [...files].sort();
+}
+
+function isFile(root: string, file: string): boolean {
+  try { return statSync(path.join(root, file)).isFile(); } catch { return false; }
+}
+
+/**
+ * The scanned-or-not source file a relative specifier names: the exact path, an
+ * emitted `.js`/`.jsx`/`.mjs`/`.cjs` name's TypeScript source, an extensionless
+ * `.ts` or `.tsx`, or a directory's `index.ts`/`index.tsx`, in TypeScript's order.
+ */
+export function resolveImport(root: string, from: string, specifier: string): string | undefined {
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier)).replace(/\/+$/, "");
+  if (base.startsWith("../") || base === "..") return undefined;
+  // `.`, `..`, and a trailing slash name a directory, so only its index can match.
+  const directory = /(?:^|\/)\.{1,2}$|\/$/.test(specifier);
+  // `.` is the repository root itself, whose index has no directory prefix.
+  const prefix = base === "." ? "" : `${base}/`;
+  const extension = path.posix.extname(base);
+  const stem = base.slice(0, base.length - extension.length);
+  const candidates = [
+    ...(directory ? [] : [base, ...(EMITTED[extension] ?? []).map(source => stem + source), `${base}.ts`, `${base}.tsx`]),
+    `${prefix}index.ts`, `${prefix}index.tsx`,
+  ];
+  return candidates.find(candidate => SOURCE.test(candidate) && !DECLARATION.test(candidate) && isFile(root, candidate));
+}
+
+/** Edges between scanned files; imports of files outside the scan are leaves. */
+export function importGraph(root: string, files: readonly string[], read = (file: string) => readFileSync(path.join(root, file), "utf8")): Map<string, Set<string>> {
+  const scanned = new Set(files);
+  const graph = new Map<string, Set<string>>();
+  for (const file of files) {
+    const targets = new Set<string>();
+    for (const specifier of relativeImports(read(file))) {
+      const target = resolveImport(root, file, specifier);
+      if (target && scanned.has(target)) targets.add(target);
+    }
+    graph.set(file, targets);
+  }
+  return graph;
+}
+
+/** Each cycle once, rotated to start at its smallest module; at least one per strongly connected component. */
+export function findCycles(graph: Graph): string[][] {
+  const cycles = new Map<string, string[]>();
+  const done = new Set<string>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const visit = (file: string) => {
+    if (onStack.has(file)) {
+      const cycle = stack.slice(stack.indexOf(file));
+      const start = cycle.indexOf([...cycle].sort()[0]!);
+      const rotated = [...cycle.slice(start), ...cycle.slice(0, start)];
+      cycles.set(rotated.join(" -> "), rotated);
+      return;
+    }
+    if (done.has(file)) return;
+    stack.push(file); onStack.add(file);
+    for (const target of [...(graph.get(file) ?? [])].sort()) visit(target);
+    stack.pop(); onStack.delete(file);
+    done.add(file);
+  };
+  for (const file of [...graph.keys()].sort()) visit(file);
+  return [...cycles.values()].sort((a, b) => a.join(" -> ").localeCompare(b.join(" -> ")));
+}
+
+/**
+ * Layer and test-only violations. A file belongs to the first layer, lowest first,
+ * with a matching glob; production files may import only their own layer or lower
+ * ones, and never a test-only file. Test-only files may import anything.
+ */
+export function layerViolations(graph: Graph, config: Pick<GraphConfig, "tests" | "layers">): { violations: string[]; unlayered: string[] } {
+  const isTest = matcher(config.tests);
+  const layers = config.layers.map(layer => matcher(layer.include));
+  const layerOf = (file: string) => layers.findIndex(owns => owns(file));
+  const violations: string[] = [];
+  const unlayered = new Set<string>();
+  for (const [file, targets] of graph) {
+    if (isTest(file)) continue;
+    const from = layerOf(file);
+    if (layers.length && from === -1) unlayered.add(file);
+    for (const target of targets) {
+      if (isTest(target)) { violations.push(`${file} imports test-only ${target}`); continue; }
+      const to = layerOf(target);
+      if (from !== -1 && to > from) violations.push(`${file} (${config.layers[from]!.name}) imports ${target} (${config.layers[to]!.name})`);
+    }
+  }
+  return { violations: violations.sort(), unlayered: [...unlayered].sort() };
+}
+
+export function checkGraph(root: string, config: GraphConfig): GraphReport {
+  if (config.include.length === 0) throw new Error("graph.include is empty; list the sources to scan in the graph section of agent-tool.json.");
+  const files = sourceFiles(root, config);
+  const graph = importGraph(root, files);
+  const cycles = findCycles(graph);
+  const { violations, unlayered } = layerViolations(graph, config);
+  const imports = [...graph.values()].reduce((total, targets) => total + targets.size, 0);
+  return { ok: cycles.length === 0 && violations.length === 0 && unlayered.length === 0, files: files.length, imports, cycles, violations, unlayered };
+}

package/src/graph/config.ts

@@ -0,0 +1,43 @@
+/** The data-only `graph` section of agent-tool.json: which TypeScript files `graph check` scans and their layers. */
+
+export interface GraphLayer { name: string; include: string[] }
+export interface GraphConfig { include: string[]; exclude: string[]; tests: string[]; layers: GraphLayer[] }
+
+export const GRAPH_DEFAULTS: GraphConfig = { include: [], exclude: [], tests: [], layers: [] };
+
+function fail(setting: string): never { throw new Error(`Invalid config setting '${setting}'.`); }
+function object(value: unknown, setting: string, allowed: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Record<string, unknown>;
+}
+
+/** Repository-relative glob: no absolute paths, backslashes, negations, or `.`/`..` segments. */
+function globs(value: unknown, setting: string): string[] {
+  if (!Array.isArray(value)) fail(setting);
+  for (const pattern of value) {
+    if (typeof pattern !== "string" || !pattern || pattern.startsWith("/") || pattern.startsWith("!") || pattern.includes("\\")
+      || pattern.split("/").some(part => !part || part === "." || part === "..")) fail(setting);
+  }
+  return [...value] as string[];
+}
+
+export function parseGraph(value: unknown): GraphConfig {
+  const input = object(value, "graph", Object.keys(GRAPH_DEFAULTS));
+  const result = structuredClone(GRAPH_DEFAULTS);
+  for (const key of ["include", "exclude", "tests"] as const) if (input[key] !== undefined) result[key] = globs(input[key], `graph.${key}`);
+  if (input.layers !== undefined) {
+    if (!Array.isArray(input.layers)) fail("graph.layers");
+    result.layers = input.layers.map((entry, index) => {
+      const setting = `graph.layers[${index}]`;
+      const layer = object(entry, setting, ["name", "include"]);
+      if (typeof layer.name !== "string" || !/^[\w.-]+$/.test(layer.name)) fail(`${setting}.name`);
+      const include = globs(layer.include, `${setting}.include`);
+      if (include.length === 0) fail(`${setting}.include`);
+      return { name: layer.name, include };
+    });
+    const names = result.layers.map(layer => layer.name);
+    if (new Set(names).size !== names.length) throw new Error("graph.layers names must be unique.");
+  }
+  return result;
+}

package/src/graph/scan.ts

@@ -0,0 +1,122 @@
+/**
+ * Import specifiers of a TypeScript source, type-only imports included. TypeScript 7
+ * has no JS compiler API and Bun.Transpiler.scanImports drops type-only imports, so
+ * this tokenizes just enough of the language to tell code from comments, strings,
+ * template text, and regular expression literals, then matches import forms.
+ */
+
+/** Whether a `/` after this code starts a regular expression literal rather than a division. */
+function startsRegex(before: string): boolean {
+  const code = before.trimEnd();
+  // `<` is left out so JSX closing tags (`</a>`) do not read as expressions; `a++ / b` divides.
+  // A postfix `!` after an operand is a non-null assertion (`value! / 2`), not logical not.
+  if (/(?:\+\+|--|[\w$)\]]!)$/.test(code)) return false;
+  return code === "" || /[(,=:[!&|?{};+\-*%>~^]$/.test(code)
+    || /(?<![.$\w])(?:return|typeof|case|in|of|delete|void|throw|new|yield|await|else|do)$/.test(code);
+}
+
+// A string or template right after one of these is a module specifier.
+const SPECIFIER_CONTEXT = /(?:(?<![.$\w])from|(?<![.$\w])import\s*\(?|(?<![.$\w])require\s*\()\s*$/;
+const CALL_CONTEXT = /(?<![.$\w])(?:import|require)\s*\(\s*$/;
+// A `)` closing the condition of one of these is followed by a statement, so a `/` there starts a regex.
+const CONTROL = /(?<![.$\w])(?:if|while|for(?:\s+await)?|with)\s*$/;
+
+/**
+ * Blanks comments, template-literal text, regular expression bodies, and every string
+ * that is not a module specifier, keeping the code inside `${...}` interpolations,
+ * which can import too. Offsets and line breaks are preserved.
+ */
+export function stripNonCode(source: string): string {
+  const out = source.split("");
+  const blank = (from: number, to: number) => { for (let i = from; i < to; i++) if (out[i] !== "\n") out[i] = " "; };
+  // The code before offset i with whitespace runs (including blanked comments) collapsed, so a
+  // long comment between `from` and its specifier cannot push `from` out of view.
+  const before = (i: number) => {
+    let text = "";
+    for (let j = i - 1; j >= 0 && text.length < 40; j--) {
+      if (/\s/.test(out[j]!)) { if (!text.startsWith(" ")) text = ` ${text}`; } else text = out[j] + text;
+    }
+    return text;
+  };
+  const lastCode = (i: number) => { let j = i - 1; while (j >= 0 && /\s/.test(out[j]!)) j--; return j; };
+  const regexAt = (i: number) => {
+    const last = out[lastCode(i)];
+    if (last === ")") return controlClose.has(lastCode(i));
+    // `}/>` closes a JSX element whose last attribute is an expression (`<A x={1}/>`).
+    if (last === "}" && source[i + 1] === ">") return false;
+    return startsRegex(before(i));
+  };
+  // Open parentheses, each true when it opened a control-flow condition, and the offsets of `)`s that closed one.
+  const parens: boolean[] = [];
+  const controlClose = new Set<number>();
+  // Each entry is the brace depth of an open interpolation; template text resumes when it closes.
+  const interpolations: number[] = [];
+  let depth = 0;
+  let i = 0;
+  if (source.startsWith("#!")) { i = source.indexOf("\n"); if (i === -1) i = source.length; blank(0, i); }
+  const skipTemplateText = () => {
+    const start = i;
+    while (i < source.length) {
+      if (source[i] === "\\") { i += 2; continue; }
+      if (source[i] === "`") { blank(start, i); i++; return; }
+      if (source[i] === "$" && source[i + 1] === "{") { blank(start, i); interpolations.push(depth); depth++; i += 2; return; }
+      i++;
+    }
+    blank(start, source.length);
+  };
+  while (i < source.length) {
+    const char = source[i]!;
+    if (char === "/" && source[i + 1] === "/") {
+      const end = source.indexOf("\n", i);
+      const stop = end === -1 ? source.length : end;
+      blank(i, stop); i = stop;
+    } else if (char === "/" && source[i + 1] === "*") {
+      const end = source.indexOf("*/", i + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      blank(i, stop); i = stop;
+    } else if (char === "/" && regexAt(i)) {
+      // Skip to the closing slash, honoring escapes and character classes, where `/` is literal.
+      const start = ++i;
+      let inClass = false;
+      while (i < source.length && source[i] !== "\n" && (inClass || source[i] !== "/")) {
+        if (source[i] === "\\") i++;
+        else if (source[i] === "[") inClass = true;
+        else if (source[i] === "]") inClass = false;
+        i++;
+      }
+      blank(start, Math.min(i, source.length));
+      i++;
+    } else if (char === "\"" || char === "'") {
+      const specifier = SPECIFIER_CONTEXT.test(before(i));
+      const start = ++i;
+      while (i < source.length && source[i] !== char && source[i] !== "\n") i += source[i] === "\\" ? 2 : 1;
+      if (!specifier) blank(start, Math.min(i, source.length));
+      i++;
+    } else if (char === "`") {
+      // A substitution-free template right after `import(` or `require(` is a specifier; keep it.
+      const close = source.indexOf("`", i + 1);
+      const literal = close === -1 ? "" : source.slice(i + 1, close);
+      if (close !== -1 && !literal.includes("${") && !literal.includes("\\") && CALL_CONTEXT.test(before(i))) i = close + 1;
+      else { i++; skipTemplateText(); }
+    } else if (char === "(") { parens.push(CONTROL.test(before(i))); i++; }
+    else if (char === ")") { if (parens.pop()) controlClose.add(i); i++; }
+    else if (char === "{") { depth++; i++; }
+    else if (char === "}") {
+      depth--; i++;
+      if (interpolations.at(-1) === depth) { interpolations.pop(); skipTemplateText(); }
+    } else i++;
+  }
+  return out.join("");
+}
+
+const SPECIFIER = /(?<![.$\w])(?:import|export)(?:\s+type\b)?\s*(?:[\w*{}\s,$"']*?\bfrom\s*)?["']([^"'\n]+)["']|(?<![.$\w])(?:import|require)\s*\(\s*["'`]([^"'`\n]+)["'`]\s*[,)]/g;
+
+/** Every module specifier in source order, bare packages included. */
+export function importSpecifiers(source: string): string[] {
+  return [...stripNonCode(source).matchAll(SPECIFIER)].map(match => (match[1] ?? match[2])!);
+}
+
+/** Relative specifiers (`./` or `../`) in source order; bare packages are leaves of the graph. */
+export function relativeImports(source: string): string[] {
+  return importSpecifiers(source).filter(specifier => specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../"));
+}

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", "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", "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.