toolroll 0.9.92 → 0.9.94

package/dist/checkout-cleanup.js

@@ -5,14 +5,22 @@
  * 2 days or a week after that, or never (only a clean-up by hand). A clean-up by hand doesn't wait for the setting.
  * Only the working copy goes: its branch, and so every commit, stays, and a later lease of the branch makes a new one.
  *
- * Always kept: a checkout in use, one whose task isn't finished (on hold, failed, a revision under way), a result
- * still waiting for review, a checkout with changes (files Toolroll wrote itself aside), and one with commits on no
- * branch. A release check's checkout (a deploy installs from it) goes once its task is complete, with its dependency
+ * Kept until idle (below): one whose task isn't finished (on hold, failed, a revision under way) and a result still
+ * waiting for review. Always kept: a checkout in use, one with changes (files Toolroll wrote itself aside), and one
+ * with commits on no branch. A release check's checkout (a deploy installs from it) goes once its task is complete, with its dependency
  * install and journey output, except the one deployed now and the project's newest complete one still waiting for its
  * deploy (no deploy since it was complete; at most a week). A superseded or cancelled gate goes at once, whatever its
  * task's state (staged releases keep the rollback copy). A checkout no task names (adopted after a crash) goes only
  * in a clean-up by hand. Every removal is in the ledger.
  *
+ * Idle checkouts go too (the idle limit, 14 days by default): one whose whole task family has been idle that long (no
+ * run, no person's act, no open lease) goes even with its result waiting for review or its task unfinished, in the
+ * storage sweep's child only, never in a clean-up by hand, and only when `WorktreePool.proveRecreatable` says nothing is lost.
+ * Nothing needs that working copy: a result page, Accept, Send back and Run checks read saved evidence and the branch,
+ * and a retry, revision or resume leases the branch, which makes a new one. Excluded, because that can't be proven: a
+ * release gate (a deploy installs from its checkout), work from an external tracker, and a checkout no task names. A
+ * checkout with uncommitted changes is never removed by this; it is listed for a person.
+ *
  * A kept checkout waiting for review or with changes drops its dependencies and build output once its run ends
  * (`slimKeptCheckouts`); the next run's setup restores them.
  */
@@ -21,7 +29,8 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { taskBranches } from "./names.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
-import { CLEANUP_CHOICES, bytesWords, diskBytes, diskBytesAsync } from "./storage.js";
+import { CLEANUP_CHOICES, IDLE_CHOICES, bytesWords, diskBytes, diskBytesAsync } from "./storage.js";
+import { checkoutIdle } from "./store.js";
 import { worktreePath } from "./worktree.js";
 const DAY_MS = 86_400_000;
 /** A release candidate's checkout holds the build a deploy installs: the newest complete one waits at most a week for it. */
@@ -218,6 +227,114 @@ export function finishedCheckouts(store, now, repo) {
         return [{ row, taskId: status.taskId, finishedAt: status.finishedAt }];
     });
 }
+/** Toolroll's own bookkeeping about a task: none of it is anyone using the task. Every other ledger entry counts as activity. */
+const NOT_ACTIVITY = ["assignment status baseline", "assignment status observed", "task archived", "checkout removed", "checkout slimmed", "checkout processes stopped",
+    "run processes stopped", "orphan process stopped", "process observation failed", "process witness settled", "branch deleted", "landed work cleaned up"];
+/**
+ * When each task family last saw a run, a person's act or a lease, read in one pass. A revision builds on what it
+ * revises, so a family is idle together. `blocked`: an open run, an unreleased claim, a release gate, or a task only an
+ * external tracker knows, in the family.
+ */
+export function idleFacts(store) {
+    const db = store.handle;
+    const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.created_at AS created_at, t.updated_at AS updated_at,
+      (SELECT MAX(s.candidate) FROM task_scope s WHERE s.task_id = r.external_id) AS candidate
+    FROM task_ref r LEFT JOIN task t ON t.id = r.external_id AND r.backend = 'built-in'`).all();
+    const parentOf = new Map(refs.filter(row => row["revision_of"] !== null).map(row => [String(row["id"]), String(row["revision_of"])]));
+    const rootOf = (id) => {
+        const seen = new Set([id]);
+        let root = id;
+        for (let parent = parentOf.get(root); parent !== undefined && !seen.has(parent); parent = parentOf.get(root)) {
+            seen.add(parent);
+            root = parent;
+        }
+        return root;
+    };
+    const families = new Map();
+    const rootByRef = new Map();
+    const rootsById = new Map();
+    const note = (root, at, blocked = false) => {
+        if (root === undefined)
+            return;
+        const fact = families.get(root) ?? { activeAt: "", blocked: false };
+        if (typeof at === "string" && at > fact.activeAt)
+            fact.activeAt = at;
+        if (blocked)
+            fact.blocked = true;
+        families.set(root, fact);
+    };
+    for (const row of refs) {
+        const id = String(row["id"]), root = rootOf(id);
+        rootByRef.set(Number(row["ref"]), root);
+        rootsById.set(id, root);
+        note(root, row["created_at"]);
+        note(root, row["updated_at"], row["state"] === null || row["candidate"] !== null);
+    }
+    const byTaskRef = (at, ref, blocked = false) => note(rootByRef.get(Number(ref)), at, blocked);
+    const runRoot = new Map();
+    const branches = [];
+    for (const row of db.prepare("SELECT id, task_ref, branch, started_at, finished_at FROM run").all()) {
+        const root = rootByRef.get(Number(row["task_ref"]));
+        runRoot.set(Number(row["id"]), root);
+        note(root, row["started_at"], row["finished_at"] === null);
+        note(root, row["finished_at"]);
+        if (root !== undefined && row["branch"] !== null)
+            branches.push([String(row["branch"]), root]);
+    }
+    for (const row of db.prepare("SELECT task_ref, acquired_at, heartbeat_at, released_at FROM claim").all()) {
+        for (const at of [row["acquired_at"], row["heartbeat_at"], row["released_at"]])
+            byTaskRef(at, row["task_ref"]);
+        byTaskRef(null, row["task_ref"], row["released_at"] === null);
+    }
+    for (const row of db.prepare("SELECT task_ref, held_at AS at FROM hold UNION ALL SELECT task_ref, created_at FROM task_steer UNION ALL SELECT task_ref, at FROM task_act").all())
+        byTaskRef(row["at"], row["task_ref"]);
+    for (const row of db.prepare("SELECT run, created_at AS at FROM run_note UNION ALL SELECT run, created_at FROM diff_comment UNION ALL SELECT run, created_at FROM decision UNION ALL SELECT run, answered_at FROM decision").all()) {
+        note(runRoot.get(Number(row["run"])), row["at"]);
+    }
+    for (const row of db.prepare(`SELECT task_id, run_id, MAX(at) AS at FROM action_ledger WHERE (task_id IS NOT NULL OR run_id IS NOT NULL)
+    AND action NOT IN (SELECT value FROM json_each(?)) GROUP BY task_id, run_id`).all(JSON.stringify(NOT_ACTIVITY))) {
+        if (row["task_id"] !== null)
+            note(rootsById.get(String(row["task_id"])), row["at"]);
+        if (row["run_id"] !== null)
+            note(runRoot.get(Number(row["run_id"])), row["at"]);
+    }
+    const byRef = new Map();
+    for (const [ref, root] of rootByRef)
+        byRef.set(ref, families.get(root));
+    // A branch answers for every family that used it: the newest activity and any block among them.
+    const byBranch = new Map();
+    const share = (branch, root) => {
+        const one = families.get(root), seen = byBranch.get(branch);
+        byBranch.set(branch, seen === undefined ? { ...one } : { activeAt: seen.activeAt > one.activeAt ? seen.activeAt : one.activeAt, blocked: seen.blocked || one.blocked });
+    };
+    for (const row of refs)
+        for (const branch of taskBranches(String(row["id"])))
+            share(branch, rootOf(String(row["id"])));
+    for (const [branch, root] of branches)
+        share(branch, root);
+    return { byRef, byBranch };
+}
+/** The idle limit in days as it stands: null when idle cleanup is off (the limit, or automatic cleanup altogether). */
+function idleDays(store) {
+    return store.checkoutCleanup() === "never" ? null : IDLE_CHOICES.find(one => one.value === checkoutIdle(store)).days;
+}
+/** When this checkout's task last saw activity, when that is past the limit and only its task's standing keeps it; else null. */
+function idleSince(pool, row, statuses, facts, days, now) {
+    if (days === null || row.taskRef === null || row.branch === "unknown" || row.releasedAt === null || row.runner !== null || pool.inUse(row.path).held)
+        return null;
+    const keep = statusOf(row, statuses)?.keep;
+    if (keep !== "waiting for review" && keep !== "task not finished")
+        return null;
+    const own = facts.byRef.get(row.taskRef), shared = facts.byBranch.get(row.branch);
+    if (own === undefined || own.blocked || shared?.blocked === true)
+        return null;
+    const since = [own.activeAt, shared?.activeAt, row.createdAt, row.leasedAt, row.releasedAt].filter((one) => typeof one === "string").sort().at(-1);
+    return Date.parse(since) + days * DAY_MS <= now.getTime() ? since : null;
+}
+/** Every commit a task's runs recorded on this checkout or its branch: what `proveRecreatable` must find on a branch. */
+function recordedHeads(store, row) {
+    return store.handle.prepare("SELECT DISTINCT head_revision AS head FROM run WHERE (branch = ? OR worktree = ?) AND head_revision IS NOT NULL").all(row.branch, row.path).map(one => String(one["head"]));
+}
 /** Why a checkout stays before anyone looks at its files, or null: it may go (as far as its task and the setting say). */
 function keptFor(pool, row, statuses, now, cleanup) {
     const status = statusOf(row, statuses);
@@ -266,6 +383,8 @@ export async function checkoutPlan(store, pool, now, options) {
     const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo));
     const sizes = await diskBytesAsync(rows.map(row => row.path));
     const statuses = taskStatuses(store, now);
+    const days = idleDays(store);
+    const facts = idleFacts(store);
     const items = await eachAtMost(rows, INSPECT_AT_ONCE, async (row) => {
         const kept = keptFor(pool, row, statuses, now, options.manual ? "manual" : cleanup);
         let why = kept.why;
@@ -273,14 +392,23 @@ export async function checkoutPlan(store, pool, now, options) {
             const found = await pool.inspect(row.path);
             why = found === "clean" ? null : found;
         }
-        return { path: row.path, repo: row.repo, branch: row.branch, taskId: kept.taskId, bytes: sizes.get(row.path) ?? 0, releasedAt: row.releasedAt, why, ...(kept.dueAt === undefined ? {} : { dueAt: kept.dueAt }) };
+        const since = kept.why === null ? null : idleSince(pool, row, statuses, facts, days, now);
+        if (since !== null) {
+            const found = await pool.inspect(row.path);
+            const proven = found === "clean" ? await pool.proveRecreatable(row, recordedHeads(store, row)) : found;
+            why = proven !== "clean" ? proven : options.manual ? "idle" : null;
+        }
+        return { path: row.path, repo: row.repo, branch: row.branch, taskId: kept.taskId, bytes: sizes.get(row.path) ?? 0, releasedAt: row.releasedAt, why,
+            ...(kept.dueAt === undefined ? {} : { dueAt: kept.dueAt }), ...(since === null ? {} : { idleSince: since }) };
     });
     const go = items.filter(one => one.why === null).sort((a, b) => b.bytes - a.bytes);
     const stay = items.filter(one => one.why !== null).sort((a, b) => (a.why ?? "").localeCompare(b.why ?? "") || b.bytes - a.bytes);
+    const idle = items.filter(one => one.idleSince !== undefined && (one.why === null || one.why === "idle"));
     return {
-        at: now.toISOString(), cleanup, manual: options.manual, go, stay,
+        at: now.toISOString(), cleanup, idle: checkoutIdle(store), manual: options.manual, go, stay,
         count: items.length, totalBytes: items.reduce((sum, one) => sum + one.bytes, 0), freeBytes: go.reduce((sum, one) => sum + one.bytes, 0),
         waitingReview: stay.filter(one => one.why === "waiting for review").length, withChanges: stay.filter(one => one.why === "has changes").length,
+        idleCount: idle.length, idleBytes: idle.reduce((sum, one) => sum + one.bytes, 0),
     };
 }
 /** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
@@ -290,7 +418,9 @@ export function previewDigest(plan) {
 /**
  * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
  * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
- * the ledger.
+ * the ledger. Idle checkouts go only with `idle`, the storage sweep's child (never the service's own pass, whose git
+ * and du must not hold up its heartbeats): each is judged again from a fresh read of its task and its family's
+ * activity, `spare` (live work), the OS's list of what runs in the folder, and `proveRecreatable`, inside its reservation.
  */
 export async function cleanCheckouts(store, pool, now, options) {
     const cleanup = store.checkoutCleanup();
@@ -299,31 +429,51 @@ export async function cleanCheckouts(store, pool, now, options) {
     // `only`: the checkouts a person saw in the preview; nothing they didn't see goes.
     const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo) && (options.only === undefined || options.only.has(row.path)));
     let statuses = taskStatuses(store, now());
+    const days = options.idle === undefined ? null : idleDays(store);
+    let facts = days === null ? { byRef: new Map(), byBranch: new Map() } : idleFacts(store);
+    // The checkouts going for being idle, and since when: judged at every look, so a task coming back drops out.
+    const idle = new Map();
+    const mayGo = (row) => {
+        idle.delete(row.path);
+        if (keptFor(pool, row, statuses, now(), options.manual ? "manual" : cleanup).why === null)
+            return options.spare?.(row.path) !== true;
+        const since = idleSince(pool, row, statuses, facts, days, now());
+        if (since === null)
+            return false;
+        idle.set(row.path, since);
+        return options.spare?.(row.path) !== true;
+    };
+    const refresh = () => { statuses = taskStatuses(store, now()); if (days !== null)
+        facts = idleFacts(store); };
     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 && options.spare?.(row.path) !== true;
+            refresh();
+        const go = mayGo(row);
         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;
+            refresh();
+            return mayGo(row) && !(idle.has(row.path) && options.idle?.occupied(row.path) === true);
         }
         return go;
     };
-    const pruned = await pool.prune(rows, wanted, options.manual ? Infinity : AUTO_MAX);
+    const proof = async (row) => idle.has(row.path) ? pool.proveRecreatable(row, recordedHeads(store, row)) : "clean";
+    const max = options.manual ? Infinity : AUTO_MAX;
+    const pruned = await pool.prune(rows, wanted, max, undefined, proof);
     const removed = [];
     for (const row of pruned.removed) {
         const taskId = row.taskRef === null ? null : store.externalIdFor(row.taskRef);
         const bytes = sizes.get(row.path) ?? 0;
-        removed.push({ path: row.path, repo: row.repo, branch: row.branch, taskId, bytes, releasedAt: row.releasedAt, why: null });
+        const since = idle.get(row.path);
+        removed.push({ path: row.path, repo: row.repo, branch: row.branch, taskId, bytes, releasedAt: row.releasedAt, why: null, ...(since === undefined ? {} : { idleSince: since }) });
         store.recordAction({ at: now().toISOString(), actor: options.actor, repo: row.repo, taskId, runId: null, action: "checkout removed", outcome: "removed",
-            source: options.manual ? "request" : "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"}, about ${bytesWords(bytes)}); branch ${row.branch} kept` });
+            source: options.manual ? "request" : "work", detail: `${basename(row.path)} (${since === undefined ? "" : `idle since ${since.slice(0, 10)}, `}released ${row.releasedAt?.slice(0, 10) ?? "?"}, about ${bytesWords(bytes)}); branch ${row.branch} kept` });
     }
-    return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0) };
+    return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0), ...(pruned.removed.length >= max ? { more: true } : {}) };
 }
 /** Checkouts this process already looked at since they were let go (path and release time): looked at once. */
 const looked = new Set();
@@ -381,6 +531,8 @@ export function whyWords(item) {
         case "release candidate": return item.dueAt === undefined ? "the deployed release candidate" : `newest release candidate, kept for its deploy until ${item.dueAt.slice(0, 10)}`;
         case "has changes": return "has changes";
         case "has commits": return "has commits on no branch";
+        case "not on its branch": return "isn't on its task's branch";
+        case "idle": return `idle since ${item.idleSince?.slice(0, 10) ?? "a while"}; the next sweep removes it`;
         case "unreadable": return "git couldn't read it";
         case "git refused": return "git wouldn't remove it";
         case "not due yet": return `due ${item.dueAt?.slice(0, 10) ?? "later"}`;

package/dist/cli-help.d.ts

@@ -2,4 +2,7 @@
  * 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                  at your terminal: start Toolroll here (or attach) and open it in the terminal\n                                   (--web: the browser; --project-root <dir>: where projects live)\n                                   in a repository without a terminal, under an agent or with --json: only says what it would do\n  toolroll open [--web]     open this computer's Toolroll again, signed in\n  toolroll welcome          the three steps to a first result (--json: the model)\n  toolroll password set     add a password (typed twice, at your terminal)\n  toolroll scan [path...]   report what is in flight (also bare `toolroll` outside a repository)\n  toolroll [path...]        the same report for the paths given\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 doctor           check that Toolroll's service holds no key a build could read\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.";
+export declare const HELP = "toolroll \u2014 hand coding work to agents, walk away, come back to pull requests\n\nUsage\n  toolroll                  at your terminal: start Toolroll here (or attach) and open it in the terminal\n                                   (--web: the browser; --project-root <dir>: where projects live)\n                                   in a repository without a terminal, under an agent or with --json: only says what it would do\n  toolroll open [--web]     open this computer's Toolroll again, signed in\n  toolroll welcome          the three steps to a first result (--json: the model)\n  toolroll password set     add a password (typed twice, at your terminal)\n  toolroll scan [path...]   report what is in flight (also bare `toolroll` outside a repository)\n  toolroll [path...]        the same report for the paths given\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: checks, your approval, deploy, merge, tag, publish\n                                   (rerun the same command to continue; --help)\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 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 integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll lead token       mint your lead agent's sign-in: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n\nTasks \u2014 `toolroll task` prints the whole list,\nand any task command + --help prints it too\n  toolroll approver add <name>\n                               add a person who can approve work\n  toolroll task add <title> queue work\n  toolroll task show <id>   one task: its plan, builds and what it waits for\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll task accept <id> --finish\n                               accept the result you read (--despite \"<why>\": accept it with a reason, without finishing)\n  toolroll task send-back <id> --feedback \"<what to change>\"\n                               send the result back for changes\n  toolroll task retry <id>  build it again\n  toolroll task ready <id>  can I merge it? each check, and what clears a blocker\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 flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n\nMachine and agent commands (the builder, agent tools, recovery):\n  toolroll internals        lists them; each keeps working as before\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 commands people rarely type: the builder's own loop, the machine contract and recovery. They all keep working;
+ * `toolroll internals` (or `toolroll internals --help`) lists them so top-level help stays about the work. */
+export declare const INTERNALS_HELP = "toolroll internals \u2014 machine and agent commands\n\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll health           recent server latency, write waits and live streams\n  toolroll ready            what could be started 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 scope <id> --goal <text>\n                               write a task's plan from the command line\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 serve --repo <path>  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   run only the builder\n  toolroll doctor           check that Toolroll's service holds no key a build could read\n  toolroll reconcile        recover what the last stretch left behind\n  toolroll release --recover-deploy [--stage <dir>] [--yes]\n  toolroll release --release-gate <id> [--yes]\n                               the release tool's recovery steps (toolroll release <branch> runs them for you)";

package/dist/cli-help.js

@@ -3,7 +3,7 @@
  * 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
+export const HELP = `toolroll — hand coding work to agents, walk away, come back to pull requests
 
 Usage
   toolroll                  at your terminal: start Toolroll here (or attach) and open it in the terminal
@@ -26,52 +26,41 @@ Usage
   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 release <branch> release Toolroll itself: checks, your approval, deploy, merge, tag, publish
+                                   (rerun the same command to continue; --help)
   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 token       mint your lead agent's sign-in: 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
+Tasks — \`toolroll task\` prints the whole list,
+and any task 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
+                               add a person who can approve work
   toolroll task add <title> queue work
-  toolroll task scope <id> --goal <text>
-                               state what success is; approval binds to it
+  toolroll task show <id>   one task: its plan, builds and what it waits for
   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 task accept <id> --finish
+                               accept the result you read (--despite "<why>": accept it with a reason, without finishing)
+  toolroll task send-back <id> --feedback "<what to change>"
+                               send the result back for changes
+  toolroll task retry <id>  build it again
+  toolroll task ready <id>  can I merge it? each check, and what clears a blocker
   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 doctor           check that Toolroll's service holds no key a build could read
-  toolroll reconcile        recover what the last stretch left behind
+  toolroll flows list | show <id> | create | edit | trigger | script | card | archive
+                               set up and inspect flows (writes preview until --yes)
+
+Machine and agent commands (the builder, agent tools, recovery):
+  toolroll internals        lists them; each keeps working as before
 
 With nothing connected it reports everything it can find below the working
 directory. Once you connect repositories it reports those instead.
@@ -97,3 +86,31 @@ 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 commands people rarely type: the builder's own loop, the machine contract and recovery. They all keep working;
+ * `toolroll internals` (or `toolroll internals --help`) lists them so top-level help stays about the work. */
+export const INTERNALS_HELP = `toolroll internals — machine and agent commands
+
+  toolroll contract         the machine contract: envelope version + capabilities
+                                   (--commands dumps the declared command guide)
+  toolroll skills list      the guides this exact binary serves
+  toolroll skills get <name>  print one guide (version-matched, never stale)
+  toolroll health           recent server latency, write waits and live streams
+  toolroll ready            what could be started 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 scope <id> --goal <text>
+                               write a task's plan from the command line
+  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 serve --repo <path>  run only the console
+                               (--editor vscode with --runner: file links
+                               open in VS Code on the device you browse from)
+  toolroll watch / daemon install   run only the builder
+  toolroll doctor           check that Toolroll's service holds no key a build could read
+  toolroll reconcile        recover what the last stretch left behind
+  toolroll release --recover-deploy [--stage <dir>] [--yes]
+  toolroll release --release-gate <id> [--yes]
+                               the release tool's recovery steps (toolroll release <branch> runs them for you)`;

package/dist/cli.js

@@ -37,7 +37,8 @@ import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } fr
 import { openStore, openStoreReadOnly, databasePath } from "./store.js";
 import { renderReport, renderPulls, renderGraph } from "./render.js";
 import { DEFAULT_MAX_DEPTH } from "./scan.js";
-import { HELP } from "./cli-help.js";
+import { HELP, INTERNALS_HELP } from "./cli-help.js";
+import { withTaskAlias } from "./task-aliases.js";
 import { quickAnswer } from "./cli-fast.js";
 import { BIN_NAME, chooseTarget, planLink, applyLink, planUnlink, applyUnlink, } from "./link.js";
 const USAGE_EXIT = 2;
@@ -113,6 +114,8 @@ export const OPERATE_COMMANDS = new Set([
     "evals",
     // Only `lead token` reaches here; the central service's lead verbs answer first.
     "lead",
+    // Only `release approve` reaches here: every other `release` form is release-cli.ts, routed before this set.
+    "release",
     "onboard",
     "status",
     "ready",
@@ -135,7 +138,9 @@ export const OPERATE_COMMANDS = new Set([
     "review",
     "assignment",
     "knowledge",
+    "map",
     "memory",
+    "flaky",
     "models",
     "claim",
     "heartbeat",
@@ -303,6 +308,8 @@ function routinesMoved(argv, write) {
     return 0;
 }
 async function dispatch(argv, write, mainOptions) {
+    // People's names for task commands (task send-back, retry, recheck) are the commands they name, before anything else.
+    argv = withTaskAlias(argv);
     // v115: routines became scheduled flows. Every old `routine …` invocation answers with one line pointing there —
     // hidden from help and the contract, before anything remote or local opens, changing nothing.
     if (argv[0] === "routine")
@@ -319,6 +326,11 @@ async function dispatch(argv, write, mainOptions) {
     // Command families below load when their command runs, so one command never pays for the others.
     if (argv[0] === 'health')
         return (await import("./health-cli.js")).runHealthCommand(argv.slice(1), write, mainOptions.connect ?? mainOptions.remote);
+    // The machine and agent commands, listed apart so top-level help stays about the work (each still runs by name).
+    if (argv[0] === 'internals' && argv.slice(1).every(arg => arg === '--help' || arg === '-h')) {
+        write(INTERNALS_HELP);
+        return 0;
+    }
     // This computer's own service, read here and never on a central server.
     if (argv[0] === 'doctor')
         return (await import("./doctor.js")).runDoctorCommand(argv.slice(1), write);
@@ -344,6 +356,9 @@ async function dispatch(argv, write, mainOptions) {
     }
     if (first === "update")
         return (await import("./toolroll-update-cli.js")).runUpdateCommand(rest, write, mainOptions.update);
+    // `toolroll release approve`: a person's approval, with the operate commands' own credential prompt and context.
+    if (first === "release" && rest[0] === "approve")
+        return runOperate("release", rest, write, mainOptions.operate ?? {});
     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 });

package/dist/code-extract.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The static read of one TS/JS file and the module resolution over a set of paths held in memory: nothing here touches
+ * the filesystem, a repository or a checker. Repository context (repository-context.ts) reads a checkout through it; the
+ * code map's parser child (code-map-main.ts) reads blobs through it. The file name decides the parse mode.
+ */
+import type ts from 'typescript-parser';
+export type Compiler = typeof ts;
+export type EdgeKind = 'imports' | 're-exports' | 'dynamic-import';
+export type DeclarationKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'method' | 'variable' | 'default';
+export type Declaration = {
+    name: string;
+    kind: Exclude<DeclarationKind, 'default'>;
+    line: number;
+    endLine: number;
+};
+export type ExportedName = {
+    name: string;
+    kind: DeclarationKind;
+    line: number;
+};
+export type Specifier = {
+    specifier: string;
+    kind: EdgeKind;
+    line: number;
+};
+export type Extracted = {
+    declarations: Declaration[];
+    exports: ExportedName[];
+    specifiers: Specifier[];
+    parseFailed: boolean;
+};
+/** Declarations, the names the file exports (under the name they are exported as) and the module specifiers it names. `require` isn't counted: it may
+ * be shadowed, and a guessed call isn't a proven relationship. */
+export declare function extractFile(compiler: Compiler, fileName: string, text: string): Extracted;
+/** The compiler options a project's tsconfig text gives, read as JSONC and converted, non-string options included.
+ * `extends` isn't followed. */
+export declare function compilerOptionsOf(compiler: Compiler, configPath: string, text: string | undefined, root: string): {
+    options: ts.CompilerOptions;
+    problem: 'extends' | 'unreadable' | null;
+};
+/** Resolve a specifier to one of `paths` (absolute, in memory); null when it names nothing there. */
+export declare function resolveAll(compiler: Compiler, root: string, paths: ReadonlyMap<string, {
+    text?: string;
+}>, directories: ReadonlySet<string>, options: ts.CompilerOptions, normal: (file: string) => string): (specifier: string, fromFile: string) => string | null;

package/dist/code-extract.js

@@ -0,0 +1,88 @@
+const declarationKind = (compiler, node) => compiler.isFunctionDeclaration(node) ? 'function' : compiler.isClassDeclaration(node) ? 'class' : compiler.isInterfaceDeclaration(node) ? 'interface'
+    : compiler.isTypeAliasDeclaration(node) ? 'type' : compiler.isEnumDeclaration(node) ? 'enum' : compiler.isMethodDeclaration(node) ? 'method'
+        : compiler.isVariableDeclaration(node) ? 'variable' : null;
+function exportedAtTop(compiler, node) {
+    const statement = compiler.isVariableDeclaration(node) ? node.parent?.parent : node;
+    if (!statement || !compiler.isSourceFile(statement.parent))
+        return false;
+    return (compiler.canHaveModifiers(statement) ? compiler.getModifiers(statement) : undefined)?.some(one => one.kind === compiler.SyntaxKind.ExportKeyword) ?? false;
+}
+/** Declarations, the names the file exports (under the name they are exported as) and the module specifiers it names. `require` isn't counted: it may
+ * be shadowed, and a guessed call isn't a proven relationship. */
+export function extractFile(compiler, fileName, text) {
+    const tree = compiler.createSourceFile(fileName, text, compiler.ScriptTarget.Latest, true);
+    const parseFailed = !!tree.parseDiagnostics?.length;
+    const line = (pos) => tree.getLineAndCharacterOfPosition(Math.min(pos, text.length)).line + 1;
+    const declarations = [], specifiers = [], exports = [];
+    const named = [];
+    const visit = (node) => {
+        const kind = declarationKind(compiler, node);
+        if (kind !== null) {
+            const name = node.name;
+            const at = line(node.getStart(tree));
+            const out = exportedAtTop(compiler, node);
+            const isDefault = out && (compiler.canHaveModifiers(node) ? compiler.getModifiers(node) : undefined)?.some(one => one.kind === compiler.SyntaxKind.DefaultKeyword);
+            if (name && compiler.isIdentifier(name)) {
+                declarations.push({ name: name.text, kind, line: at, endLine: line(node.end) });
+                if (out)
+                    exports.push({ name: name.text, kind, line: at });
+            }
+            else if (!name && isDefault)
+                exports.push({ name: 'default', kind: 'default', line: at });
+        }
+        if (compiler.isExportAssignment(node) && !node.isExportEquals) {
+            if (compiler.isIdentifier(node.expression))
+                named.push({ local: node.expression.text, as: 'default' });
+            else
+                exports.push({ name: 'default', kind: 'default', line: line(node.getStart(tree)) });
+        }
+        if (compiler.isImportDeclaration(node) && compiler.isStringLiteral(node.moduleSpecifier))
+            specifiers.push({ specifier: node.moduleSpecifier.text, kind: 'imports', line: line(node.getStart(tree)) });
+        if (compiler.isExportDeclaration(node)) {
+            if (node.moduleSpecifier && compiler.isStringLiteral(node.moduleSpecifier))
+                specifiers.push({ specifier: node.moduleSpecifier.text, kind: 're-exports', line: line(node.getStart(tree)) });
+            else if (!node.moduleSpecifier && node.exportClause && compiler.isNamedExports(node.exportClause)) {
+                for (const one of node.exportClause.elements)
+                    named.push({ local: (one.propertyName ?? one.name).text, as: one.name.text });
+            }
+        }
+        if (compiler.isCallExpression(node) && node.arguments.length === 1 && compiler.isStringLiteral(node.arguments[0]) && node.expression.kind === compiler.SyntaxKind.ImportKeyword) {
+            specifiers.push({ specifier: node.arguments[0].text, kind: 'dynamic-import', line: line(node.getStart(tree)) });
+        }
+        compiler.forEachChild(node, visit);
+    };
+    visit(tree);
+    // `export { a as b }` and `export default a`: the local declaration, under the name it is exported as.
+    for (const { local, as } of named) {
+        const found = declarations.find(one => one.name === local && one.kind !== 'method');
+        if (found !== undefined && !exports.some(one => one.name === as))
+            exports.push({ name: as, kind: as === 'default' ? 'default' : found.kind, line: found.line });
+    }
+    return { declarations, exports, specifiers, parseFailed };
+}
+/** The compiler options a project's tsconfig text gives, read as JSONC and converted, non-string options included.
+ * `extends` isn't followed. */
+export function compilerOptionsOf(compiler, configPath, text, root) {
+    const base = { module: compiler.ModuleKind.NodeNext, moduleResolution: compiler.ModuleResolutionKind.NodeNext, allowJs: true, resolveJsonModule: true };
+    if (text === undefined)
+        return { options: base, problem: null };
+    const parsed = compiler.parseConfigFileTextToJson(configPath, text);
+    if (parsed.error || !parsed.config?.compilerOptions)
+        return { options: base, problem: 'unreadable' };
+    const converted = compiler.convertCompilerOptionsFromJson(parsed.config.compilerOptions, root);
+    return { options: { ...base, ...converted.options }, problem: parsed.config.extends ? 'extends' : null };
+}
+/** Resolve a specifier to one of `paths` (absolute, in memory); null when it names nothing there. */
+export function resolveAll(compiler, root, paths, directories, options, normal) {
+    const host = {
+        fileExists: file => paths.has(normal(file)),
+        readFile: file => paths.get(normal(file))?.text,
+        directoryExists: dir => directories.has(normal(dir)),
+        getCurrentDirectory: () => root,
+        realpath: file => normal(file),
+    };
+    return (specifier, fromFile) => {
+        const resolved = compiler.resolveModuleName(specifier, fromFile, options, host).resolvedModule?.resolvedFileName;
+        return resolved && paths.has(normal(resolved)) ? normal(resolved) : null;
+    };
+}