@petepetrash/circuit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pete Petrash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+<div align="center">
+  <img src="assets/circuit.png" alt="Circuit" width="100%" />
+</div>
+<h3 align="center"><strong>The process your coding agent follows</strong></h3>
+<br />
+Circuit helps coding agents work like experienced practitioners: following a
+clear process, applying the right skills at the right time, and checking their
+work against evidence. One power dial sets the spend: Circuit picks the model,
+effort, and tools for each step from the step's role, so the reading that
+steers the run stays on the strong tier while routine steps run cheap. It
+gives agents and operators a better working environment than ad-hoc chat.
+
+Circuit is a workflow engine at its core, driven from a plain CLI. The
+Claude Code and Codex plugins are the bridge that teaches a host agent to
+drive that CLI, and today they are also the fastest way to install and try
+Circuit.
+
+Go from this:
+
+- Remember which chat thread has the latest state
+- Remember which skill to use and when
+- Ask for routine planning, checking, and review steps by hand
+- Wonder whether the agent took shortcuts or repeated an old mistake
+- Keep nudging the process forward yourself
+
+To this:
+
+- `/circuit:run build the thing`
+
+Circuit puts the process into a repeatable flow:
+
+- Records the chosen flow, built-in or custom
+- Moves through each step in sequence and/or parallelizes non-dependent steps
+- Applies your preferred skills at the appropriate steps
+- Uses your preferred model(s) and thinking power for particular steps
+- Checks step outputs before continuing, including deterministic relay
+  acceptance criteria where a flow declares them, with traces, reports, and
+  evidence that show what passed
+
+Ready to try it? Pick a host below, or point your coding agent at the setup
+prompt. For the full docs map, see [`docs/README.md`](docs/README.md).
+
+## Start Here
+
+Pick the path that matches where you want to use Circuit. Claude Code and
+Codex reach the same workflow engine through a plugin; Local CLI runs that
+engine directly. If you want a coding agent to set this up for you, skip to
+[`Give This To A Coding Agent`](#give-this-to-a-coding-agent).
+
+### Claude Code
+
+Install the host plugin:
+
+```text
+/plugin marketplace add petekp/circuit
+/plugin install circuit@circuit
+/reload-plugins
+```
+
+Then ask Circuit to handle a task:
+
+```text
+/circuit:run the checkout total is wrong when discounts and tax both apply
+```
+
+A real run spawns worker agents that spend model time: a small task typically
+takes several minutes end to end and costs a few dollars at the default dials.
+Review is read-only and the safest first run. The power dial spends less:
+`--power low` on a CLI run, or `defaults.power` in config.
+
+The installed plugin bundles the whole engine, so you do not need to clone
+this repo, run `npm install`, install a separate `circuit` binary, or
+create a symlink to get started this way.
+
+### Codex
+
+Install the published plugin from the marketplace:
+
+```bash
+codex plugin marketplace add petekp/circuit --ref circuit--v0.1.0
+```
+
+Working from this checkout instead? Refresh the local plugin package and
+installed host caches:
+
+```bash
+npm run plugins:refresh-local
+```
+
+Then ask Codex to use Circuit:
+
+```text
+/circuit:run the checkout total is wrong when discounts and tax both apply
+```
+
+Codex can recommend the right Circuit flow from your natural-language request.
+
+### Local CLI
+
+Install the CLI directly from npm:
+
+```bash
+npm install -g @petepetrash/circuit
+circuit doctor
+circuit run <flow> --goal '<your task>'
+```
+
+Circuit does the work through connector CLIs (`claude` by default), so a
+signed-in Claude Code install is a prerequisite. `circuit doctor` confirms
+the connectors your runs would actually use are ready, before a run
+spends anything on a broken one, and lists any other connector CLI as
+optional.
+
+Working from this checkout instead?
+
+```bash
+npm install
+npm run build
+./bin/circuit run <flow> --goal '<your task>'
+```
+
+The flow name is required: one of `build`, `fix`, `review`, `explore`, or
+`prototype`. The CLI runs from any directory: it prefers compiled flows in
+the current project and falls back to its own bundled copies. The operator
+guide covers pointing at a specific flow folder with `--flow-root`.
+
+Circuit requires Node.js `22.18.0` or newer.
+
+One scope note: flows that change code (`build`, `fix`) verify
+their work through your project's `package.json` scripts (`verify`, `test`,
+or `check`), so today they need an npm-family project. `review`, `explore`,
+and `prototype` work in any repo.
+
+For a more careful manual check, use [`docs/first-run.md`](docs/first-run.md).
+For the repo map, use [`docs/repository-map.md`](docs/repository-map.md).
+
+## Start From An Intent
+
+`/circuit:run` is the normal front door on every host. See
+[`docs/operator-guide.md`](docs/operator-guide.md#front-doors) for the per-host
+table, the CLI flow-name rule, and the host-alias status.
+
+Handoff stays available as a visible continuity utility for saving, resuming,
+clearing, briefing, or installing continuity support. The CLI also has
+experimental utilities that are not published as host commands:
+`./bin/circuit create` drafts a reusable custom flow after explicit
+confirmation, `./bin/circuit generate` composes a runnable bespoke flow from a
+plain task description, and `./bin/circuit preview` shows which connector,
+model, and effort each step of a flow would get, without spawning anything. See
+[`docs/operator-guide.md`](docs/operator-guide.md) for direct commands, flags,
+checkpoints, verification, and troubleshooting.
+
+## Safety Notes
+
+Build, Fix, and Prototype may invoke a write-capable worker. Circuit
+discloses that before write-capable work starts:
+
+> A worker can edit this checkout.
+
+Review collects untracked file paths and sizes by default, but not untracked
+file contents. Add `--include-untracked-content` only after you confirm those
+files are safe to relay.
+
+Built-in worker connectors are **`claude-code`**, **`codex`**, and
+**`cursor-agent`**. Use `claude-code` for trusted Claude Code writes, `codex`
+for first-class Codex worker writes, and `cursor-agent` for Cursor CLI
+implementer work.
+
+Custom connectors use the prompt-file/output-file protocol. stdin is ignored,
+the process inherits the Circuit process environment and current working
+directory, and `capabilities.filesystem: read-only` is a routing signal, not an
+OS sandbox.
+
+## Host And Worker Terms
+
+Codex has two separate roles:
+
+- **host/orchestrator behavior:** in Codex, use `/circuit:run` for a task.
+  Codex can recommend the right Circuit flow and invoke the local Circuit
+  engine.
+- **worker connector behavior:** Circuit can relay worker steps through the
+  Codex CLI from any host, including write-capable implementer steps.
+
+See [`docs/configuration.md`](docs/configuration.md) for connector routing and
+worker setup.
+
+## Configuration
+
+Circuit reads config at run time from:
+
+1. `~/.config/circuit/config.yaml` for your personal defaults across projects.
+2. `./.circuit/config.yaml` at the repo root for project-specific overrides.
+
+Config can set models, effort, local skills, connector routing, and per-flow
+overrides. See [`docs/configuration.md`](docs/configuration.md).
+
+## Give This To A Coding Agent
+
+Paste this into a coding agent when you want it to set up Circuit from a
+checkout safely:
+
+```text
+You are setting up Circuit in this repo: <repo-path>.
+
+Stay inside that checkout. Read README.md and docs/agent-setup.md, then follow
+the setup checklist there. Do not hand-edit generated host output. Preview any
+config YAML before writing it. Use Review as the first real run unless I ask
+for a write-capable flow. Report commands run, files changed, verification
+results, and any blocker.
+```
+
+See [`docs/agent-setup.md`](docs/agent-setup.md) for the full setup checklist.
+
+## Where To Go Next
+
+Start:
+
+- [`docs/first-run.md`](docs/first-run.md): manual setup check, safest Review,
+  and the run folder shape.
+- [`docs/README.md`](docs/README.md): map of the current docs.
+- [`docs/repository-map.md`](docs/repository-map.md): repo map, layer
+  ownership, and migration rationale.
+
+Operate:
+
+- [`docs/operator-guide.md`](docs/operator-guide.md): commands, run flow,
+  checkpoints, verification, and troubleshooting.
+- [`docs/configuration.md`](docs/configuration.md): config layers, local
+  skills, Codex worker setup, and connector routing.
+- [`docs/agent-setup.md`](docs/agent-setup.md): copy-paste setup instructions
+  for a coding agent.
+
+Contribute or verify:
+
+- [`docs/generated-surfaces.md`](docs/generated-surfaces.md): source map for
+  generated command, skill, schematic, and plugin output.
+- [`src/README.md`](src/README.md): source tree map for contributors.
+- [`docs/release/proofs/index.yaml`](docs/release/proofs/index.yaml):
+  checked-in proof set covering doing work, deciding, continuity,
+  customization, failure, first run, and plan execution for this release.
+
+## License
+
+Circuit is released under the [MIT License](LICENSE). You are free to use,
+modify, and redistribute it, including commercially, as long as you keep the
+copyright and license notice.

package/bin/circuit

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { assertNodeVersion } from './node-version-guard.js';
+
+// Fail with a legible message before loading any modern code when the running
+// Node is below the supported floor (package.json engines). No-op otherwise.
+assertNodeVersion();
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(binDir, '..');
+const cliPath = resolve(repoRoot, 'dist/cli/circuit.js');
+
+if (!existsSync(cliPath)) {
+  const tscPath = resolve(repoRoot, 'node_modules/.bin/tsc');
+  if (!existsSync(tscPath)) {
+    process.stderr.write(
+      `error: compiled CLI is missing at ${cliPath}, and TypeScript is not installed at ${tscPath}. Run npm install, then retry.\n`,
+    );
+    process.exit(1);
+  }
+  const result = spawnSync(tscPath, ['-p', resolve(repoRoot, 'tsconfig.build.json')], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    process.stderr.write(`error: failed to build compiled CLI: ${result.error.message}\n`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const { main } = await import(pathToFileURL(cliPath).href);
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  },
+);

package/bin/node-version-guard.d.ts

@@ -0,0 +1,12 @@
+// Types for the plain-JavaScript Node version guard (node-version-guard.js).
+// The guard ships as .js so it runs on a too-old Node; this declaration lets
+// TypeScript callers and tests import it with types.
+
+export declare const REQUIRED_NODE: { readonly major: number; readonly minor: number };
+
+export declare function nodeVersionError(
+  currentVersion: string,
+  required: { readonly major: number; readonly minor: number },
+): string | undefined;
+
+export declare function assertNodeVersion(): void;

package/bin/node-version-guard.js

@@ -0,0 +1,65 @@
+// Node.js version guard for the circuit CLI entry point.
+//
+// This file is deliberately plain, widely-compatible JavaScript. Its whole job
+// is to print a legible error BEFORE circuit loads any modern code, so it must
+// parse and run on whatever (possibly too-old) Node the operator has. Keep it
+// dependency-free and avoid syntax newer than the floor it is meant to catch:
+// no optional chaining, no nullish coalescing, no top-level await.
+
+/** The minimum Node.js the circuit runtime supports (see package.json engines). */
+export const REQUIRED_NODE = { major: 22, minor: 18 };
+
+// Node's unflagged built-in TypeScript type-stripping — which circuit's `.ts`
+// entry points require — arrived on the 22.x LTS line at 22.18, but on the
+// 23.x "Current" line not until 23.6. A Node in the 23.0–23.5 window clears a
+// naive "newer major is fine" check yet still crashes on the first `.ts` import
+// with a raw, illegible error. Map the per-major floor so the guard names the
+// real fix instead of letting that crash through.
+const TYPE_STRIPPING_FLOOR_BY_MAJOR = { 23: 6 };
+
+/**
+ * Return a legible error string when `currentVersion` is below `required`, or
+ * undefined when it satisfies the floor. An unparseable version returns
+ * undefined on purpose: a guard that cannot read the running version must not
+ * block a run it has no evidence is unsupported.
+ *
+ * @param {string} currentVersion e.g. process.versions.node ("22.17.0")
+ * @param {{ major: number, minor: number }} required
+ * @returns {string | undefined}
+ */
+export function nodeVersionError(currentVersion, required) {
+  const parts = String(currentVersion).split('.');
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  if (Number.isNaN(major) || Number.isNaN(minor)) {
+    return undefined;
+  }
+  if (major > required.major) {
+    // A newer major clears the floor, but some lines only gained unflagged
+    // `.ts` stripping mid-release; below that per-major floor a `.ts` import
+    // still crashes even though the major looks new enough.
+    const lineFloor = TYPE_STRIPPING_FLOOR_BY_MAJOR[major];
+    if (lineFloor !== undefined && minor < lineFloor) {
+      return `circuit needs Node.js's built-in TypeScript support, which on the Node.js ${major}.x line arrived in ${major}.${lineFloor}, but you are running Node.js ${currentVersion}.\nUpgrade to Node.js ${major}.${lineFloor} or newer, or use the ${required.major}.${required.minor}+ LTS line, then run circuit again.\n`;
+    }
+    return undefined;
+  }
+  if (major === required.major && minor >= required.minor) {
+    return undefined;
+  }
+  return `circuit requires Node.js ${required.major}.${required.minor} or newer, but you are running Node.js ${currentVersion}.\nUpgrade Node.js (https://nodejs.org) and run circuit again.\n`;
+}
+
+/**
+ * Print the version error and exit(1) when the running Node is too old. A no-op
+ * on a supported Node, so it is safe to call unconditionally at startup.
+ *
+ * @returns {void}
+ */
+export function assertNodeVersion() {
+  const message = nodeVersionError(process.versions.node, REQUIRED_NODE);
+  if (message !== undefined) {
+    process.stderr.write(message);
+    process.exit(1);
+  }
+}

package/dist/app/checkpoints/discover.d.ts

@@ -0,0 +1,63 @@
+import type { BriefGitProbe, StalenessFacts } from '../continuity/brief.js';
+/** One parked-and-resumable run, triaged for the operator. */
+export interface CheckpointRow {
+    readonly run_folder: string;
+    readonly run_id: string;
+    readonly flow_id: string;
+    readonly goal: string;
+    /** The fork the run is waiting on: what it asks and the choices it offers. */
+    readonly checkpoint: {
+        readonly prompt?: string;
+        readonly choices: ReadonlyArray<{
+            readonly id: string;
+            readonly label: string;
+        }>;
+        readonly request_path?: string;
+    };
+    /** The existing per-run resume command. The checkpoints list only links to it. */
+    readonly resume_command: string;
+    /**
+     * Best-effort divergence between the run's captured baseline and the live
+     * repo. Present only when a baseline was resolved AND the probe returned
+     * facts; omitted otherwise so a missing signal never renders a wrong claim.
+     */
+    readonly staleness?: StalenessFacts;
+}
+export interface CheckpointsList {
+    readonly runs_root: string;
+    readonly rows: readonly CheckpointRow[];
+}
+/** A captured git baseline for one run folder, if one is available. */
+export interface CapturedBaseline {
+    readonly head?: string;
+    readonly branch?: string;
+}
+export interface DiscoverCheckpointsListInput {
+    /** `<projectRoot>/.circuit/runs` — see `runsRoot` in control-plane-paths. */
+    readonly runsRoot: string;
+    /** The project root the staleness probe runs against. Defaults to cwd. */
+    readonly projectRoot?: string;
+    /**
+     * Resolve a run folder's captured git baseline for the staleness probe. Run
+     * folders carry no baseline on disk today, so the default resolves none and
+     * every row omits its staleness column. Tests inject a resolver to exercise
+     * the triage column; a later baseline-capture change can wire a real one.
+     */
+    readonly capturedBaselineFor?: (runFolder: string) => CapturedBaseline | undefined;
+    /** Brief-time git divergence probe. Defaulted to the real one. */
+    readonly gitProbe?: BriefGitProbe;
+}
+/**
+ * Resume command for one parked run. The checkpoints list only prints this
+ * link; the operator runs it. Mirrors the canonical per-run resume command
+ * string (`src/runtime/projections/progress.ts`).
+ */
+export declare function checkpointResumeCommand(runFolder: string): string;
+/**
+ * Walk the runs root and triage every parked run into the read model. Folders
+ * that do not parse as a runtime trace, that errored, or that are not parked at
+ * a checkpoint are skipped — only the genuinely resumable `checkpoint_waiting`
+ * shape survives the filter.
+ */
+export declare function discoverCheckpointsList(input: DiscoverCheckpointsListInput): CheckpointsList;
+//# sourceMappingURL=discover.d.ts.map

package/dist/app/checkpoints/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/app/checkpoints/discover.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG5E,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;CACzC;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IACnF,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAwCD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,GAAG,eAAe,CAoD5F"}

package/dist/app/checkpoints/discover.js

@@ -0,0 +1,121 @@
+// Checkpoints list discovery (read model).
+//
+// The frontier use case is "run dozens in parallel, steer at the forks." A run
+// that hits an operator checkpoint parks itself and waits. This module is the
+// aggregate read surface: it walks the runs root, projects each folder through
+// the same per-run projection `circuit runs show` uses, keeps only the runs
+// that genuinely parked at a checkpoint, and triages each one with its fork and
+// a best-effort staleness signal.
+//
+// It is a pure projection. It does NOT resume anything: every listed run links
+// to the existing per-run `circuit resume`, which the operator runs one at a
+// time. Bulk resume is deliberately out of scope here — it can only honor the
+// clean-park shape, and its real value (reviving crashed runs) waits for the
+// durable resumable cursor that does not exist yet. So the filter is the
+// narrow resumable-park predicate (`checkpoint_waiting`), not the broader
+// "needs attention" flag, which also covers dead crashed folders and
+// missing-evidence runs that are not resumable.
+import { readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { realBriefGitProbe } from '../continuity/brief.js';
+import { projectRunStatusFromRunFolder } from '../run-status/run-folder-projector.js';
+/**
+ * Resume command for one parked run. The checkpoints list only prints this
+ * link; the operator runs it. Mirrors the canonical per-run resume command
+ * string (`src/runtime/projections/progress.ts`).
+ */
+export function checkpointResumeCommand(runFolder) {
+    return `circuit resume --run-folder ${runFolder} --checkpoint-choice <choice>`;
+}
+/**
+ * Best-effort staleness probe for one run folder. Returns undefined when no
+ * baseline was resolved OR when the probe throws — a custom probe need not be
+ * crash-safe the way `realBriefGitProbe` is, and a thrown probe must never abort
+ * the whole checkpoints walk and drop every remaining parked run. A throw is
+ * treated as "no signal", exactly like a missing baseline.
+ */
+function probeStaleness(baseline, gitProbe, projectRoot) {
+    if (baseline === undefined)
+        return undefined;
+    try {
+        return gitProbe({
+            projectRoot,
+            ...(baseline.head === undefined ? {} : { capturedHead: baseline.head }),
+            ...(baseline.branch === undefined ? {} : { capturedBranch: baseline.branch }),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function listRunFolders(runsRoot) {
+    let entries;
+    try {
+        entries = readdirSync(runsRoot, { withFileTypes: true });
+    }
+    catch {
+        // A missing or unreadable runs root means no parked runs to list.
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(runsRoot, entry.name))
+        .sort();
+}
+/**
+ * Walk the runs root and triage every parked run into the read model. Folders
+ * that do not parse as a runtime trace, that errored, or that are not parked at
+ * a checkpoint are skipped — only the genuinely resumable `checkpoint_waiting`
+ * shape survives the filter.
+ */
+export function discoverCheckpointsList(input) {
+    const runsRoot = resolve(input.runsRoot);
+    const projectRoot = input.projectRoot ?? process.cwd();
+    const gitProbe = input.gitProbe ?? realBriefGitProbe;
+    const baselineFor = input.capturedBaselineFor ?? (() => undefined);
+    const rows = [];
+    for (const runFolder of listRunFolders(runsRoot)) {
+        let projection;
+        try {
+            projection = projectRunStatusFromRunFolder(runFolder);
+        }
+        catch {
+            // Unreadable or non-folder: not a parked run we can list.
+            continue;
+        }
+        // The resumable-park predicate. Narrower than "needs attention" on purpose:
+        // a dead crashed folder and a missing-evidence run are both attention-worthy
+        // but neither is resumable, so neither belongs in a checkpoints list that
+        // links resume.
+        if (projection.reason !== 'checkpoint_waiting')
+            continue;
+        const baseline = baselineFor(runFolder);
+        const staleness = probeStaleness(baseline, gitProbe, projectRoot);
+        const hasStaleness = staleness !== undefined && Object.keys(staleness).length > 0;
+        rows.push({
+            run_folder: projection.run_folder,
+            run_id: projection.run_id,
+            flow_id: projection.flow_id,
+            goal: projection.goal,
+            checkpoint: {
+                ...(projection.checkpoint.prompt === undefined
+                    ? {}
+                    : { prompt: projection.checkpoint.prompt }),
+                choices: projection.checkpoint.choices.map((choice) => ({
+                    id: choice.id,
+                    label: choice.label,
+                })),
+                ...(projection.checkpoint.request_path === undefined
+                    ? {}
+                    : { request_path: projection.checkpoint.request_path }),
+            },
+            resume_command: checkpointResumeCommand(projection.run_folder),
+            ...(hasStaleness ? { staleness } : {}),
+        });
+    }
+    // Stable ordering: oldest-first by folder so the queue reads top-to-bottom in
+    // the order the runs were started (run folders sort lexicographically, and
+    // listRunFolders already sorted them). Keep it deterministic.
+    return { runs_root: runsRoot, rows };
+}
+//# sourceMappingURL=discover.js.map

package/dist/app/checkpoints/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/app/checkpoints/discover.ts"],"names":[],"mappings":"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"}

package/dist/app/checkpoints/render.d.ts

@@ -0,0 +1,4 @@
+import type { CheckpointsList } from './discover.js';
+/** Render the whole checkpoints list as a printable, plain-English list. */
+export declare function renderCheckpointsList(checkpoints: CheckpointsList): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/app/checkpoints/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/app/checkpoints/render.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,eAAe,CAAC;AAoDpE,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,CAS1E"}

package/dist/app/checkpoints/render.js

@@ -0,0 +1,68 @@
+// Checkpoints list renderer (read model).
+//
+// Turns the triaged checkpoints list into a plain-English list an operator can
+// scan. Each row shows the run's goal, the fork it is waiting on (the
+// checkpoint prompt and the choices it offers), a best-effort staleness line,
+// and the existing per-run resume command to answer it. Short sentences, one
+// idea each.
+/**
+ * A one-line staleness summary for a row, or undefined when there is nothing
+ * trustworthy to say. Mirrors the handoff brief's discipline: only claim a fact
+ * the probe positively established, and stay silent otherwise. This is best
+ * effort — when no captured baseline was available the whole signal is absent.
+ */
+function stalenessLine(staleness) {
+    if (staleness === undefined || Object.keys(staleness).length === 0)
+        return undefined;
+    const parts = [];
+    if (staleness.branch_gone === true) {
+        parts.push(staleness.capture_head_reachable === true
+            ? 'its branch is merged and gone'
+            : 'its branch is gone');
+    }
+    if (staleness.commits_since !== undefined && staleness.commits_since > 0) {
+        const n = staleness.commits_since;
+        parts.push(`${n} commit${n === 1 ? '' : 's'} landed since it parked`);
+    }
+    else if (staleness.head_advanced === true) {
+        parts.push('the repo moved since it parked');
+    }
+    else if (staleness.head_advanced === false &&
+        staleness.tree_clean === true &&
+        staleness.branch_gone !== true) {
+        parts.push('the repo has not moved since it parked');
+    }
+    if (parts.length === 0)
+        return undefined;
+    return `Staleness: ${parts.join('; ')}.`;
+}
+function renderRow(row, index) {
+    const lines = [];
+    lines.push(`${index + 1}. ${row.goal}`);
+    lines.push(`   Flow: ${row.flow_id}  Run: ${row.run_id}`);
+    lines.push(`   Folder: ${row.run_folder}`);
+    if (row.checkpoint.prompt !== undefined) {
+        lines.push(`   Asking: ${row.checkpoint.prompt}`);
+    }
+    const choices = row.checkpoint.choices
+        .map((choice) => (choice.label === choice.id ? choice.id : `${choice.id} (${choice.label})`))
+        .join(', ');
+    lines.push(`   Choices: ${choices}`);
+    const staleness = stalenessLine(row.staleness);
+    if (staleness !== undefined)
+        lines.push(`   ${staleness}`);
+    lines.push(`   Resume: ${row.resume_command}`);
+    return lines.join('\n');
+}
+/** Render the whole checkpoints list as a printable, plain-English list. */
+export function renderCheckpointsList(checkpoints) {
+    if (checkpoints.rows.length === 0) {
+        // Endings point forward: name the natural next command.
+        return 'No runs are waiting on a decision. See recent runs with: circuit runs';
+    }
+    const count = checkpoints.rows.length;
+    const header = `${count} run${count === 1 ? '' : 's'} waiting on a decision:`;
+    const body = checkpoints.rows.map((row, index) => renderRow(row, index)).join('\n\n');
+    return `${header}\n\n${body}`;
+}
+//# sourceMappingURL=render.js.map