toolroll 0.9.5 → 0.9.7

package/dist/check-levels.d.ts

@@ -0,0 +1,67 @@
+import type { Store, VerifyCommand } from "./store.js";
+export declare const CHECK_LEVELS: readonly ["quick", "full", "off"];
+export type CheckLevel = (typeof CHECK_LEVELS)[number];
+export declare const isCheckLevel: (value: unknown) => value is CheckLevel;
+export declare const CHECK_LEVEL_WORDS: Readonly<Record<CheckLevel, string>>;
+export declare const CHECK_LEVEL_HINTS: Readonly<Record<CheckLevel, string>>;
+/** Ledger actions. The ledger is append-only, so the newest entry is the setting. */
+export declare const PROJECT_LEVEL_ACTION = "check level changed";
+export declare const TASK_LEVEL_ACTION = "task checks chosen";
+export declare const RUN_LEVEL_ACTION = "checks used";
+/** The quick command's grant lives beside the full one under its own key. */
+export declare const quickVerifyKey: (repo: string) => string;
+export declare function liveQuickCommand(store: Store, repo: string): VerifyCommand | null;
+/** Ledger reads go through the repo index: `repo = ?` (or IS NULL for unplaced work). */
+export declare const repoClause: (repo: string | null) => [string, string[]];
+export declare function repoOfRun(store: Store, runId: number): string | null;
+export type ProjectCheckLevel = {
+    level: CheckLevel;
+    setBy: string | null;
+    at: string | null;
+};
+/** A project's level. With nothing recorded it is Full: a project that existed
+ * before levels keeps exactly the check it had. New projects are stamped Quick
+ * when they are added (stampNewProjectLevel). */
+export declare function projectCheckLevel(store: Store, repo: string): ProjectCheckLevel;
+/** An approver's act: set the project's level. The ledger keeps before → after. */
+export declare function setProjectCheckLevel(store: Store, repo: string, level: CheckLevel, by: string, now: Date): {
+    changed: boolean;
+    before: CheckLevel;
+};
+/** A project added from now on starts on Quick. One that already has a level,
+ * or an approved check from before levels existed, is left exactly as it is. */
+export declare function stampNewProjectLevel(store: Store, repo: string, now: Date): boolean;
+/** A task's own choice, if it made one; a revision inherits the task it revises. */
+export declare function taskCheckLevel(store: Store, taskId: string): CheckLevel | null;
+/** A filing choice: this task's checks, overriding the project. Fixed once its
+ * plan is approved, so what the approver saw is what runs. */
+export declare function setTaskCheckLevel(store: Store, taskId: string, level: CheckLevel, by: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export type EffectiveCheckLevel = {
+    level: CheckLevel;
+    from: "task" | "project";
+};
+export declare function effectiveCheckLevel(store: Store, repo: string | null, taskId: string | null): EffectiveCheckLevel;
+/** The command a level runs. Quick without its own command runs the full one
+ * (and says so: the level that ran is Full). Off runs nothing. */
+export declare function checkCommandFor(store: Store, repo: string, level: CheckLevel): {
+    level: CheckLevel;
+    command: VerifyCommand | null;
+};
+/** The builder records which level a run used, so its result says it honestly. */
+export declare function recordRunCheckLevel(store: Store, run: {
+    id: number;
+    taskId: string;
+    repo: string | null;
+}, level: CheckLevel, from: EffectiveCheckLevel["from"], now: Date): void;
+/** The level a finished run's checks used; null for a run from before levels. */
+export declare function runCheckLevel(store: Store, runId: number): CheckLevel | null;
+/** A starting point for the quick command, from the project's own scripts.
+ * It is only a suggestion: a person approves the exact command. */
+export declare function suggestQuickCommand(repo: string): string | null;
+/** "skip the tests", "run the full checks": a filing request in chat, as a level. */
+export declare function checkLevelFromWords(text: string): CheckLevel | null;

package/dist/check-levels.js

@@ -0,0 +1,171 @@
+/** Check levels: how much of the project check runs after a build.
+ *
+ * - Quick: a fast check while work is in progress (typecheck plus the tests
+ *   near the change). New projects start here.
+ * - Full: the project's approved check, as before. Projects that already
+ *   had a check keep it.
+ * - Off: no check. The result reads Ready for review, with "Checks: Off for this project" underneath.
+ *
+ * Nothing here needs a new table. A project's level and a task's choice are
+ * append-only ledger entries (the newest one wins, and the ledger already
+ * says who changed what, when). The quick command is a second approved
+ * verification grant with its own digest, kept under a `quick:` key beside
+ * the full one, so approving it is the same ceremony as `verify set`. */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { approvalOf } from "./scope.js";
+export const CHECK_LEVELS = ["quick", "full", "off"];
+export const isCheckLevel = (value) => typeof value === "string" && CHECK_LEVELS.includes(value);
+export const CHECK_LEVEL_WORDS = { quick: "Quick", full: "Full", off: "Off" };
+export const CHECK_LEVEL_HINTS = {
+    quick: "A fast check while building: typecheck and the tests near the change.",
+    full: "The project's full check after every build.",
+    off: "No check. Results are Ready for review, and say no check ran.",
+};
+/** Ledger actions. The ledger is append-only, so the newest entry is the setting. */
+export const PROJECT_LEVEL_ACTION = "check level changed";
+export const TASK_LEVEL_ACTION = "task checks chosen";
+export const RUN_LEVEL_ACTION = "checks used";
+/** The quick command's grant lives beside the full one under its own key. */
+export const quickVerifyKey = (repo) => `quick:${repo}`;
+export function liveQuickCommand(store, repo) {
+    return store.liveVerifyCommand(quickVerifyKey(repo));
+}
+/** Ledger reads go through the repo index: `repo = ?` (or IS NULL for unplaced work). */
+export const repoClause = (repo) => repo === null ? ["repo IS NULL", []] : ["repo = ?", [repo]];
+export function repoOfRun(store, runId) {
+    const run = store.getRun(runId);
+    return run === null ? null : store.refById(run.taskRef)?.repo ?? null;
+}
+function newest(store, sql, ...params) {
+    const row = store.handle.prepare(sql).get(...params);
+    return row === undefined ? null : { actor: String(row["actor"]), at: String(row["at"]), outcome: String(row["outcome"]) };
+}
+/** A project's level. With nothing recorded it is Full: a project that existed
+ * before levels keeps exactly the check it had. New projects are stamped Quick
+ * when they are added (stampNewProjectLevel). */
+export function projectCheckLevel(store, repo) {
+    const row = newest(store, "SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1", repo, PROJECT_LEVEL_ACTION);
+    if (row === null || !isCheckLevel(row.outcome))
+        return { level: "full", setBy: null, at: null };
+    return { level: row.outcome, setBy: row.actor, at: row.at };
+}
+/** An approver's act: set the project's level. The ledger keeps before → after. */
+export function setProjectCheckLevel(store, repo, level, by, now) {
+    const before = projectCheckLevel(store, repo);
+    if (before.level === level && before.setBy !== null)
+        return { changed: false, before: before.level };
+    store.recordAction({ at: now.toISOString(), actor: by, repo, taskId: null, runId: null, action: PROJECT_LEVEL_ACTION, outcome: level, source: "policy",
+        detail: `${CHECK_LEVEL_WORDS[before.level]} → ${CHECK_LEVEL_WORDS[level]}` });
+    return { changed: before.level !== level, before: before.level };
+}
+/** A project added from now on starts on Quick. One that already has a level,
+ * or an approved check from before levels existed, is left exactly as it is. */
+export function stampNewProjectLevel(store, repo, now) {
+    const known = newest(store, "SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? LIMIT 1", repo, PROJECT_LEVEL_ACTION);
+    if (known !== null)
+        return false;
+    const hadCheck = store.handle.prepare("SELECT 1 FROM verify_command WHERE repo = ? LIMIT 1").get(repo) !== undefined;
+    if (hadCheck)
+        return false;
+    store.recordAction({ at: now.toISOString(), actor: "system", repo, taskId: null, runId: null, action: PROJECT_LEVEL_ACTION, outcome: "quick", source: "policy",
+        detail: "New project → Quick" });
+    return true;
+}
+/** A task's own choice, if it made one; a revision inherits the task it revises. */
+export function taskCheckLevel(store, taskId) {
+    let id = taskId;
+    for (let depth = 0; id !== null && depth < 64; depth++) {
+        const ref = store.lookupRef(id);
+        const [where, params] = repoClause(ref?.repo ?? null);
+        const row = newest(store, `SELECT actor, at, outcome FROM action_ledger WHERE ${where} AND task_id = ? AND action = ? ORDER BY id DESC LIMIT 1`, ...params, id, TASK_LEVEL_ACTION);
+        if (row !== null && isCheckLevel(row.outcome))
+            return row.outcome;
+        id = ref?.revisionOf ?? null;
+    }
+    return null;
+}
+/** A filing choice: this task's checks, overriding the project. Fixed once its
+ * plan is approved, so what the approver saw is what runs. */
+export function setTaskCheckLevel(store, taskId, level, by, now) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null)
+        return { ok: false, message: `No task ${taskId}.` };
+    if (approvalOf(store.getScope(taskId)).approved) {
+        return { ok: false, message: "This task's plan is already approved, so its checks are fixed. File a new task to change them." };
+    }
+    if (taskCheckLevel(store, taskId) === level)
+        return { ok: true };
+    store.recordAction({ at: now.toISOString(), actor: by, repo: ref.repo, taskId, runId: null, action: TASK_LEVEL_ACTION, outcome: level, source: "request",
+        detail: `Checks for this task: ${CHECK_LEVEL_WORDS[level]}` });
+    return { ok: true };
+}
+export function effectiveCheckLevel(store, repo, taskId) {
+    const own = taskId === null ? null : taskCheckLevel(store, taskId);
+    if (own !== null)
+        return { level: own, from: "task" };
+    return { level: repo === null ? "full" : projectCheckLevel(store, repo).level, from: "project" };
+}
+/** The command a level runs. Quick without its own command runs the full one
+ * (and says so: the level that ran is Full). Off runs nothing. */
+export function checkCommandFor(store, repo, level) {
+    if (level === "off")
+        return { level: "off", command: null };
+    if (level === "quick") {
+        const quick = liveQuickCommand(store, repo);
+        if (quick !== null)
+            return { level: "quick", command: quick };
+    }
+    return { level: "full", command: store.liveVerifyCommand(repo) };
+}
+/** The builder records which level a run used, so its result says it honestly. */
+export function recordRunCheckLevel(store, run, level, from, now) {
+    store.recordAction({ at: now.toISOString(), actor: "system", repo: run.repo, taskId: run.taskId, runId: run.id, action: RUN_LEVEL_ACTION, outcome: level, source: "work",
+        detail: `${CHECK_LEVEL_WORDS[level]} checks (${from === "task" ? "this task's choice" : "project setting"})` });
+}
+/** The level a finished run's checks used; null for a run from before levels. */
+export function runCheckLevel(store, runId) {
+    const [where, params] = repoClause(repoOfRun(store, runId));
+    const row = newest(store, `SELECT actor, at, outcome FROM action_ledger WHERE ${where} AND run_id = ? AND action = ? ORDER BY id DESC LIMIT 1`, ...params, runId, RUN_LEVEL_ACTION);
+    return row !== null && isCheckLevel(row.outcome) ? row.outcome : null;
+}
+/** A starting point for the quick command, from the project's own scripts.
+ * It is only a suggestion: a person approves the exact command. */
+export function suggestQuickCommand(repo) {
+    const file = join(repo, "package.json");
+    if (!existsSync(file))
+        return null;
+    let scripts = {};
+    let deps = {};
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        scripts = parsed.scripts ?? {};
+        deps = { ...(parsed.dependencies ?? {}), ...(parsed.devDependencies ?? {}) };
+    }
+    catch {
+        return null;
+    }
+    const has = (name) => typeof scripts[name] === "string";
+    const runner = existsSync(join(repo, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(repo, "yarn.lock")) ? "yarn" : "npm";
+    const run = (name) => runner === "npm" ? `npm run ${name}` : `${runner} ${name}`;
+    const exec = runner === "npm" ? "npx" : `${runner} exec`;
+    const typecheck = ["typecheck", "type-check", "check-types", "tsc"].find(has) ?? null;
+    const changed = "$(git diff --name-only HEAD~1)";
+    const tests = "vitest" in deps ? `${exec} vitest related --run ${changed}`
+        : "jest" in deps ? `${exec} jest --findRelatedTests --passWithNoTests ${changed}` : null;
+    const parts = [typecheck === null ? null : run(typecheck), tests].filter((one) => one !== null);
+    if (parts.length > 0)
+        return parts.join(" && ");
+    return has("lint") ? run("lint") : null;
+}
+/** "skip the tests", "run the full checks": a filing request in chat, as a level. */
+export function checkLevelFromWords(text) {
+    const said = text.toLowerCase().replace(/[’']/g, "'");
+    if (/\b(skip|without|no|don't run|do not run|turn off|switch off)\b[^.!?\n]{0,20}\b(the )?(tests|checks)\b/.test(said) || /\b(tests|checks) off\b/.test(said))
+        return "off";
+    if (/\b(full|all the|every|complete)\s+(test|check)s?\b/.test(said))
+        return "full";
+    if (/\bquick\s+(test|check)s?\b/.test(said))
+        return "quick";
+    return null;
+}

package/dist/claim.d.ts

@@ -411,6 +411,28 @@ export declare function finalizeInterruptedFenced(store: Store, args: {
     committed?: boolean;
     now: Date;
 }): InterruptSeal;
+/**
+ * Hand an attempt back because the SERVICE stopped (its builder is
+ * stopping or restarting), not because anyone stopped the task: one fenced
+ * transaction releases the claim as `interrupted`, ends the run (and every
+ * open run it owns) as `failed` / `interrupted` — the words dead-runner
+ * recovery writes, so the next attempt inherits the preserved work in the
+ * same checkout exactly as after a crash — and returns the task to the
+ * queue with no strike, no backoff and no hold, so the next builder pass
+ * resumes it. A lease the world moved past still ends the run, touching no
+ * task state.
+ */
+export declare function finalizeHandBackFenced(store: Store, args: {
+    leaseId: string;
+    runId: number;
+    taskId: string;
+    message: string;
+    now: Date;
+}): {
+    ok: true;
+    requeued: boolean;
+    fenced: boolean;
+};
 /**
  * THE STOP FENCE at settlement (v52): when a stop applies to the run —
  * its own or an owning ancestor's — seal the attempt as interrupted and

package/dist/claim.js

@@ -1003,6 +1003,49 @@ export function finalizeInterruptedFenced(store, args) {
         return { ok: true, stopRun, requeued: Number(requeued.changes) > 0, fenced: false };
     });
 }
+/**
+ * Hand an attempt back because the SERVICE stopped (its builder is
+ * stopping or restarting), not because anyone stopped the task: one fenced
+ * transaction releases the claim as `interrupted`, ends the run (and every
+ * open run it owns) as `failed` / `interrupted` — the words dead-runner
+ * recovery writes, so the next attempt inherits the preserved work in the
+ * same checkout exactly as after a crash — and returns the task to the
+ * queue with no strike, no backoff and no hold, so the next builder pass
+ * resumes it. A lease the world moved past still ends the run, touching no
+ * task state.
+ */
+export function finalizeHandBackFenced(store, args) {
+    const { leaseId, runId, taskId, now } = args;
+    const db = store.handle;
+    return inTransaction(store, () => {
+        const run = store.getRun(runId);
+        if (run === null || run.leaseId !== leaseId || run.outcome !== null) {
+            throw new Error(`run ${runId} is not ${leaseId}'s open attempt — a hand-back seals exactly one`);
+        }
+        const { changes } = db
+            .prepare(`UPDATE claim SET released_at = ?, released_by = 'interrupted'
+          WHERE lease_id = ? AND released_at IS NULL AND ${NOT_SUPERSEDED}`)
+            .run(now.toISOString(), leaseId);
+        const fenced = Number(changes) === 0;
+        if (args.message.trim() !== "")
+            store.recordOutcomeFacts(runId, { handoff: args.message });
+        for (const owned of store.ownedRunsOf(runId)) {
+            if (owned === runId)
+                continue;
+            const child = store.getRun(owned);
+            if (child !== null && child.outcome === null)
+                store.finishRun(owned, { outcome: "failed", reason: "interrupted", now });
+        }
+        store.finishRun(runId, { outcome: "failed", reason: "interrupted", now });
+        if (fenced)
+            return { ok: true, requeued: false, fenced: true };
+        const requeued = db
+            .prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ? AND state = 'running'")
+            .run(now.toISOString(), taskId);
+        store.bumpWake();
+        return { ok: true, requeued: Number(requeued.changes) > 0, fenced: false };
+    });
+}
 /**
  * THE STOP FENCE at settlement (v52): when a stop applies to the run —
  * its own or an owning ancestor's — seal the attempt as interrupted and

package/dist/cli.d.ts

@@ -39,7 +39,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\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 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 integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local 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> / 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 the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\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 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 integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local 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> / 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 the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with

package/dist/cli.js

@@ -65,6 +65,7 @@ Usage
   toolroll session          native coding sessions through the running service
   toolroll connect          save a private connection to your central service
   toolroll lead             named leads on the connected service
+  toolroll lead token       mint your lead agent's credential: its own work pings nobody
   toolroll conversation     shared and private conversations on that service
   toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)
 
@@ -192,6 +193,8 @@ export const TOP_LEVEL_COMMANDS = [
 ];
 export const OPERATE_COMMANDS = new Set([
     "up",
+    // Only `lead token` reaches here; the central service's lead verbs answer first.
+    "lead",
     "onboard",
     "status",
     "ready",
@@ -1275,6 +1278,7 @@ async function runDemoCommand(argv, write) {
         write(`  sandbox   ${sandbox}`);
         write("");
         write("Open Chat and ask for a change, like \"fix the flaky refund test\".");
+        write("For your own project, run `npx toolroll up` in its folder.");
         write("");
         write(keep
             ? "Ctrl-C stops the server; the sandbox is KEPT. It stays a demo forever — every spending command refuses it."

package/dist/demo-chat.d.ts

@@ -1,8 +1,3 @@
-/**
- * Chat in `toolroll demo`: the scripted lead's conversation (src/demo.ts),
- * rendered as plain server HTML with native forms. One small script keeps a
- * running build's progress live; without it the page still works by reload.
- */
 import type { DemoExchange } from "./demo.js";
 /** What a finished exchange's stored result holds, read back from its evidence. */
 export type DemoResultView = {

package/dist/demo-chat.js

@@ -1,3 +1,10 @@
+/**
+ * Chat in `toolroll demo`: the scripted lead's conversation (src/demo.ts),
+ * rendered as plain server HTML with native forms. One small script keeps a
+ * running build's progress live; without it the page still works by reload.
+ */
+import { START_COMMAND } from "./first-run.js";
+import { headlineOf } from "./task-status.js";
 const SUGGESTIONS = ["Fix the flaky refund test", "Rewrite the empty Payouts page", "Put the new invoice view behind a flag"];
 const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 const hidden = (csrf) => `<input type="hidden" name="csrf" value="${esc(csrf)}">`;
@@ -52,9 +59,11 @@ function diffHtml(diff) {
 function resultCard(exchange, csrf, result) {
     if (result === null)
         return `<section class="card demo-result"><p class="meta">This result's saved evidence is unavailable.</p></section>`;
-    const status = exchange.state === "complete" ? `<span class="badge demo-complete">Complete</span>`
-        : exchange.state === "sent-back" ? `<span class="badge">Sent back</span>` : `<span class="badge demo-ready">Ready</span>`;
     const passed = result.checks.status === "passed";
+    // The shared headline (task-status.ts): the same words as every real task.
+    const headline = headlineOf({ stage: exchange.state === "complete" ? "complete" : exchange.state === "sent-back" ? "building" : "finished",
+        checks: { status: passed ? "passed" : "failed", exitCode: null, head: null } });
+    const status = `<span class="badge${headline === "Complete" ? " demo-complete" : headline === "Ready for review" ? " demo-ready" : ""}" data-headline="${headline}">${headline}</span>`;
     const summary = `${result.files} file${result.files === 1 ? "" : "s"} changed · +${result.additions} −${result.deletions} · ` +
         `<span class="${passed ? "demo-pass" : "demo-fail"}">${esc(result.checks.detail)}</span>`;
     const actions = exchange.state === "ready"
@@ -92,7 +101,9 @@ export function demoThreadHtml(exchanges, csrf, resultOf) {
         if (exchange.state === "ready" || exchange.state === "complete" || exchange.state === "sent-back")
             parts.push(resultCard(exchange, csrf, resultOf(exchange)));
         if (exchange.state === "complete") {
-            parts.push(`<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`);
+            parts.push(`<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, `<section class="card demo-handoff" data-demo-handoff aria-label="Your own project"><h2>Now try it on your own project</h2>` +
+                `<p>In your repository's folder, run:</p><pre class="demo-command"><code>${esc(START_COMMAND)}</code></pre>` +
+                `<p class="meta">It opens in your browser, already signed in.</p></section>`);
         }
         return `<article class="demo-turn" id="demo-${exchange.id}">${parts.join("")}</article>`;
     }).join("");

package/dist/dispatch.js

@@ -12,6 +12,7 @@ import { approvalOf } from "./scope.js";
 import { plannerSourceProblemOf } from "./planner-source.js";
 import { authPauseOf, authWaitOf, providerName, signInReason } from "./provider-auth.js";
 import { REVIEW_TOKENS, resultStatusOf, reviewFactsOf } from "./workspace-ui.js";
+import { replacedWords } from "./task-status.js";
 import { BUILT_IN, parseCapabilityKey } from "./store.js";
 export const DEFAULT_MAX_OPEN_DECISIONS = 5;
 /**
@@ -210,8 +211,12 @@ export function diagnoseTaskDispatch(store, taskId, now) {
             ? `${status.detail} Its independent review succeeded on attempt ${review.attempt} of ${review.cap}.`
             : status.detail, { action: "open-result", review });
     }
-    if (task.state === "cancelled")
-        return answer("cancelled", "terminal", "Cancelled", "Nothing else will run for this task.");
+    if (task.state === "cancelled") {
+        // Replaced, never "Cancelled": a successor carries the work on.
+        const successor = store.replacementOf(taskId);
+        return successor === null ? answer("cancelled", "terminal", "Cancelled", "Nothing else will run for this task.")
+            : answer("cancelled", "terminal", replacedWords(successor), `${replacedWords(successor)}. Nothing else will run for this task.`);
+    }
     if (task.state === "failed")
         return answer("failed", "terminal", "Needs a retry", "The last attempt stopped; review its incident, then retry it.", { action: "retry-task" });
     if (store.hasLiveClaim(ref.id, now))

package/dist/dispose.d.ts

@@ -73,6 +73,14 @@ export type Disposition = {
     kind: "stopped";
     stopRun: number;
     requeued: boolean;
+}
+/** The service stopped or restarted while the attempt ran (no one stopped
+ * the task): its work is preserved, the run ends as interrupted, and the
+ * task is back in the queue — no strike, no backoff — so the next builder
+ * pass resumes it from the kept work. */
+ | {
+    kind: "handed-back";
+    requeued: boolean;
 } | {
     kind: "invariant";
     reason: string;

package/dist/dispose.js

@@ -14,7 +14,7 @@ import { originalTaskBase, focusedTestCommandSupported } from "./observations.js
  * inlined before.
  */
 import { createHash } from "node:crypto";
-import { completeFenced, finalizeFailureFenced, finalizeMalformedFenced, finalizeParkFenced, interruptIfStopped, release, } from "./claim.js";
+import { completeFenced, finalizeFailureFenced, finalizeHandBackFenced, finalizeMalformedFenced, finalizeParkFenced, interruptIfStopped, release, } from "./claim.js";
 import { bodyHashOf, publicationBody } from "./publish.js";
 import { modeTermsFromJson } from "./modes.js";
 import { readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
@@ -338,6 +338,12 @@ function disposeBuildOutcomeLocked(context, result) {
         });
         return { kind: "malformed", sealed: sealed.ok };
     }
+    // A stop no operator asked for is the SERVICE stopping (the fence above
+    // already settled every task stop): hand the attempt back, never strike it.
+    if (result.reason === "stopped" && policy === "tick" && leaseId !== undefined && store.getRun(runId)?.role === "builder") {
+        const handed = finalizeHandBackFenced(store, { leaseId, runId, taskId, message: result.message, now: clock() });
+        return { kind: "handed-back", requeued: handed.requeued };
+    }
     if (TICK_FAILURE_REASONS.has(result.reason)) {
         // One fenced transaction decides what the failure means. The
         // classification trusts only what the machine itself observed.

package/dist/export.js

@@ -33,7 +33,7 @@ const SECRET_TABLES = new Set(["web_session", "ceremony_nonce", "telegram_pairin
 const DERIVED_TABLE = /^(sqlite_|memory_search)/;
 /** Columns that hold a secret (or what stands in for one): never exported. */
 const SECRET_COLUMNS = new Set([
-    "api_token.secret_hash", "approver.credential_hash", "coordinator_credential.credential_hash", "runner.credential_hash", "invite.token_hash",
+    "api_token.secret_hash", "lead_credential.secret_hash", "approver.credential_hash", "coordinator_credential.credential_hash", "runner.credential_hash", "invite.token_hash",
     "flow_trigger.hook_hash", "held_session.cookie", "push_subscription.endpoint", "push_subscription.p256dh", "push_subscription.auth",
     "chat_turn.credential_key", "mate_session.credential_key", "mate_turn.credential_key", "bridge_lease.push_url", "workflow_preview.token",
     "quota.credential_fp",
@@ -56,7 +56,7 @@ export function categoryOf(table) {
         [/^teammate/, "teammates"],
         [/^(flow|routine|workflow_)/, "flows"],
         [/^(chat_|mate_|team_|telegram_|slack_|discord_|teams_|notification|push_|bridge_lease)/, "chats"],
-        [/^(approver|api_token|invite|sso_identity|coordinator_)/, "people"],
+        [/^(approver|api_token|lead_credential|invite|sso_identity|coordinator_)/, "people"],
         [/^(run|artifact|claim|worktree$|execution_slot|contest|tournament_terms|fallback_cycle|fallback_transition|held_session|session_turn|attended_authorization|criterion_review|diff_comment|proof_|review_request|repair_chain|incident|publication$|merge_|side_spend|knowledge_snapshot|learning_snapshot|skill_snapshot)/, "runs"],
         [/^(task|hold$|plan_|scope_|tool_seal|decision|external_|skill_test)/, "tasks"],
         [/^(project|approval_policy|capability|verify_command|worktree_setup|backend_grant|intake_grant|publication_grant|operating_mode|knowledge_|learning_|memory_|skill_)/, "projects"],
@@ -67,6 +67,7 @@ export function categoryOf(table) {
 /** Extra shapes beside the evidence scanner's: this installation's own tokens and password hashes, and bearer headers. */
 const EXTRA_SHAPES = [
     /\bso_[a-f0-9]{12}_[A-Za-z0-9_-]{43}/g,
+    /\blt_[a-f0-9]{12}_[A-Za-z0-9_-]{43}/g,
     /\bscrypt\$[^\s"',;]+/g,
     /\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
     /\bsk-[A-Za-z0-9_-]{20,}/g,

package/dist/first-run.d.ts

@@ -1,6 +1,20 @@
 import type { Runner } from "./backend.js";
 export declare const SIGN_IN_COMMAND = "claude auth login";
 export declare const SANDBOX_COMMAND = "npx toolroll demo";
+/** How a person starts on a real project (the demo hands off to this). */
+export declare const START_COMMAND = "npx toolroll up";
+/** How it works, once, above the composer until the first request. */
+export declare const HOW_IT_WORKS = "Ask for a change. The lead writes a short plan; you approve it; an agent builds it on its own branch; it's Ready when your tests pass.";
+type SignInState = "connected" | "signed-out" | "not-installed" | "unverified" | "key-present" | "key-works" | "key-refused" | "missing-key";
+/**
+ * The one command that gets an agent signed in on this computer: sign in to the CLI that's installed (Claude Code
+ * first, then Codex), or install Claude Code and sign in, written for this operating system's shell. Unknown states
+ * (not checked yet) get the install-and-sign-in command, which is right on a fresh machine and harmless otherwise.
+ */
+export declare function signInCommandFor(states: {
+    claude: SignInState;
+    codex: SignInState;
+} | null, platform: NodeJS.Platform): string;
 export type FirstRunAction = {
     kind: "link";
     label: string;
@@ -23,6 +37,7 @@ export type FirstRunFacts = {
     projects: number;
     hasTask: boolean;
     firstResultAt: string | null;
+    signInCommand?: string;
 };
 /** The three steps, each done or with the one action that does it; null once the first result has arrived. */
 export declare function firstRunSteps(facts: FirstRunFacts): FirstRunStep[] | null;
@@ -58,3 +73,22 @@ export declare const TODO_GREP_ARGS: readonly string[];
 export declare function findFirstTasks(repo: string, runner?: Runner): Promise<FirstTaskSuggestion[]>;
 /** "First result in 7 min": how long after the installation began its first Ready result arrived. */
 export declare function firstResultWords(since: string, at: string): string | null;
+/** The first task's five steps, as a person reads them. */
+export declare const JOURNEY_STEPS: readonly [readonly ["plan", "Plan"], readonly ["approve", "You approve"], readonly ["build", "Build"], readonly ["checks", "Checks"], readonly ["ready", "Ready"]];
+export type JourneyKey = (typeof JOURNEY_STEPS)[number][0];
+/** `stuck`: the step it stopped at (Failed, Stopped, or waiting on something other than the approval). */
+export type JourneyStep = {
+    key: JourneyKey;
+    label: string;
+    state: "done" | "current" | "stuck" | "todo";
+};
+/**
+ * Where the first task stands on Plan → You approve → Build → Checks → Ready, from the one stage every surface reads
+ * (task-status.ts). Waiting for a worker before approval is still the plan; after approval it is the build. `built`:
+ * the build finished with a result.
+ */
+export declare function firstTaskJourney(read: {
+    stage: "queued" | "planning" | "needs-you" | "building" | "checking" | "finished" | "complete" | "failed" | "stopped";
+    need?: string | undefined;
+}, approved: boolean, built?: boolean): JourneyStep[];
+export {};

package/dist/first-run.js

@@ -9,6 +9,23 @@ import { run } from "./exec.js";
 import { githubIssues } from "./issues.js";
 export const SIGN_IN_COMMAND = "claude auth login";
 export const SANDBOX_COMMAND = "npx toolroll demo";
+/** How a person starts on a real project (the demo hands off to this). */
+export const START_COMMAND = "npx toolroll up";
+/** How it works, once, above the composer until the first request. */
+export const HOW_IT_WORKS = "Ask for a change. The lead writes a short plan; you approve it; an agent builds it on its own branch; it's Ready when your tests pass.";
+/**
+ * The one command that gets an agent signed in on this computer: sign in to the CLI that's installed (Claude Code
+ * first, then Codex), or install Claude Code and sign in, written for this operating system's shell. Unknown states
+ * (not checked yet) get the install-and-sign-in command, which is right on a fresh machine and harmless otherwise.
+ */
+export function signInCommandFor(states, platform) {
+    const installed = (state) => state !== undefined && state !== "not-installed";
+    if (installed(states?.claude))
+        return SIGN_IN_COMMAND;
+    if (installed(states?.codex))
+        return "codex login";
+    return `npm install -g @anthropic-ai/claude-code${platform === "win32" ? ";" : " &&"} ${SIGN_IN_COMMAND}`;
+}
 /** The three steps, each done or with the one action that does it; null once the first result has arrived. */
 export function firstRunSteps(facts) {
     if (facts.firstResultAt !== null)
@@ -16,7 +33,7 @@ export function firstRunSteps(facts) {
     const project = facts.projects > 0;
     return [
         facts.agentSignedIn === null ? { key: "agent", title: "Agent signed in", done: false, action: null, checking: true }
-            : { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: SIGN_IN_COMMAND } },
+            : { key: "agent", title: "Agent signed in", done: facts.agentSignedIn, action: facts.agentSignedIn ? null : { kind: "command", command: facts.signInCommand ?? SIGN_IN_COMMAND } },
         { key: "project", title: "Project added", done: project, action: project ? null : { kind: "link", label: "Add a project", href: "/projects" } },
         { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
     ];
@@ -103,3 +120,22 @@ export function firstResultWords(since, at) {
     }
     return `First result in ${Math.round(minutes / (24 * 60))} days`;
 }
+/** The first task's five steps, as a person reads them. */
+export const JOURNEY_STEPS = [["plan", "Plan"], ["approve", "You approve"], ["build", "Build"], ["checks", "Checks"], ["ready", "Ready"]];
+/**
+ * Where the first task stands on Plan → You approve → Build → Checks → Ready, from the one stage every surface reads
+ * (task-status.ts). Waiting for a worker before approval is still the plan; after approval it is the build. `built`:
+ * the build finished with a result.
+ */
+export function firstTaskJourney(read, approved, built = false) {
+    const at = read.stage === "finished" || read.stage === "complete" ? { index: 5, stuck: false }
+        : read.stage === "checking" ? { index: 3, stuck: false }
+            : read.stage === "building" ? { index: 2, stuck: false }
+                : read.stage === "needs-you" && read.need === "approval" ? { index: 1, stuck: false }
+                    : read.stage === "planning" ? { index: 0, stuck: false }
+                        : read.stage === "queued" ? { index: approved ? 2 : 0, stuck: false }
+                            // A build that finished but isn't Ready (its checks failed or didn't run, or it needs a decision) stopped at Checks.
+                            : { index: built ? 3 : approved ? 2 : 0, stuck: true };
+    return JOURNEY_STEPS.map(([key, label], index) => ({ key, label,
+        state: index < at.index ? "done" : index === at.index ? (at.stuck ? "stuck" : "current") : "todo" }));
+}