toolroll 0.9.94 → 0.9.96

package/dist/check-repair.js

@@ -0,0 +1,240 @@
+/**
+ * A failed check gets one owner and a bounded repair (docs/plans/fleet-follow-through.md, part 2).
+ *
+ * One `check_repair` row per task family, revision and failure: the UNIQUE key is what keeps the same failure on the
+ * same revision from starting a second repair, however many times it is seen. The row's owner is the task that built
+ * the revision. The repair itself is the existing ledger's (`maybeTriggerRepair`, `repair_chain`), so it is an ordinary
+ * revision: the source scope verbatim, the ordinary rails, the ordinary approval.
+ *
+ * Who says yes doesn't change here. A mode a person signed with automatic repair and a limit drafts and approves through
+ * the seal that already exists. Without that signature nothing is drafted and nothing spends: the row waits for a person,
+ * and a person's repair is a draft that takes the normal plan approval. A model never moves a row past that.
+ *
+ * Failure text never reaches this file's decisions: the failure key comes from the sealed receipt and the log's failing
+ * file names, and it only ever matches rows, it grants nothing.
+ */
+import { createHash } from "node:crypto";
+import { maybeTriggerRepair } from "./dispose.js";
+import { readingFleet } from "./fleet-schema.js";
+import { familyRootOf, settleFindingAnswers } from "./findings.js";
+import { failingTestsOf } from "./gate-failure.js";
+import { CHECK_REPAIR_LIMIT, modeTermsFromJson } from "./modes.js";
+import { releaseCheckScope } from "./scope.js";
+import { readVerificationView } from "./contracts/verification-view.js";
+import { failedVerificationEvidence } from "./verification-evidence.js";
+import { saveEvidencePair } from "./evidence-pair.js";
+const repairOf = (row) => ({
+    id: Number(row["id"]), familyRoot: String(row["family_root"]), ownerTask: String(row["owner_task"]), repo: String(row["repo"]), revision: String(row["revision"]),
+    sourceRun: Number(row["source_run"]), state: String(row["state"]), why: String(row["why"]), repairTask: row["repair_task"] === null ? null : String(row["repair_task"]),
+    attempt: row["attempt"] === null ? null : Number(row["attempt"]), createdAt: String(row["created_at"]), updatedAt: String(row["updated_at"]),
+});
+export function checkRepairsOfTask(store, taskId) {
+    return readingFleet(() => store.handle.prepare("SELECT * FROM check_repair WHERE family_root = ? ORDER BY id DESC").all(familyRootOf(store, taskId)).map(repairOf), []);
+}
+export function checkRepairOfRun(store, runId) {
+    return readingFleet(() => {
+        const row = store.handle.prepare("SELECT * FROM check_repair WHERE source_run = ? ORDER BY id DESC LIMIT 1").get(runId);
+        return row === undefined ? null : repairOf(row);
+    }, null);
+}
+/** What makes this failure this failure: the command, how it ended, and which files failed. Never the log's own bytes,
+ * which differ on every run. */
+export function failureKeyOf(receipt, log) {
+    const view = readVerificationView(receipt);
+    const facts = view.ok ? view.value : null;
+    const failing = failingTestsOf(log)?.map(one => one.file).sort() ?? [];
+    const result = facts === null ? null : facts.result;
+    return createHash("sha256").update(JSON.stringify(["toolroll:check-failure", facts?.command.digest ?? null, result?.exitCode ?? null, result?.failure ?? null, failing])).digest("hex").slice(0, 32);
+}
+/** Parked work stays quiet: a person already has this task, or it is stopped. */
+function parkedWhy(store, taskRef, runId, now) {
+    if (store.activeHolds(taskRef, now).length > 0)
+        return "This task is on hold.";
+    if (store.applicableStopFor(runId) !== null)
+        return "This attempt was stopped.";
+    if (store.decisionsForTask(taskRef).some(one => one.state === "open" || one.state === "expired"))
+        return "This task is waiting for an answer.";
+    if (store.pendingSteerCount(taskRef) > 0)
+        return "This task has a note waiting for its next attempt.";
+    return null;
+}
+/** Why an approved plan can't cover a repair of this result, or null when it can. */
+function notCovered(store, taskId, runId) {
+    const scope = store.getScope(taskId);
+    if (scope === null)
+        return "This task has no approved plan to repair under.";
+    if (scope.releaseTerms != null || releaseCheckScope(scope) || (scope.candidate ?? null) !== null)
+        return "Its plan only covers checking this commit. A fix needs a task of its own.";
+    if (store.lookupRef(taskId)?.deliverable === "report")
+        return "This task delivers a report: there's no code to repair.";
+    const publication = store.publicationForRun(runId);
+    if (publication !== null && !(publication.state === "intended" && publication.attempts === 0))
+        return "This result is published. Fix it through its pull request.";
+    return null;
+}
+/** The attempts this family's repair chain has spent. */
+const attemptsUsed = (store, taskId) => store.repairLineageOf(taskId).attempts.reduce((highest, row) => Math.max(highest, row.attempt), 0);
+function move(store, id, state, why, now, draft) {
+    store.handle.prepare("UPDATE check_repair SET state = ?, why = ?, updated_at = ?, repair_task = COALESCE(?, repair_task), attempt = COALESCE(?, attempt) WHERE id = ?")
+        .run(state, why, now.toISOString(), draft?.task ?? null, draft?.attempt ?? null, id);
+    store.bumpWake();
+}
+function askPerson(store, row, subject, body, now) {
+    store.enqueueNotification({ source: { run: row.sourceRun }, dedupeKey: `check-repair:${row.id}:${subject}`, kind: "check-repair", pushClass: "attention", subject, body, link: `/t/${encodeURIComponent(row.ownerTask)}` }, now);
+}
+/** Take the row one step, from where it stands now. A person's yes is never decided here: `person` only says a person asked for the draft. */
+function advance(store, repo, root, row, now, person) {
+    const run = store.getRun(row.sourceRun);
+    const ref = run === null ? null : store.refById(run.taskRef);
+    const verdict = store.proofVerdictFor(row.sourceRun);
+    if (run === null || ref === null || verdict === null) {
+        move(store, row.id, "with-person", "The failed attempt's records can't be read.", now);
+        return null;
+    }
+    const parked = person ? null : parkedWhy(store, run.taskRef, run.id, now);
+    if (parked !== null) {
+        move(store, row.id, "parked", parked, now);
+        return null;
+    }
+    const uncovered = notCovered(store, row.ownerTask, run.id);
+    if (uncovered !== null) {
+        move(store, row.id, "with-person", uncovered, now);
+        // A release's check speaks for itself (release-adapters.ts): one voice for one failure.
+        if (store.getScope(row.ownerTask)?.releaseTerms == null)
+            askPerson(store, row, "A failed check needs you", `The check failed on ${row.revision.slice(0, 7)}, and a repair can't run under this plan. ${uncovered}`, now);
+        return null;
+    }
+    const mode = store.activeMode(repo, now);
+    const terms = mode === null ? null : modeTermsFromJson(mode.termsJson);
+    const auto = terms?.repairAuto === true;
+    const limit = auto ? terms.repairMaxAttempts : CHECK_REPAIR_LIMIT;
+    const used = attemptsUsed(store, row.ownerTask);
+    if (used >= limit) {
+        const why = `${used} repair${used === 1 ? "" : "s"} tried, which is the limit. It's yours to decide.`;
+        move(store, row.id, "with-person", why, now);
+        askPerson(store, row, "Repairs ran out on a failed check", `The check still fails on ${row.revision.slice(0, 7)} after ${used} repair${used === 1 ? "" : "s"}. The failed check's log is on the result.`, now);
+        return null;
+    }
+    if (!auto && !person) {
+        move(store, row.id, "waiting", "Waiting for a person to start a repair.", now);
+        store.enqueueNotification({ source: { run: run.id }, dedupeKey: `check-repair:${row.id}:waiting`, kind: "check-repair", subject: "A check failed", body: `The check failed on ${row.revision.slice(0, 7)}. Start a repair on the task page.`, link: `/t/${encodeURIComponent(row.ownerTask)}` }, now);
+        return null;
+    }
+    const trigger = maybeTriggerRepair(store, repo, root, run.id, verdict.verdict, now, "verification", !person);
+    if (trigger.kind === "drafted") {
+        move(store, row.id, "repairing", trigger.approved ? `Repair ${trigger.draftTaskId} is approved under the signed mode and will build next.` : `Repair ${trigger.draftTaskId} is drafted and waits for its plan to be approved.`, now, { task: trigger.draftTaskId, attempt: trigger.attempt });
+        saveEvidencePair(store, root, { taskId: row.ownerTask, runId: run.id, by: "Toolroll" }, now);
+    }
+    else if (trigger.kind === "rerun") {
+        move(store, row.id, "rerunning", "The failure looks unrelated to this change, so the check runs once more on the same commit.", now);
+    }
+    else {
+        const why = trigger.kind === "stopped" ? stopWords(trigger.reason) : "A repair can't start from this result. It's yours to decide.";
+        move(store, row.id, "with-person", why, now);
+        if (trigger.kind === "stopped")
+            askPerson(store, row, "A repair stopped", why, now);
+    }
+    return trigger;
+}
+const stopWords = (reason) => ({
+    "repair-attempts-spent": "The repairs allowed were used up.",
+    "repair-no-progress": "Two repairs in a row didn't reduce what's failing, so Toolroll stopped.",
+    "repair-refused-integrity": "The result disagrees with its approved terms, so a person reads it first.",
+}[reason]);
+/**
+ * Route one failed check. Runs at disposition. A failure already on record for this family and revision changes nothing,
+ * unless it was the one rerun of an unrelated failure, which now goes to a person through the ledger's own rerun stop.
+ */
+export function routeFailedCheck(store, repo, root, runId, now) {
+    const run = store.getRun(runId);
+    if (run === null || run.role !== "builder" || run.finishedAt === null || !run.headRevision)
+        return null;
+    const taskId = store.externalIdFor(run.taskRef);
+    if (taskId === null)
+        return null;
+    const failure = failedVerificationEvidence(store, root, runId);
+    if (failure.kind !== "failed")
+        return null;
+    const familyRoot = familyRootOf(store, taskId);
+    const key = failureKeyOf(failure.receipt, failure.log);
+    return store.transact(() => {
+        const earlier = store.handle.prepare("SELECT * FROM check_repair WHERE family_root = ? AND revision = ? AND failure_key = ?").get(familyRoot, run.headRevision, key);
+        if (earlier !== undefined) {
+            const row = repairOf(earlier);
+            if (row.state === "rerunning") {
+                store.handle.prepare("UPDATE check_repair SET source_run = ? WHERE id = ?").run(runId, row.id);
+                maybeTriggerRepair(store, repo, root, runId, store.proofVerdictFor(runId)?.verdict ?? "refuted", now, "verification", true);
+                move(store, row.id, "with-person", "It failed again on the same commit. It's yours to decide.", now);
+            }
+            return repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id));
+        }
+        // A newer failure replaces an older one nobody took up.
+        store.handle.prepare("UPDATE check_repair SET state = 'closed', why = 'A newer attempt replaced this result.', updated_at = ? WHERE family_root = ? AND state IN ('waiting', 'parked', 'rerunning')").run(now.toISOString(), familyRoot);
+        const made = store.handle.prepare(`INSERT INTO check_repair (family_root, owner_task, repo, revision, failure_key, source_run, state, why, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, 'waiting', '', ?, ?)`)
+            .run(familyRoot, taskId, repo, run.headRevision, key, runId, now.toISOString(), now.toISOString());
+        const row = repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(Number(made.lastInsertRowid)));
+        advance(store, repo, root, row, now, false);
+        return repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id));
+    });
+}
+/** A person asks for the repair. The draft takes the normal plan approval: this is not that approval. */
+export function startCheckRepair(store, root, runId, now) {
+    const row = checkRepairOfRun(store, runId);
+    if (row === null)
+        return { ok: false, reason: "unknown", message: `Run ${runId} has no failed check to repair.` };
+    if (row.state !== "waiting" && row.state !== "parked" && row.state !== "with-person")
+        return { ok: false, reason: "refused", message: row.repairTask !== null ? `Repair ${row.repairTask} already exists for this failure.` : row.why };
+    return store.transact(() => {
+        const trigger = advance(store, row.repo, root, row, now, true);
+        if (trigger?.kind === "drafted")
+            return { ok: true, draft: trigger.draftTaskId, attempt: trigger.attempt, approved: trigger.approved };
+        return { ok: false, reason: "refused", message: repairOf(store.handle.prepare("SELECT * FROM check_repair WHERE id = ?").get(row.id)).why };
+    });
+}
+/** A passing result in the family ends its failed-check rows. Rows the person already holds end too: the code passes now. */
+export function settleCheckRepairs(store, taskId, verdict, now) {
+    if (verdict !== "verified" && verdict !== "attested")
+        return;
+    readingFleet(() => store.handle.prepare("UPDATE check_repair SET state = 'fixed', why = 'A later result passed its check.', updated_at = ? WHERE family_root = ? AND state NOT IN ('fixed', 'closed')").run(now.toISOString(), familyRootOf(store, taskId)), null);
+}
+/** Each sweep: a parked failure whose task is free again takes its next step, unless a newer attempt replaced it. */
+export function resumeParkedRepairs(store, root, now) {
+    return readingFleet(() => {
+        let moved = 0;
+        for (const raw of store.handle.prepare("SELECT * FROM check_repair WHERE state = 'parked'").all()) {
+            const row = repairOf(raw);
+            const run = store.getRun(row.sourceRun);
+            if (run === null)
+                continue;
+            if (parkedWhy(store, run.taskRef, run.id, now) !== null)
+                continue;
+            store.transact(() => {
+                if (store.lastBuilderRun(run.taskRef)?.id !== run.id)
+                    move(store, row.id, "closed", "A newer attempt replaced this result.", now);
+                else
+                    advance(store, row.repo, root, row, now, false);
+            });
+            moved++;
+        }
+        return moved;
+    }, 0);
+}
+/** A build was accepted as finished: count what it answered, then route its check if it failed. Bookkeeping that never
+ * costs the build its result: a problem here leaves the finding open and the failed check on the result. */
+export function followBuiltRun(store, repo, root, runId, worktree, now) {
+    try {
+        settleFindingAnswers(store, runId, worktree, now);
+    }
+    catch { /* the answers stay saved */ }
+    try {
+        store.transact(() => store.savepoint(() => routeFailedCheck(store, repo, root, runId, now)));
+    }
+    catch { /* the failure stays on the result */ }
+}
+/** How a failed check stands, for a person, in one line. */
+export function checkRepairWords(row) {
+    const head = `Check failed on ${row.revision.slice(0, 7)} (build #${row.sourceRun})`;
+    if (row.state === "with-person")
+        return `${head}, needs you. ${row.why}`;
+    return row.state === "parked" ? `${head}. Paused: ${row.why}` : `${head}. ${row.why}`;
+}

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

@@ -56,6 +56,8 @@ and any task command + --help prints it too
   toolroll chat --as <you> --token <t>
                                talk to your lead: one conversation across every
                                project; it proposes, you confirm (--say "…" for one turn)
+  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)
 

package/dist/cli.js

@@ -141,6 +141,10 @@ export const OPERATE_COMMANDS = new Set([
     "map",
     "memory",
     "flaky",
+    "card",
+    // Follow-through (follow-through-cli.ts): findings and saved provider failures.
+    "finding",
+    "captures",
     "models",
     "claim",
     "heartbeat",

package/dist/coding-provider.d.ts

@@ -85,4 +85,4 @@ export declare function createCodexCodingProvider(options?: {
 export declare function codingSessionPermissions(store: Pick<Store, "databaseFile" | "listWorktrees" | "projectSandbox">, worktreeRoot: string): (input: {
     repo: string;
     worktree: string;
-}) => CodingPermissions;
+}) => Promise<CodingPermissions>;

package/dist/coding-provider.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { prepareProtectedStorage, storageRefusalOf } from "./protected-storage.js";
 import { TextDecoder } from "node:util";
 import { homedir, hostname } from "node:os";
 import { readDenyPath } from "./project-sandbox.js";
@@ -441,20 +442,23 @@ export function createCodexCodingProvider(options = {}) {
 export function codingSessionPermissions(store, worktreeRoot) {
     return input => sessionPermissions(store, { ...input, worktreeRoot });
 }
-function sessionPermissions(store, input) {
+async function sessionPermissions(store, input) {
     const databaseFile = store.databaseFile();
     if (databaseFile === null || databaseFile === "" || databaseFile === ":memory:")
         return { problem: "The coding session has no state folder to fence, so it was not started." };
     try {
         const poolRoots = [join(dirname(databaseFile), "worktrees"), input.worktreeRoot, ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
         const binding = trustedWorktreeBinding(input.repo, input.worktree, poolRoots);
-        const boundary = taskBoundary({ worktree: input.worktree, provider: "codex", binding, policy: FENCE_POLICY_CURRENT });
+        // The storage check, awaited off this thread (protected-storage.ts).
+        const storage = await prepareProtectedStorage();
+        const boundary = taskBoundary({ worktree: input.worktree, provider: "codex", binding, policy: FENCE_POLICY_CURRENT, storage });
         // The project's read denies, read live (a session seals none; they only narrow).
         const readDeny = store.projectSandbox(input.repo).readDeny.map(one => readDenyPath(one, homedir()));
-        const launch = fenceFor("build", { databaseFile, worktree: input.worktree, boundary, binding, runFolders: runFolders(null), poolRoots, readDeny, policy: FENCE_POLICY_CURRENT });
+        const launch = fenceFor("build", { databaseFile, worktree: input.worktree, boundary, binding, runFolders: runFolders(null), poolRoots, readDeny, policy: FENCE_POLICY_CURRENT, storage });
         return { config: codexFenceConfig(launch.fence, false, launch.fenceGrants) };
     }
-    catch {
-        return { problem: "The session's worktree couldn't be bound to its project, so the session was not started." };
+    catch (error) {
+        // The storage check's own words survive: what didn't finish, and which program macOS may need to allow.
+        return { problem: storageRefusalOf(error)?.message ?? "The session's worktree couldn't be bound to its project, so the session was not started." };
     }
 }

package/dist/coding-workspace.d.ts

@@ -39,7 +39,7 @@ type Options = {
     permissions: (input: {
         repo: string;
         worktree: string;
-    }) => CodingPermissions;
+    }) => CodingPermissions | Promise<CodingPermissions>;
     provider?: () => CodingProvider;
     admissionPaused?: () => boolean;
     authorize?: (actor: CodingActor, repo: string) => boolean;

package/dist/coding-workspace.js

@@ -280,8 +280,8 @@ export class CodingWorkspace {
         return { id, type, text, status: string(item['status']) || null, ...(type === 'userMessage' && clientId ? { clientId } : {}) };
     }
     /** The thread's confinement, made right before each start or resume from the plane's own records. */
-    permissionsFor(repo, worktree) {
-        const made = this.options.permissions({ repo, worktree });
+    async permissionsFor(repo, worktree) {
+        const made = await this.options.permissions({ repo, worktree });
         if ('problem' in made)
             throw Error(made.problem);
         return made;
@@ -455,7 +455,7 @@ export class CodingWorkspace {
             this.authorize(actor, repo);
             this.admit();
             nativeStartupAttempted = true;
-            const result = object(await this.request('thread/start', { cwd: worktree, approvalPolicy: 'on-request', approvalsReviewer: 'user', ...this.permissionsFor(repo, worktree), ...(input.model ? { model: input.model } : {}), developerInstructions: CODING_INSTRUCTIONS + (context?.text ?? ''), persistExtendedHistory: true }));
+            const result = object(await this.request('thread/start', { cwd: worktree, approvalPolicy: 'on-request', approvalsReviewer: 'user', ...(await this.permissionsFor(repo, worktree)), ...(input.model ? { model: input.model } : {}), developerInstructions: CODING_INSTRUCTIONS + (context?.text ?? ''), persistExtendedHistory: true }));
             const thread = object(result['thread']), nativeThreadId = string(thread['id']);
             if (!nativeThreadId)
                 throw Error('The agent did not return a session identity.');
@@ -504,7 +504,7 @@ export class CodingWorkspace {
         this.authorize({ name: session.owner, generation: session.generation }, session.repo);
         if (session.context)
             verifyCodingContext(session.context, session.repo, session.base);
-        const result = object(await this.request('thread/resume', { threadId: session.nativeThreadId, cwd: session.worktree, approvalPolicy: 'on-request', approvalsReviewer: 'user', ...this.permissionsFor(session.repo, session.worktree), ...(session.model ? { model: session.model } : {}), developerInstructions: CODING_INSTRUCTIONS + (session.context?.text ?? ''), persistExtendedHistory: true }));
+        const result = object(await this.request('thread/resume', { threadId: session.nativeThreadId, cwd: session.worktree, approvalPolicy: 'on-request', approvalsReviewer: 'user', ...(await this.permissionsFor(session.repo, session.worktree)), ...(session.model ? { model: session.model } : {}), developerInstructions: CODING_INSTRUCTIONS + (session.context?.text ?? ''), persistExtendedHistory: true }));
         const thread = object(result['thread']);
         if (thread['id'] !== session.nativeThreadId)
             throw Error('The agent returned a different conversation. Continuity could not be verified.');

package/dist/contracts/chat-actions.d.ts

@@ -264,6 +264,73 @@ export declare const chatActionRequestSchemas: {
         repo: z.ZodString;
         on: z.ZodBoolean;
     }, z.core.$strict>;
+    readonly mode_revoke: z.ZodObject<{
+        repo: z.ZodString;
+    }, z.core.$strict>;
+    readonly provider_resume: z.ZodObject<{
+        provider: z.ZodString;
+    }, z.core.$strict>;
+    readonly worker_note: z.ZodObject<{
+        runner: z.ZodString;
+        note: z.ZodString;
+    }, z.core.$strict>;
+    readonly lead_identity: z.ZodObject<{
+        name: z.ZodString;
+        persona: z.ZodString;
+    }, z.core.$strict>;
+    readonly task_archive: z.ZodObject<{
+        task: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly task_restore: z.ZodObject<{
+        task: z.ZodString;
+    }, z.core.$strict>;
+    readonly flow_archive: z.ZodObject<{
+        flow: z.ZodInt;
+    }, z.core.$strict>;
+    readonly flow_unattended_off: z.ZodObject<{
+        flow: z.ZodInt;
+    }, z.core.$strict>;
+    readonly incident_resolve: z.ZodObject<{
+        incident: z.ZodInt;
+    }, z.core.$strict>;
+    readonly finding_send: z.ZodObject<{
+        task: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodInt>;
+        pointer: z.ZodOptional<z.ZodString>;
+        run: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly finding_resend: z.ZodObject<{
+        finding: z.ZodInt;
+    }, z.core.$strict>;
+    readonly task_reopen: z.ZodObject<{
+        task: z.ZodString;
+    }, z.core.$strict>;
+    readonly revision_accept: z.ZodObject<{
+        task: z.ZodString;
+        revision: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly revision_reject: z.ZodObject<{
+        task: z.ZodString;
+        revision: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
+    readonly flow_unattended: z.ZodObject<{
+        flow: z.ZodInt;
+        days: z.ZodInt;
+        budget: z.ZodOptional<z.ZodString>;
+        runs: z.ZodOptional<z.ZodString>;
+        include: z.ZodOptional<z.ZodArray<z.ZodInt>>;
+    }, z.core.$strict>;
+    readonly memory_decide: z.ZodObject<{
+        repo: z.ZodString;
+        proposal: z.ZodInt;
+        decision: z.ZodEnum<{
+            accept: "accept";
+            reject: "reject";
+        }>;
+    }, z.core.$strict>;
     readonly code_map_holdout_end: z.ZodObject<{
         repo: z.ZodString;
     }, z.core.$strict>;
@@ -306,6 +373,9 @@ export declare const sharedActionSchema: z.ZodObject<{
         code_map_switch: "code_map_switch";
         decision_record: "decision_record";
         decision_retire: "decision_retire";
+        finding_resend: "finding_resend";
+        finding_send: "finding_send";
+        flow_archive: "flow_archive";
         flow_browser: "flow_browser";
         flow_browser_off: "flow_browser_off";
         flow_card_add: "flow_card_add";
@@ -325,13 +395,22 @@ export declare const sharedActionSchema: z.ZodObject<{
         flow_trigger_pause: "flow_trigger_pause";
         flow_trigger_remove: "flow_trigger_remove";
         flow_trigger_resume: "flow_trigger_resume";
+        flow_unattended: "flow_unattended";
+        flow_unattended_off: "flow_unattended_off";
+        incident_resolve: "incident_resolve";
         kit_setup: "kit_setup";
         knowledge_instructions: "knowledge_instructions";
         knowledge_remove: "knowledge_remove";
         knowledge_restore: "knowledge_restore";
         knowledge_save: "knowledge_save";
         lead_about_you: "lead_about_you";
+        lead_identity: "lead_identity";
+        memory_decide: "memory_decide";
+        mode_revoke: "mode_revoke";
+        provider_resume: "provider_resume";
         result_accept: "result_accept";
+        revision_accept: "revision_accept";
+        revision_reject: "revision_reject";
         scope_approve: "scope_approve";
         skill_disable: "skill_disable";
         skill_enable: "skill_enable";
@@ -351,11 +430,15 @@ export declare const sharedActionSchema: z.ZodObject<{
         suggestion_not_now: "suggestion_not_now";
         sweep_cancel_rest: "sweep_cancel_rest";
         sweep_file: "sweep_file";
+        task_archive: "task_archive";
         task_cancel: "task_cancel";
+        task_reopen: "task_reopen";
+        task_restore: "task_restore";
         task_resume: "task_resume";
         tool_add: "tool_add";
         tool_remove: "tool_remove";
         trial_stop: "trial_stop";
+        worker_note: "worker_note";
     }>;
     request: z.ZodObject<{}, z.core.$catchall<z.ZodUnknown>>;
     repo: z.ZodString;

package/dist/contracts/chat-actions.js

@@ -86,6 +86,24 @@ export const chatActionRequestSchemas = {
     // Slice 3: stopping a trial (starting one stays in Settings → Models, behind a step-up).
     trial_stop: z.strictObject({ repo: words, trial: id }),
     code_map_switch: z.strictObject({ repo: words, on: z.boolean() }),
+    // Chat and console parity (docs/plans/toolroll-cards.md): each runs the console's own write.
+    mode_revoke: z.strictObject({ repo: words }),
+    provider_resume: z.strictObject({ provider: words }),
+    worker_note: z.strictObject({ runner: words, note: words }),
+    lead_identity: z.strictObject({ name: words, persona: words }),
+    task_archive: z.strictObject({ task: words, reason: words.optional() }),
+    task_restore: z.strictObject({ task: words }),
+    flow_archive: z.strictObject({ flow: id }),
+    flow_unattended_off: z.strictObject({ flow: id }),
+    incident_resolve: z.strictObject({ incident: id }),
+    // Follow-through: send a finding to the task that owns the code. Text is checked and cleaned when the card is made.
+    finding_send: z.strictObject({ task: words, summary: words.optional(), file: words.optional(), line: z.int().min(1).optional(), pointer: words.optional(), run: id.optional() }),
+    finding_resend: z.strictObject({ finding: id }),
+    task_reopen: z.strictObject({ task: words }),
+    revision_accept: z.strictObject({ task: words, revision: id.optional() }),
+    revision_reject: z.strictObject({ task: words, revision: id.optional() }),
+    flow_unattended: z.strictObject({ flow: id, days: z.int().min(1), budget: words.optional(), runs: words.optional(), include: z.array(id).optional() }),
+    memory_decide: z.strictObject({ repo: words, proposal: id, decision: z.enum(["accept", "reject"]) }),
     code_map_holdout_end: z.strictObject({ repo: words }),
     /** The line, and (from 1) the line it replaces; 0 or none adds it. */
     lead_about_you: z.strictObject({ line: words, replaces: z.int().min(0).optional() }),