toolroll 0.9.59 → 0.9.61

package/dist/checkout-cleanup.d.ts

@@ -64,6 +64,8 @@ export declare function finishedCheckouts(store: Store, now: Date, repo?: string
     taskId: string | null;
     finishedAt: string;
 }[];
+/** Why a checkout stays as a clean-up by hand reads it (in use, or its task not done with it), before its files; null: it may go. */
+export declare function checkoutKeepWhy(pool: WorktreePool, row: WorktreeRow, statuses: ReturnType<typeof taskStatuses>, now: Date): KeepWhy | null;
 /**
  * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
  * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
@@ -92,6 +94,7 @@ export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: ()
     actor: string;
     repo?: string;
     only?: ReadonlySet<string>;
+    spare?: (path: string) => boolean;
 }): Promise<CleanResult>;
 export type SlimResult = {
     slimmed: {

package/dist/checkout-cleanup.js

@@ -242,6 +242,10 @@ function keptFor(pool, row, statuses, now, cleanup) {
     const dueAt = new Date(Date.parse(since) + days * DAY_MS).toISOString();
     return dueAt > now.toISOString() ? { why: "not due yet", taskId, dueAt } : { why: null, taskId };
 }
+/** Why a checkout stays as a clean-up by hand reads it (in use, or its task not done with it), before its files; null: it may go. */
+export function checkoutKeepWhy(pool, row, statuses, now) {
+    return keptFor(pool, row, statuses, now, "manual").why;
+}
 async function eachAtMost(items, limit, work) {
     const out = new Array(items.length);
     let next = 0;
@@ -298,11 +302,16 @@ export async function cleanCheckouts(store, pool, now, options) {
     const sizes = new Map();
     const wanted = (row, fresh) => {
         // Right before a checkout goes, where its task stands is read afresh, and its size taken for the ledger.
+        // `spare`: live work uses it (storage-sweep.ts), asked at both looks.
         if (fresh)
             statuses = taskStatuses(store, now());
-        const go = keptFor(pool, row, statuses, now(), options.manual ? "manual" : cleanup).why === null;
-        if (go && fresh)
+        const go = keptFor(pool, row, statuses, now(), options.manual ? "manual" : cleanup).why === null && options.spare?.(row.path) !== true;
+        if (go && fresh) {
             sizes.set(row.path, diskBytes([row.path]).get(row.path) ?? 0);
+            // du can be slow. The reservation excludes a concurrent checkout lease, and this last read also catches
+            // an open run/claim or task change that arrived while size was measured in the sweep child.
+            return keptFor(pool, row, taskStatuses(store, now()), now(), options.manual ? "manual" : cleanup).why === null && options.spare?.(row.path) !== true;
+        }
         return go;
     };
     const pruned = await pool.prune(rows, wanted, options.manual ? Infinity : AUTO_MAX);

package/dist/cli-fast.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The answers that need nothing but this file: `--version` and the top-level
+ * usage. The bin asks here before importing the CLI, so neither loads the
+ * store, the contracts or a single command family. main() asks here too, so
+ * both roads print the same bytes.
+ */
+/** The line to print and exit 0 with, or null when the CLI has to run. */
+export declare function quickAnswer(argv: readonly string[]): string | null;

package/dist/cli-fast.js

@@ -0,0 +1,18 @@
+/**
+ * The answers that need nothing but this file: `--version` and the top-level
+ * usage. The bin asks here before importing the CLI, so neither loads the
+ * store, the contracts or a single command family. main() asks here too, so
+ * both roads print the same bytes.
+ */
+import { HELP } from "./cli-help.js";
+import { PACKAGE_VERSION } from "./version.js";
+/** Exactly the invocations whose whole answer is top-level usage — anything more goes through the CLI. */
+const HELP_INVOCATIONS = new Set(["--help", "-h", "help"]);
+/** The line to print and exit 0 with, or null when the CLI has to run. */
+export function quickAnswer(argv) {
+    if (argv[0] === "--version" || argv[0] === "-v")
+        return PACKAGE_VERSION;
+    if (argv.length === 1 && HELP_INVOCATIONS.has(argv[0]))
+        return HELP;
+    return null;
+}

package/dist/cli-help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The top-level usage text, on its own so `toolroll --help` can print it
+ * without loading every command family (see cli-fast.ts).
+ */
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)\n  toolroll repos remove <path>\n                                   take it out of the console; its tasks and results stay\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll release <branch> release Toolroll itself: gate, your approval, deploy, merge, tag, publish\n                                   (resumable: rerun to continue; --help)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll health           recent server latency, write waits and live streams\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / worker release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to your lead: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";

package/dist/cli-help.js

@@ -0,0 +1,91 @@
+/**
+ * The top-level usage text, on its own so `toolroll --help` can print it
+ * without loading every command family (see cli-fast.ts).
+ */
+import { DEFAULT_MAX_DEPTH } from "./scan.js";
+export const HELP = `toolroll — a control plane for unattended coding agents
+
+Usage
+  toolroll [path...]        report what is in flight
+  toolroll pulls            report what is waiting on a person
+  toolroll graph            report which work graph is already here
+  toolroll repos            list connected repositories, and how to adjust
+  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)
+  toolroll repos remove <path>
+                                   take it out of the console; its tasks and results stay
+  toolroll repos add-from-github <owner/name> --root <dir>
+                                   preview, then clone and connect (--yes)
+  toolroll link             put \`toolroll\` on your PATH
+  toolroll unlink           take it off again
+  toolroll update           update to the latest release: verified, drained, undoable
+                                   (preview first; --yes, --now, --at HH:MM, --rollback)
+  toolroll release <branch> release Toolroll itself: gate, your approval, deploy, merge, tag, publish
+                                   (resumable: rerun to continue; --help)
+  toolroll contract         the machine contract: envelope version + capabilities
+                                   (--commands dumps the declared command guide)
+  toolroll skills install --claude-code [--dir <path>]
+                                   install this binary's guides for Claude Code (preview first)
+  toolroll skills install   teach a repo's agents this queue exists (preview first)
+  toolroll skills list      the guides this exact binary serves
+  toolroll skills get <name>  print one guide (version-matched, never stale)
+  toolroll demo             a seeded throwaway sandbox — see it working in 90 seconds
+  toolroll up               app + builder for every saved project — the normal start
+  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
+  toolroll status           running, queued, ready results, release check and plan windows
+  toolroll health           recent server latency, write waits and live streams
+  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
+  toolroll lead token       mint your lead agent's credential: its own work pings nobody
+  toolroll lead say "<text>"  (the lead) one short message in its person's chat
+
+Operating the queue — \`toolroll task\` prints the whole surface,
+and any queue command + --help prints it too
+  toolroll approver add <name>
+                               mint the credential that lets a person say yes
+  toolroll ready            what could be dispatched right now
+  toolroll check-progress <run>  current or final approved check progress
+  toolroll task wait <id> [--timeout <seconds>]
+                               wait for this attempt to finish or need a person
+  toolroll task add <title> queue work
+  toolroll task scope <id> --goal <text>
+                               state what success is; approval binds to it
+  toolroll task approve <id>
+                               the yes — nothing builds without one
+  toolroll claim <id> --runner <name>
+  toolroll heartbeat <lease> / worker release <lease> / reap
+  toolroll tick --runner <name> --token <t> --repo <path>
+                               one unattended pass over the ready set
+  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
+                               set up and inspect flows (writes preview until --yes)
+  toolroll chat --as <you> --token <t>
+                               talk to your lead: one conversation across every
+                               project; it proposes, you confirm (--say "…" for one turn)
+  toolroll serve --repo <path>  advanced: run only the console
+                               (--editor vscode with --runner: file links
+                               open in VS Code on the device you browse from)
+  toolroll watch / daemon install   advanced: run only the builder
+  toolroll reconcile        recover what the last stretch left behind
+
+With nothing connected it reports everything it can find below the working
+directory. Once you connect repositories it reports those instead.
+
+Options
+  --all         report everything discoverable, ignoring connected repos
+  --depth <n>   directory levels to descend (default: ${DEFAULT_MAX_DEPTH})
+  --hidden      include dot-directories, which are skipped by default
+  --dirty       also read each working tree for uncommitted files
+  --local       branches only: no network, no pull requests, no issues
+  --json        emit a machine-readable envelope instead of a report
+  -o <file>     also write that envelope to a file (requires --json)
+  -h, --help    show this
+
+Nothing is written, installed, or configured. Every repository is read
+through git with --no-optional-locks, so a scan never contends for the
+index lock with an editor you have open.
+
+--dirty is off by default because reading a working tree is unbounded
+work: on a large or cloud-synced repo \`git status\` can take minutes,
+where listing branches takes milliseconds.
+
+link shows what it would do and changes nothing; add --yes to apply it,
+or --to <dir> to choose where. It never uses sudo, never leaves your
+home directory, and never touches a file it did not create.`;

package/dist/cli.d.ts

@@ -14,9 +14,10 @@ import { previewGithubRepo, cloneGithubRepo } from "./onboard.js";
 import { type SessionCliOptions } from "./session-cli.js";
 import { type TeamCliOptions } from "./team-cli.js";
 import { type RemoteExecOptions } from "./remote-exec.js";
-import { type UpdateCliDeps } from "./toolroll-update-cli.js";
-import { type ReleaseCliDeps } from "./release-cli.js";
-import { type OperateOptions } from "./operate.js";
+import type { UpdateCliDeps } from "./toolroll-update-cli.js";
+import type { ReleaseCliDeps } from "./release-cli.js";
+import type { OperateOptions } from "./operate.js";
+import { HELP } from "./cli-help.js";
 export type CliOptions = {
     roots: string[];
     /** The positional tokens exactly as typed, index-aligned with `roots` —
@@ -41,7 +42,8 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)\n  toolroll repos remove <path>\n                                   take it out of the console; its tasks and results stay\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll release <branch> release Toolroll itself: gate, your approval, deploy, merge, tag, publish\n                                   (resumable: rerun to continue; --help)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll health           recent server latency, write waits and live streams\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / worker release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to your lead: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+/** The top-level usage text (cli-help.ts), re-exported where it always lived. */
+export { HELP };
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with
@@ -143,4 +145,3 @@ export declare const CONTRACT_FLAGS: readonly ["json", "commands"];
 export declare function isDirectInvocation(moduleUrl: string, entry: string | undefined, toRealPath?: (path: string) => string): boolean;
 /** The process entry the bin calls: the SQLite notice hushed, the exit code set. */
 export declare function runCliProcess(argv: readonly string[]): Promise<void>;
-export {};

package/dist/cli.js

@@ -29,106 +29,23 @@ import { runSessionCommand, SESSION_CLI_ACTIONS } from "./session-cli.js";
 import { maybeRunTeamCommand, TEAM_CLI_ACTIONS } from "./team-cli.js";
 import { deprecationWarning } from "./deprecations.js";
 import { maybeRunRemoteCommand } from "./remote-exec.js";
-import { runHealthCommand } from "./health-cli.js";
 import { discover, inspectAll } from "./discover.js";
 import { readPulls } from "./pulls.js";
 import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } from "./graph.js";
 import { openStore, openStoreReadOnly, databasePath } from "./store.js";
-import { PACKAGE_VERSION } from "./version.js";
-import { runUpdateCommand } from "./toolroll-update-cli.js";
-import { runReleaseCommand } from "./release-cli.js";
-import { runOperate, OPERATE_HELP } from "./operate.js";
 import { renderReport, renderPulls, renderGraph } from "./render.js";
-import { readRemote } from "./remote.js";
 import { DEFAULT_MAX_DEPTH } from "./scan.js";
+import { HELP } from "./cli-help.js";
+import { quickAnswer } from "./cli-fast.js";
 import { BIN_NAME, chooseTarget, planLink, applyLink, planUnlink, applyUnlink, } from "./link.js";
 const USAGE_EXIT = 2;
-export const HELP = `toolroll — a control plane for unattended coding agents
-
-Usage
-  toolroll [path...]        report what is in flight
-  toolroll pulls            report what is waiting on a person
-  toolroll graph            report which work graph is already here
-  toolroll repos            list connected repositories, and how to adjust
-  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)
-  toolroll repos remove <path>
-                                   take it out of the console; its tasks and results stay
-  toolroll repos add-from-github <owner/name> --root <dir>
-                                   preview, then clone and connect (--yes)
-  toolroll link             put \`toolroll\` on your PATH
-  toolroll unlink           take it off again
-  toolroll update           update to the latest release: verified, drained, undoable
-                                   (preview first; --yes, --now, --at HH:MM, --rollback)
-  toolroll release <branch> release Toolroll itself: gate, your approval, deploy, merge, tag, publish
-                                   (resumable: rerun to continue; --help)
-  toolroll contract         the machine contract: envelope version + capabilities
-                                   (--commands dumps the declared command guide)
-  toolroll skills install --claude-code [--dir <path>]
-                                   install this binary's guides for Claude Code (preview first)
-  toolroll skills install   teach a repo's agents this queue exists (preview first)
-  toolroll skills list      the guides this exact binary serves
-  toolroll skills get <name>  print one guide (version-matched, never stale)
-  toolroll demo             a seeded throwaway sandbox — see it working in 90 seconds
-  toolroll up               app + builder for every saved project — the normal start
-  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
-  toolroll status           running, queued, ready results, release check and plan windows
-  toolroll health           recent server latency, write waits and live streams
-  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
-  toolroll lead token       mint your lead agent's credential: its own work pings nobody
-  toolroll lead say "<text>"  (the lead) one short message in its person's chat
-
-Operating the queue — \`toolroll task\` prints the whole surface,
-and any queue command + --help prints it too
-  toolroll approver add <name>
-                               mint the credential that lets a person say yes
-  toolroll ready            what could be dispatched right now
-  toolroll check-progress <run>  current or final approved check progress
-  toolroll task wait <id> [--timeout <seconds>]
-                               wait for this attempt to finish or need a person
-  toolroll task add <title> queue work
-  toolroll task scope <id> --goal <text>
-                               state what success is; approval binds to it
-  toolroll task approve <id>
-                               the yes — nothing builds without one
-  toolroll claim <id> --runner <name>
-  toolroll heartbeat <lease> / worker release <lease> / reap
-  toolroll tick --runner <name> --token <t> --repo <path>
-                               one unattended pass over the ready set
-  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
-                               set up and inspect flows (writes preview until --yes)
-  toolroll chat --as <you> --token <t>
-                               talk to your lead: one conversation across every
-                               project; it proposes, you confirm (--say "…" for one turn)
-  toolroll serve --repo <path>  advanced: run only the console
-                               (--editor vscode with --runner: file links
-                               open in VS Code on the device you browse from)
-  toolroll watch / daemon install   advanced: run only the builder
-  toolroll reconcile        recover what the last stretch left behind
-
-With nothing connected it reports everything it can find below the working
-directory. Once you connect repositories it reports those instead.
-
-Options
-  --all         report everything discoverable, ignoring connected repos
-  --depth <n>   directory levels to descend (default: ${DEFAULT_MAX_DEPTH})
-  --hidden      include dot-directories, which are skipped by default
-  --dirty       also read each working tree for uncommitted files
-  --local       branches only: no network, no pull requests, no issues
-  --json        emit a machine-readable envelope instead of a report
-  -o <file>     also write that envelope to a file (requires --json)
-  -h, --help    show this
-
-Nothing is written, installed, or configured. Every repository is read
-through git with --no-optional-locks, so a scan never contends for the
-index lock with an editor you have open.
-
---dirty is off by default because reading a working tree is unbounded
-work: on a large or cloud-synced repo \`git status\` can take minutes,
-where listing branches takes milliseconds.
-
-link shows what it would do and changes nothing; add --yes to apply it,
-or --to <dir> to choose where. It never uses sudo, never leaves your
-home directory, and never touches a file it did not create.`;
+/** The queue's commands live in operate.ts, the largest module graph here: loaded when one of them runs, not before. */
+async function runOperate(command, argv, write, options) {
+    const operate = await import("./operate.js");
+    return operate.runOperate(command, argv, write, options);
+}
+/** The top-level usage text (cli-help.ts), re-exported where it always lived. */
+export { HELP };
 export function parseArgs(argv) {
     const roots = [];
     const rawRoots = [];
@@ -290,8 +207,9 @@ export function extractOutputFlag(argv) {
     return { args, ...(outputFile === undefined ? {} : { outputFile }) };
 }
 export async function main(argv, write = line => console.log(line), mainOptions = {}) {
-    if (argv[0] === "--version" || argv[0] === "-v") {
-        write(PACKAGE_VERSION);
+    const quick = quickAnswer(argv);
+    if (quick !== null) {
+        write(quick);
         return 0;
     }
     const extracted = extractOutputFlag(argv);
@@ -392,8 +310,9 @@ async function dispatch(argv, write, mainOptions) {
     if (argv[0] === "routine")
         return routinesMoved(argv, write);
     // A saved API token sends commands marked remote to the central server, before anything local opens.
+    // Command families below load when their command runs, so one command never pays for the others.
     if (argv[0] === 'health')
-        return runHealthCommand(argv.slice(1), write, mainOptions.team ?? mainOptions.remote);
+        return (await import("./health-cli.js")).runHealthCommand(argv.slice(1), write, mainOptions.team ?? mainOptions.remote);
     const central = await maybeRunRemoteCommand(argv, mainOptions.remote ?? mainOptions.team);
     if (typeof central === "number")
         return central;
@@ -415,8 +334,9 @@ async function dispatch(argv, write, mainOptions) {
         return runLinkCommand(first, rest, write, mainOptions.binSource);
     }
     if (first === "update")
-        return runUpdateCommand(rest, write, mainOptions.update);
+        return (await import("./toolroll-update-cli.js")).runUpdateCommand(rest, write, mainOptions.update);
     if (first === "release") {
+        const { runReleaseCommand } = await import("./release-cli.js");
         return runReleaseCommand(rest, write, { releaseLease: lease => runOperate("worker", ["release", ...lease], write, mainOptions.operate ?? {}), ...mainOptions.release });
     }
     if (first === "contract")
@@ -500,6 +420,7 @@ async function dispatch(argv, write, mainOptions) {
 async function maybeReadRemote(repos, options) {
     if (options.local)
         return undefined;
+    const { readRemote } = await import("./remote.js");
     return readRemote(repos.map(repo => ({ path: repo.path, remoteUrl: repo.remoteUrl })));
 }
 function configFile() {

package/dist/contracts/console-api.d.ts

@@ -156,7 +156,8 @@ export declare const CONSOLE_FORMS: {
     readonly revise: FormContract<"batch" | "return" | "source">;
     readonly followUp: FormContract<"level" | "return">;
     readonly resolveIncident: FormContract<"return">;
-    readonly taskSteer: FormContract<"note">;
+    readonly taskSteer: FormContract<"note" | "return" | "run">;
+    readonly taskReply: FormContract<"answer" | "question">;
     readonly taskHold: FormContract<"reason">;
     readonly taskBlock: FormContract<"on">;
     readonly taskRepairDependency: FormContract<"blocker" | "operation" | "replacement">;
@@ -173,6 +174,7 @@ export declare const CONSOLE_FORMS: {
     readonly taskAcceptProof: FormContract<"note" | "return" | "run">;
     readonly taskComplete: FormContract<"accept" | "note" | "publish" | "receipt" | "return" | "run">;
     readonly taskStop: FormContract<"return" | "run">;
+    readonly taskPause: FormContract<"mode" | "note" | "request" | "return" | "run">;
     readonly taskResume: FormContract<"nonce" | "return" | "run" | "token">;
 };
 export type ConsoleFormName = keyof typeof CONSOLE_FORMS;

package/dist/contracts/console-api.js

@@ -167,7 +167,8 @@ export const CONSOLE_FORMS = {
     followUp: formContract("POST /r/<run>/checks|add-tests", ["return", "level"]),
     resolveIncident: formContract("POST /i/<id>/resolve", ["return"]),
     // A task's verbs (/t/<task>/<verb>), one body each.
-    taskSteer: formContract("POST /t/<task>/steer", ["note"]),
+    taskSteer: formContract("POST /t/<task>/steer", ["note", "return", "run"]),
+    taskReply: formContract("POST /t/<task>/reply", ["question", "answer"]),
     taskHold: formContract("POST /t/<task>/hold", ["reason"]),
     taskBlock: formContract("POST /t/<task>/block|unblock", ["on"]),
     taskRepairDependency: formContract("POST /t/<task>/repair-dependency", ["blocker", "operation", "replacement"]),
@@ -184,6 +185,9 @@ export const CONSOLE_FORMS = {
     taskAcceptProof: formContract("POST /t/<task>/accept-proof", ["run", "note", "return"]),
     taskComplete: formContract("POST /t/<task>/complete", ["receipt", "run", "accept", "note", "publish", "return"]),
     taskStop: formContract("POST /t/<task>/stop", ["run", "return"]),
+    // Pause, or Pause and steer when a note rides along, or Resume (mode=resume): the exact run shown, and the page's own
+    // request id.
+    taskPause: formContract("POST /t/<task>/pause", ["run", "request", "note", "mode", "return"]),
     taskResume: formContract("POST /t/<task>/resume|resume-arm", ["run", "token", "nonce", "return"]),
 };
 /** The console POSTs whose handlers read no field (sign-out not even the shared guard): their contract is the empty form. */

package/dist/contracts/lead-tools.d.ts

@@ -656,7 +656,14 @@ export declare const LEAD_TOOL_INPUTS: {
     }, z.core.$strict>;
     readonly propose_steer: z.ZodObject<{
         task: z.ZodString;
-        note: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            note: "note";
+            pause: "pause";
+            "pause-and-steer": "pause-and-steer";
+            resume: "resume";
+        }>>;
+        question: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     readonly propose_dependency_repair: z.ZodObject<{
         task: z.ZodString;
@@ -1318,7 +1325,14 @@ export declare const LEAD_TOOL_READ_INPUTS: {
     }, z.core.$strict>;
     readonly propose_steer: z.ZodObject<{
         task: z.ZodString;
-        note: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            note: "note";
+            pause: "pause";
+            "pause-and-steer": "pause-and-steer";
+            resume: "resume";
+        }>>;
+        question: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     readonly propose_dependency_repair: z.ZodObject<{
         task: z.ZodString;

package/dist/contracts/lead-tools.js

@@ -130,7 +130,11 @@ export const LEAD_TOOL_INPUTS = {
     propose_reserve: z.strictObject({ task: taskRef, worker: text("workerName").nullable() }),
     propose_hold: z.strictObject({ task: taskRef, reason: text("proposalReason") }),
     propose_unhold: z.strictObject({ task: taskRef }),
-    propose_steer: z.strictObject({ task: taskRef, note }),
+    // mode: a note (the default), Pause (stop a running Claude build's turn, keep the build), Pause and steer, or Resume
+    // (a paused build goes on where it stopped, without a note).
+    // question: a running agent's open question (Agents board); the note is its reply, sent as an ordinary note.
+    propose_steer: z.strictObject({ task: taskRef, note: note.optional(), mode: z.enum(["note", "pause", "pause-and-steer", "resume"]).optional(),
+        question: z.number().int().positive().optional().describe("A running agent's open question (get_task agentQuestions): the note becomes its reply and closes it.") }),
     propose_dependency_repair: z.strictObject({ task: taskRef, blocker: taskRef, operation: z.enum(["retry", "unlink", "replace"]), replacement: taskRef.optional() }),
     propose_scope: z.strictObject({ task: taskRef, goal: scopeText, not: scopeText.nullable().optional(), touches: touches.optional(), acceptance }),
     propose_agents: z.strictObject({