toolroll 0.9.93 → 0.9.95

package/dist/checkout-cleanup.d.ts

@@ -1,11 +1,13 @@
-import { type CheckoutCleanup } from "./storage.js";
-import type { Store, WorktreeRow } from "./store.js";
+import { type CheckoutCleanup, type CheckoutIdle } from "./storage.js";
+import { type Store, type WorktreeRow } from "./store.js";
 import { type WorktreePool } from "./worktree.js";
 /** A release candidate's checkout holds the build a deploy installs: the newest complete one waits at most a week for it. */
 export declare const CANDIDATE_KEEP_MS: number;
 /** The worker's pass removes at most this many; a clean-up by hand has no cap. */
 export declare const AUTO_MAX = 20;
-export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task";
+export type KeepWhy = "in use" | "task not finished" | "waiting for review" | "release candidate" | "has changes" | "has commits" | "not on its branch" | "unreadable" | "git refused" | "not due yet" | "cleanup is off" | "no task"
+/** A clean-up by hand leaves it; the next sweep takes it. */
+ | "idle";
 export type CheckoutItem = {
     path: string;
     repo: string;
@@ -17,10 +19,13 @@ export type CheckoutItem = {
     why: KeepWhy | null;
     /** With "not due yet" or "release candidate": when it may go. */
     dueAt?: string;
+    /** Past the idle limit: when its task last saw any activity. */
+    idleSince?: string;
 };
 export type CheckoutPlan = {
     at: string;
     cleanup: CheckoutCleanup;
+    idle: CheckoutIdle;
     manual: boolean;
     go: CheckoutItem[];
     stay: CheckoutItem[];
@@ -30,6 +35,9 @@ export type CheckoutPlan = {
     freeBytes: number;
     waitingReview: number;
     withChanges: number;
+    /** What the next sweep's idle cleanup takes. */
+    idleCount: number;
+    idleBytes: number;
 };
 type Status = {
     keep: KeepWhy | null;
@@ -64,6 +72,21 @@ export declare function finishedCheckouts(store: Store, now: Date, repo?: string
     taskId: string | null;
     finishedAt: string;
 }[];
+/** The newest activity of a task's whole family, and whether something rules idle cleanup out for it. */
+type IdleFact = {
+    activeAt: string;
+    blocked: boolean;
+};
+export type IdleFacts = {
+    byRef: Map<number, IdleFact>;
+    byBranch: Map<string, IdleFact>;
+};
+/**
+ * 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 declare function idleFacts(store: Store): IdleFacts;
 /** 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;
 /**
@@ -83,11 +106,15 @@ export type CleanResult = {
         why: KeepWhy;
     }[];
     freed: number;
+    /** The worker's pass stopped at AUTO_MAX: more may be due, and the sweep comes back an hour later. */
+    more?: boolean;
 };
 /**
  * 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 declare function cleanCheckouts(store: Store, pool: WorktreePool, now: () => Date, options: {
     manual: boolean;
@@ -95,6 +122,10 @@ export declare function cleanCheckouts(store: Store, pool: WorktreePool, now: ()
     repo?: string;
     only?: ReadonlySet<string>;
     spare?: (path: string) => boolean;
+    /** The storage sweep's child only: idle checkouts go too. `occupied` asks the OS whether any process works in a folder. */
+    idle?: {
+        occupied: (path: string) => boolean;
+    };
 }): Promise<CleanResult>;
 export type SlimResult = {
     slimmed: {
@@ -122,5 +153,5 @@ export declare function discardCheckout(store: Store, pool: WorktreePool, path:
     message: string;
 }>;
 /** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
-export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt">): string;
+export declare function whyWords(item: Pick<CheckoutItem, "why" | "dueAt" | "idleSince">): string;
 export {};

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/claim.d.ts

@@ -214,6 +214,8 @@ export declare function acquireIfReady(store: Store, taskRef: number, runner: st
     provider?: string;
     /** The model this dispatch would run — the quota scope. */
     model?: string;
+    /** A fallback entry's pinned auth mode: its quota is that credential's, never the base's. */
+    authMode?: "subscription" | "api-key";
     /** What this dispatch is FOR. Re-proved inside the transaction — the
      * caller's survey is not trusted (Codex planning review, finding 2). */
     dispatchRole?: "builder" | "planner" | "scout";
@@ -348,6 +350,10 @@ export type FailureDisposition = {
     ok: true;
     disposition: "auth-expired";
     provider: string;
+} | {
+    ok: true;
+    disposition: "fallback";
+    provider: string;
 } | {
     ok: false;
     reason: "fenced" | "unknown" | "stopped";

package/dist/claim.js

@@ -38,6 +38,7 @@ import { sealUnchangedPlanUnderMode } from "./plan-auto.js";
 import { routeFromJson } from "./phase-routing.js";
 import { contractChangesOf, decodePlannerSource, encodePlannerSource, canonicalContractJson, PLANNER_SOURCE_LIMITS, describeContractChanges, encodePlanContractRecord, plannerContractOf, plannerSourceDigest, } from "./planner-source.js";
 import { storeEvidence, readVerifiedArtifact, EVIDENCE_CAPS } from "./evidence.js";
+import { moveOnIfExhausted } from "./fallback.js";
 /** How stale a mirror's last complete sync may be before admission refuses. */
 export const SYNC_MAX_AGE_MS = 15 * 60_000;
 /**
@@ -298,7 +299,7 @@ export function acquireIfReady(store, taskRef, runner, options) {
         // Quota is keyed to the credential that actually exhausts: the RESOLVED
         // provider, never a fixed binary name — codex quota must not collide
         // with claude's, nor bypass it (Codex provider review, high finding 5).
-        const quota = store.quotaState(runner, options.provider ?? "claude", scope, options.now);
+        const quota = store.quotaState(runner, options.provider ?? "claude", scope, options.now, options.authMode ?? "subscription");
         if (quota !== null && quota.state === "exhausted") {
             return {
                 ok: false,
@@ -349,7 +350,7 @@ export function acquireIfReady(store, taskRef, runner, options) {
         // exhausted with no probe in flight (finding 3). Same transaction, so
         // consume-with-claim is all-or-nothing.
         if (taken.ok && quota !== null) {
-            store.consumeHalfOpen(runner, options.provider ?? "claude", scope, options.now);
+            store.consumeHalfOpen(runner, options.provider ?? "claude", scope, options.now, options.authMode ?? "subscription");
         }
         return taken;
     });
@@ -880,6 +881,16 @@ function sealFailure(store, leaseId, args) {
     if (failureClass !== "commit-failure" && run.terminalClass === "auth-expired") {
         return { ok: true, ...sealAuthExpired(store, run, taskId, now) };
     }
+    // Out of plan on an approved chain: the walk moves on, no strike, and the next agent runs through the ordinary claim.
+    // Anything else about this ending (fallback.ts says what closed the walk) stays the ordinary road below.
+    // Only the agent's own exit moves: a lease, branch or HEAD law that failed, or a commit that failed, is that ending.
+    if (failureClass === "unknown") {
+        const moved = moveOnIfExhausted(store, runId, taskId, now);
+        if (moved !== null) {
+            store.finishRun(runId, { outcome: "failed", reason: "usage-exhausted", now });
+            return { ok: true, disposition: "fallback", provider: moved.to.provider };
+        }
+    }
     store.finishRun(runId, { outcome: "failed", reason: failureClass, now });
     if (failureClass === "commit-failure") {
         // The work exists and is uncommitted; nothing times its way out of

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 card <source>    the data chat shows as a card: tasks, results, flows, spend,\n                               projects, builders, mode, integrations, providers, findings, handover\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,43 @@ 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 card <source>    the data chat shows as a card: tasks, results, flows, spend,
+                               projects, builders, mode, integrations, providers, findings, handover
+  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 +88,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;
@@ -137,7 +138,13 @@ export const OPERATE_COMMANDS = new Set([
     "review",
     "assignment",
     "knowledge",
+    "map",
     "memory",
+    "flaky",
+    "card",
+    // Follow-through (follow-through-cli.ts): findings and saved provider failures.
+    "finding",
+    "captures",
     "models",
     "claim",
     "heartbeat",
@@ -305,6 +312,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")
@@ -321,6 +330,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);