toolroll 0.9.62 → 0.9.65

package/dist/chat-delivery.js

@@ -26,7 +26,33 @@ import { isShotsKind, resultShotsFor } from "./result-shots.js";
 import { CHAT_APP_NAMES } from "./flow-triggers.js";
 import { answersPrompt, applyDecideFeedback, applyDecideTap, decideFallbackLink, decideOffer, decideTargetOf, hasLiveDecideTokens, linksFor, mergedText, mintDecideButtons, offerFingerprint, openPromptFor, recordChatMerge } from "./chat-decide.js";
 import { mergePullRequest } from "./pull-request-flow.js";
-import { watchedPing } from "./agent-board.js";
+import { attentionSubjectOf, neverHeld, watchedPing } from "./agent-board.js";
+/**
+ * The watch at a chat app's final fence (cockpit §3, R11), right before the network: a notice about an agent its
+ * person has open now waits, as a held part, until the watch ends; then it is delivered as usual. The subject is the
+ * part's own run, or its task's live build. Only a part planned with `watch` (never a security alert or the digest)
+ * can be held. True: held, so nothing is sent now.
+ */
+export function heldForWatch(state, store, part, event, approver, content, now) {
+    // Fail closed: only a notice planned as holdable (a kind a watch may hold) is ever held here.
+    if (event.kind !== "notice" || content.watch !== true)
+        return false;
+    // One part may cover several tasks (a grouped card, a batch): it waits only while every one of them is watched,
+    // until the first of those watches ends.
+    const subjects = content.subjects ?? [{ ref: content.task ? store.lookupRef(content.task)?.id ?? null : null, run: content.run ?? null }];
+    if (subjects.length === 0)
+        return false;
+    let until = null;
+    for (const subject of subjects) {
+        const decided = watchedPing(store, { kind: "notice", run: subject.run, taskRef: subject.ref }, approver, now);
+        if (decided === "send" || decided === "skip")
+            return false;
+        if (until === null || decided.hold < until)
+            until = decided.hold;
+    }
+    state.holdPart(part, until);
+    return true;
+}
 export const chatObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
     ? v
     : {};
@@ -397,8 +423,9 @@ export async function processChatEvent(options) {
                 return false;
             if (!outcome.ok &&
                 "refused" in outcome &&
-                outcome.refused === "concurrent") {
-                state.defer(event.id, "Assistant is answering another message", new Date(nowOf(options).getTime() + 5000));
+                (outcome.refused === "concurrent" || outcome.refused === "backlog")) {
+                // The lead is answering, or messages sent earlier wait in the person's lead queue: this one waits its turn.
+                state.defer(event.id, outcome.refused === "backlog" ? "Waiting behind earlier messages" : "Assistant is answering another message", new Date(nowOf(options).getTime() + 5000));
                 return true;
             }
             receipt = store.leadRequestReceipt(resolved.session.id, request);
@@ -422,7 +449,7 @@ export async function processChatEvent(options) {
         if (turn?.state !== "answered") {
             state.plan(event.id, [
                 {
-                    text: leadFailureText(turn?.failureReason ?? null),
+                    text: leadFailureText(turn?.failureReason ?? null, turn != null && store.leadTurnCostUnconfirmed(turn.id)),
                 },
             ], nowOf(options));
             return true;
@@ -734,7 +761,12 @@ function planQuietCard(options, binding, notification, now) {
     const view = quietCardView(store, card.tasks, now, options.evidenceRoot, binding.approver);
     if (view === null)
         return;
-    const content = { text: view.text, link: view.link, ...(card.tasks.length === 1 ? { task: notification.taskId } : {}) };
+    // A card about one task is that task's: its person's watch may hold it at the final fence (never a security kind).
+    // A card about its tasks is theirs: its person's watch may hold it at the final fence while every one of them is
+    // watched (never for a security kind).
+    const content = { text: view.text, link: view.link, ...(card.tasks.length === 1 ? { task: notification.taskId } : {}),
+        ...(card.tasks.length > 0 && !neverHeld(notification.kind) ? { watch: true } : {}),
+        ...(card.tasks.length > 1 && !neverHeld(notification.kind) ? { subjects: card.tasks.slice(0, 100).map(ref => ({ ref, run: null })) } : {}) };
     const shown = chatHash(JSON.stringify(content));
     if (card.message !== null) {
         if (card.digest === shown)
@@ -763,7 +795,12 @@ function planFinished(options, binding, taskRef, run, now, notification = null,
     // A single update keeps its task and run, so a reply to it names that work.
     const single = batch.items.length === 1 ? batch.items[0] : null;
     const task = single === null ? null : store.refById(single.taskRef)?.externalId ?? null;
-    const about = { ...(task === null ? {} : { task }), ...(single?.run == null ? {} : { run: single.run }) };
+    // Holdable when its fact is a kind a watch may hold (the batch line for a finished run, or the notification joining
+    // it); a batch of several holds only while every one of them is watched.
+    const joining = notification === null ? null : options.store.notificationById(notification);
+    const holdable = batch.items.length > 0 && (joining === null || !neverHeld(joining.kind));
+    const about = { ...(task === null ? {} : { task }), ...(single?.run == null ? {} : { run: single.run }), ...(holdable ? { watch: true } : {}),
+        ...(holdable && batch.items.length > 1 ? { subjects: batch.items.slice(0, 100).map(one => ({ ref: one.taskRef, run: one.run })) } : {}) };
     // A message about one result, plan, failure or pull request acts in place (chat-decide.ts), as on Telegram: its
     // buttons are minted only when what it offers changed, or its own were spent (Not now), so an unchanged repaint keeps them.
     const offer = decideOfferFor(options, binding, view.target, repos, now);
@@ -962,6 +999,7 @@ function offerNotice(options, notification, binding, registry) {
                     task: notification.taskId,
                     run: run.id,
                     link: card.link,
+                    ...(attentionSubjectOf(store, notification) !== null ? { watch: true } : {}),
                 };
                 const digest = chatHash(JSON.stringify(content));
                 const prior = state
@@ -1044,6 +1082,7 @@ function offerNotice(options, notification, binding, registry) {
                         text: offer?.text ?? chatText(phoneText(notification.body === "" ? leadSubjectOf(store, notification, binding.approver) : `${leadSubjectOf(store, notification, binding.approver)}\n\n${notification.body}`, 2500), notification.taskId === null ? [] : [{ id: notification.taskId, title: chatTitle(store, notification.taskId) }]),
                         ...(notification.taskId ? { task: notification.taskId } : {}),
                         ...(run ? { run: run.id } : {}),
+                        ...(attentionSubjectOf(store, notification) !== null ? { watch: true } : {}),
                         ...(offer !== null ? { decide: mintDecide(options, binding, target, offer, now) }
                             : fallback !== null ? { link: fallback }
                                 : notification.link

package/dist/chat-messages.d.ts

@@ -174,6 +174,8 @@ export declare class ChatMessages extends ChatCore {
         taskId: string | null;
         sourceRun: number | null;
     }, now: Date): number;
+    /** How many of this chat's messages wait for, or are being answered by, the lead (the lead queue's bound per chat). */
+    messagesWaiting(binding: number): number;
     /** Whether a message from this chat is already waiting on, or being answered from, this bot message (a tapped question). */
     messageWaitingOn(binding: number, messageId: string): boolean;
     getMessage(id: number): TelegramConversation | null;
@@ -294,6 +296,12 @@ export declare class ChatMessages extends ChatCore {
     claimDeliveries(binding: TelegramBinding, owner: string, ttlMs: number, now: Date, only?: "all" | "urgent"): TelegramDelivery[];
     /** Synchronous final fence, called AFTER each asynchronous enrollment read. */
     deliveryProblem(row: TelegramDelivery, binding: TelegramBinding, owner: string, projects: readonly string[], now: Date, batch?: readonly number[]): string | null;
+    /**
+     * The watch at the final fence (cockpit §3, R11): right before the network, a person who has since opened the
+     * agent this ping is about holds it — the claim is released with the watch's end as its next attempt, no attempt
+     * spent — and news about a finished run they have now seen settles quietly. "send": nothing changed.
+     */
+    watchFence(row: TelegramDelivery, binding: TelegramBinding, owner: string, now: Date): "send" | "held" | "skipped";
     claimHeld(row: TelegramDelivery, owner: string, now: Date): boolean;
     /** A confirmed network message remains history even if authority changed
      * while it was in flight. It only binds the OLD destination, never new work. */

package/dist/chat-messages.js

@@ -9,7 +9,7 @@
  * Imports the store's types only (no runtime cycle): the store builds its chats on it.
  */
 import { join } from "node:path";
-import { watchedPing } from "./agent-board.js";
+import { neverHeld, watchedPing } from "./agent-board.js";
 import { ChatCore } from "./chat-core.js";
 import { readChatMessageBody, readChatPart, savedChatEventBody, savedChatPart } from "./contracts/chat-content.js";
 import { isTelegramProgressNotification, proposalTaskOf, readNotification, readNotificationReceipt } from "./notification-rows.js";
@@ -381,6 +381,10 @@ export class ChatMessages extends ChatCore {
             .run(`m${row.updateId}`, row.binding.botId, row.binding.id, row.binding.chatId, row.binding.userId, row.messageId, row.replyTo ?? "", savedChatEventBody(body), now.toISOString());
         return row.updateId;
     }
+    /** How many of this chat's messages wait for, or are being answered by, the lead (the lead queue's bound per chat). */
+    messagesWaiting(binding) {
+        return Number(this.prepare("SELECT COUNT(*) AS n FROM chat_event WHERE provider = :provider AND kind = 'message' AND binding = ? AND state IN ('queued', 'running')").get(binding)?.["n"] ?? 0);
+    }
     /** Whether a message from this chat is already waiting on, or being answered from, this bot message (a tapped question). */
     messageWaitingOn(binding, messageId) {
         return this.prepare("SELECT 1 AS hit FROM chat_event WHERE provider = :provider AND kind = 'message' AND binding = ? AND ts = ? AND state IN ('queued', 'running') LIMIT 1").get(binding, messageId) !== undefined;
@@ -767,17 +771,45 @@ export class ChatMessages extends ChatCore {
                     return TELEGRAM_HOLD_REASONS.task;
             }
         }
-        if (row.taskRef !== null) {
+        // A security alert never waits behind its task's earlier pings (one may be held while its person watches the agent).
+        if (row.taskRef !== null && !neverHeld(String(current["kind"]))) {
             // Skipped history never fences what follows it: it is settled.
-            const earlier = this.db.prepare(`SELECT n.id FROM notification n
+            const earlier = this.db.prepare(`SELECT n.*, d.next_attempt_at AS held_until, d.last_error AS held_error FROM notification n
         LEFT JOIN notification_delivery d ON d.notification = n.id AND d.destination = ?
         WHERE n.task_ref = ? AND n.id < ? AND n.resolved_at IS NULL AND ${TELEGRAM_UNSETTLED}`)
                 .all(row.destination, row.taskRef, row.id);
-            if (earlier.some(one => !batch.includes(Number(one["id"]))))
+            // One a watch is holding (cockpit §3) keeps nothing behind it: it goes when the watch ends, and what followed
+            // it about another attempt is not that watch's to delay.
+            // Held: deferred by a watch (a future next attempt with no failure behind it), or watched right now.
+            const held = (one) => (one["held_until"] != null && String(one["held_until"]) > now.toISOString() && one["held_error"] == null)
+                || typeof watchedPing(this.store, readNotification(one), binding.approver, now) === "object";
+            if (earlier.some(one => !batch.includes(Number(one["id"])) && !held(one)))
                 return TELEGRAM_HOLD_REASONS.order;
         }
         return null;
     }
+    /**
+     * The watch at the final fence (cockpit §3, R11): right before the network, a person who has since opened the
+     * agent this ping is about holds it — the claim is released with the watch's end as its next attempt, no attempt
+     * spent — and news about a finished run they have now seen settles quietly. "send": nothing changed.
+     */
+    watchFence(row, binding, owner, now) {
+        const current = this.db.prepare("SELECT * FROM notification WHERE id = ?").get(row.id);
+        if (current === undefined)
+            return "send";
+        const decided = watchedPing(this.store, readNotification(current), binding.approver, now);
+        if (decided === "send")
+            return "send";
+        const where = "WHERE notification = ? AND destination = ? AND claim_owner = ? AND claim_generation = ? AND delivered_at IS NULL";
+        if (decided === "skip") {
+            this.db.prepare(`UPDATE notification_delivery SET receipt = '${TELEGRAM_SKIPPED_QUIET}', claim_owner = NULL, claim_expires_at = NULL ${where}`)
+                .run(row.id, row.destination, owner, row.claimGeneration);
+            return "skipped";
+        }
+        this.db.prepare(`UPDATE notification_delivery SET next_attempt_at = ?, claim_owner = NULL, claim_expires_at = NULL ${where}`)
+            .run(decided.hold, row.id, row.destination, owner, row.claimGeneration);
+        return "held";
+    }
     claimHeld(row, owner, now) {
         return this.db.prepare(`SELECT 1 FROM notification_delivery WHERE notification = ? AND destination = ?
       AND claim_owner = ? AND claim_generation = ? AND claim_expires_at > ? AND delivered_at IS NULL`)

package/dist/check-levels-ui.js

@@ -2,12 +2,12 @@
  * words. One choice (Quick, Full, Off) and the quick command beside the full
  * one. Every change takes the password and lands in the ledger; approving a
  * command restates exactly what will run, unattended, before the yes. */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 import { CHECK_LEVELS, CHECK_LEVEL_HINTS, CHECK_LEVEL_WORDS } from "./check-levels.js";
 import { BATCH_HINT } from "./batch-policy.js";
 export function checkSettingsHtml(view) {
     const post = (act, body, attrs) => postForm("/settings/checks", body, { attrs, hidden: { repo: view.repo, act } });
-    const password = html `<label>Password<input type="password" name="password" autocomplete="current-password" required></label>`;
+    const password = html `${reauth(html `<label>Password<input type="password" name="password" autocomplete="current-password" required></label>`)}`;
     const notes = [
         view.said === null ? "" : html `<p class="notice" role="status">${view.said}</p>`,
         view.problem === null ? "" : html `<p class="problem" role="alert">${view.problem}</p>`,

package/dist/check-levels.js

@@ -153,6 +153,9 @@ export function suggestQuickCommand(repo) {
     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}`;
+    // A project's own quick script knows its tests best (Toolroll's runs the attack suite when a guard changes).
+    if (has("check:quick"))
+        return run("check:quick");
     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)";

package/dist/checkout-proof.d.ts

@@ -0,0 +1,28 @@
+import type { Store } from "./store.js";
+export type CheckoutProof = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function localCheckoutOf(store: Store, runId: number, local: {
+    runner?: string | undefined;
+    poolRoot?: string | undefined;
+}, now: Date): CheckoutProof;
+/** How Finder is asked: the system's own `open` by absolute path (never found through PATH), from the root directory,
+ * with a minimal environment, one argument. True only when it answered success before the deadline: at the deadline
+ * the answer is "not shown", the child is killed outright, and anything it says later is ignored. */
+export type RevealExec = (file: string, args: readonly string[], options: {
+    cwd: string;
+    env: Record<string, string>;
+}, done: (error: Error | null) => void) => {
+    kill: (signal: NodeJS.Signals) => unknown;
+} | undefined;
+export declare const REVEAL_COMMAND = "/usr/bin/open";
+export declare const REVEAL_DEADLINE_MS = 10000;
+export declare function revealInFinder(path: string, run?: RevealExec, deadlineMs?: number, clock?: () => number): Promise<boolean>;
+/** Whether this console can ask Finder at all (a Mac, or a test's own revealer). */
+export declare const canReveal: (injected: boolean) => boolean;
+/** The command to paste into a terminal: `cd` to the path as one single-quoted shell word (a quote inside escaped). */
+export declare function cdCommandOf(path: string): string;

package/dist/checkout-proof.js

@@ -0,0 +1,62 @@
+/**
+ * A running attempt's checkout, proved to be on this machine (docs/plans/agents-cockpit.md phase E): the run is live
+ * under the task's current claim, its worktree row is this machine's runner's and this task's, and the path is its own
+ * real path, a directory inside this machine's pool. Used to offer "copy the cd command" and "Show in Finder" — and
+ * proved again immediately before Finder is asked to reveal it. Nothing is ever launched in it.
+ */
+import { execFile } from "node:child_process";
+import { lstatSync, realpathSync } from "node:fs";
+export function localCheckoutOf(store, runId, local, now) {
+    if (local.runner === undefined || local.poolRoot === undefined)
+        return { ok: false, reason: "this console doesn't run builds on this machine" };
+    const run = store.getRun(runId);
+    if (run === null || run.outcome !== null || run.worktree === null)
+        return { ok: false, reason: "this attempt has no running checkout" };
+    if (store.currentLiveLease(run.taskRef, now) !== run.leaseId)
+        return { ok: false, reason: "this attempt isn't the one running now" };
+    const row = store.getWorktree(run.worktree);
+    if (row === null || row.taskRef !== run.taskRef)
+        return { ok: false, reason: "the checkout isn't where the record says" };
+    // The run, its worktree row and this machine all name the same runner: an inconsistent record fails closed.
+    if (run.runner !== local.runner || row.runner !== local.runner)
+        return { ok: false, reason: "this attempt runs on another computer" };
+    try {
+        const real = realpathSync(run.worktree), pool = realpathSync(local.poolRoot);
+        // Strictly inside: the pool directory itself is never a checkout.
+        if (real !== run.worktree || !real.startsWith(`${pool}/`) || !lstatSync(real).isDirectory())
+            return { ok: false, reason: "the checkout isn't inside this machine's pool" };
+        return { ok: true, path: real };
+    }
+    catch {
+        return { ok: false, reason: "the checkout couldn't be found on this machine" };
+    }
+}
+export const REVEAL_COMMAND = "/usr/bin/open";
+export const REVEAL_DEADLINE_MS = 10_000;
+export function revealInFinder(path, run = (file, args, options, done) => execFile(file, [...args], options, error => done(error)), deadlineMs = REVEAL_DEADLINE_MS, clock = () => performance.now()) {
+    return new Promise(resolve => {
+        let settled = false;
+        let child;
+        // The deadline is a moment on a monotonic clock, not the timer having run: a success that arrives after it (even
+        // ahead of an overdue timer, in a stalled event loop) is "not shown".
+        const due = clock() + deadlineMs;
+        const finish = (shown) => { if (settled)
+            return; settled = true; clearTimeout(timer); resolve(shown); };
+        const timer = setTimeout(() => { finish(false); try {
+            child?.kill("SIGKILL");
+        }
+        catch { /* already gone */ } }, deadlineMs);
+        try {
+            child = run(REVEAL_COMMAND, ["-R", path], { cwd: "/", env: { PATH: "/usr/bin:/bin" } }, error => finish(error === null && clock() < due));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+/** Whether this console can ask Finder at all (a Mac, or a test's own revealer). */
+export const canReveal = (injected) => injected || process.platform === "darwin";
+/** The command to paste into a terminal: `cd` to the path as one single-quoted shell word (a quote inside escaped). */
+export function cdCommandOf(path) {
+    return `cd '${path.replaceAll("'", `'\\''`)}'`;
+}

package/dist/claim.d.ts

@@ -70,6 +70,13 @@ export type AcquireResult = {
     reason: "mode-ended";
     message: string;
 }
+/** A lead sweep's limit (docs/plans/lead-fan-out.md): `limit` of its families already hold a live claim. */
+ | {
+    ok: false;
+    reason: "sweep-limit";
+    sweep: number;
+    limit: number;
+}
 /** The credential presented with this acquisition did not verify against
  * the runner row AT CLAIM TIME (MCP spec v6): stale incarnations never
  * ride a successor's rotation. */
@@ -183,6 +190,11 @@ export { DEFAULT_MAX_OPEN_DECISIONS, missingCapability } from "./dispatch.js";
  * it, which is a race being won; not-ready means nobody should have it, and
  * says why.
  */
+/**
+ * A conformance check's claim (acp-check.ts): its task has no scope to approve, so readiness is not asked — but a
+ * check runs real agents, so the runner's capacity is counted where the claim lands, as for dispatch.
+ */
+export declare function acquireForCheck(store: Store, taskRef: number, runner: string, options: AcquireOptions): AcquireResult | NotReady;
 export declare function acquireIfReady(store: Store, taskRef: number, runner: string, options: AcquireOptions & {
     repo?: string;
     maxOpenDecisions?: number;

package/dist/claim.js

@@ -131,6 +131,12 @@ function acquireLocked(store, taskRef, runner, options) {
                 message: "the operating mode that approved this has ended — the approval falls back to a person",
             };
         }
+        // A LEAD SWEEP'S LIMIT, inside this write transaction so two runners can't both take the last slot: at most
+        // max_parallel of its families hold a live claim (claimed-but-not-started counts; a revision counts as its child).
+        const sweep = placedRef === null ? null : store.sweepOfTask(placedRef.externalId);
+        if (sweep !== null && store.sweepLiveClaims(sweep.id, stamp, taskRef) >= sweep.maxParallel) {
+            return { ok: false, reason: "sweep-limit", sweep: sweep.id, limit: sweep.maxParallel };
+        }
         const existing = latest(db, taskRef);
         if (existing !== undefined && isLive(existing, stamp)) {
             return {
@@ -199,6 +205,19 @@ export { DEFAULT_MAX_OPEN_DECISIONS, missingCapability } from "./dispatch.js";
  * it, which is a race being won; not-ready means nobody should have it, and
  * says why.
  */
+/**
+ * A conformance check's claim (acp-check.ts): its task has no scope to approve, so readiness is not asked — but a
+ * check runs real agents, so the runner's capacity is counted where the claim lands, as for dispatch.
+ */
+export function acquireForCheck(store, taskRef, runner, options) {
+    return inTransaction(store, () => {
+        const registered = store.getRunner(runner);
+        if (registered !== null && store.liveClaimCount(runner, options.now) >= registered.runner.capacity) {
+            return { ok: false, reason: "capacity", message: `${runner} has no free slot for a check` };
+        }
+        return acquireLocked(store, taskRef, runner, options);
+    });
+}
 export function acquireIfReady(store, taskRef, runner, options) {
     const role = options.dispatchRole ?? "builder";
     return inTransaction(store, () => {
@@ -1116,7 +1135,7 @@ function sealPlan(store, leaseId, args) {
                     ? ""
                     : "The filed goal, exclusions, touches, and acceptance criteria are reproduced exactly.\n"
                 : `It AMENDS the filed contract (${oneLine(describeContractChanges(contractChanges).join("; "), 300)})${amendment === null ? "" : ` — because: ${oneLine(amendment, 200)}`}\n`) +
-            (autoApproved ? "Approved under the signed operating mode. The next build may proceed with the original terms and required quality checks." : "Review, edit, and approve the scope — nothing builds until you do."),
+            (autoApproved ? `${store.getScope(taskId)?.approvalBasis === "grant" ? "Approved because its flow runs on its own." : "Approved under the signed operating mode."} The next build may proceed with the original terms and required quality checks.` : "Review, edit, and approve the scope — nothing builds until you do."),
     }, now);
     return { ok: true, changes: contractChanges.length, amendment };
 }

package/dist/cli-help.d.ts

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

package/dist/cli-help.js

@@ -6,7 +6,10 @@ import { DEFAULT_MAX_DEPTH } from "./scan.js";
 export const HELP = `toolroll — a control plane for unattended coding agents
 
 Usage
-  toolroll [path...]        report what is in flight
+  toolroll                  in a repository: start Toolroll for it, or open the one already running
+                                   (under an agent or with --json: only says what it would do)
+  toolroll scan [path...]   report what is in flight (also bare \`toolroll\` outside a repository)
+  toolroll [path...]        the same report for the paths given
   toolroll pulls            report what is waiting on a person
   toolroll graph            report which work graph is already here
   toolroll repos            list connected repositories, and how to adjust
@@ -63,6 +66,7 @@ and any queue command + --help prints it too
                                (--editor vscode with --runner: file links
                                open in VS Code on the device you browse from)
   toolroll watch / daemon install   advanced: run only the builder
+  toolroll doctor           check that Toolroll's service holds no key a build could read
   toolroll reconcile        recover what the last stretch left behind
 
 With nothing connected it reports everything it can find below the working

package/dist/cli.d.ts

@@ -11,6 +11,7 @@
  * should not have to parse a column layout.
  */
 import { previewGithubRepo, cloneGithubRepo } from "./onboard.js";
+import { type QuickStartSeams } from "./quick-start.js";
 import { type SessionCliOptions } from "./session-cli.js";
 import { type TeamCliOptions } from "./team-cli.js";
 import { type RemoteExecOptions } from "./remote-exec.js";
@@ -69,6 +70,8 @@ export type MainOptions = {
     };
     update?: UpdateCliDeps;
     release?: ReleaseCliDeps;
+    /** Tests: bare `toolroll` in a repository (quick-start.ts) — its repository, agent check, proofs and actions. */
+    quickStart?: Partial<QuickStartSeams>;
 };
 /**
  * Strip `-o <file>` / `--output <file>` before dispatch. The flag belongs to

package/dist/cli.js

@@ -24,6 +24,7 @@ import { applyClaudeCodeInstall, applyInstall, contextBlock, defaultClaudeCodeSk
 import { GUIDES, guideNamed } from "./guides.js";
 import { parseGithubRepo, previewGithubRepo, cloneGithubRepo, isLargeRepo } from "./onboard.js";
 import { run as execRun } from "./exec.js";
+import { isBareInvocation, runQuickStart } from "./quick-start.js";
 import { COMMAND_GUIDE, SURFACE_NOTES, SURFACE_SCHEMA_VERSION } from "./surface.js";
 import { runSessionCommand, SESSION_CLI_ACTIONS } from "./session-cli.js";
 import { maybeRunTeamCommand, TEAM_CLI_ACTIONS } from "./team-cli.js";
@@ -111,7 +112,7 @@ export function parseArgs(argv) {
  * exact sets instead of regex-reading source. "" is the no-verb report,
  * which answers as `scan`. */
 export const TOP_LEVEL_COMMANDS = [
-    "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github",
+    "", "scan", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github",
     "link", "unlink", "update", "release", "contract", "skills list", "skills get", "skills install", "demo",
     ...SESSION_CLI_ACTIONS.map(action => `session ${action}`),
     ...TEAM_CLI_ACTIONS,
@@ -172,7 +173,7 @@ export const OPERATE_COMMANDS = new Set([
     "reconcile",
     "run",
     "flows",
-    "config", "chat", "proposals", "mode", "chat-approval", "people", "tokens", "keys",
+    "config", "chat", "proposals", "mode", "chat-approval", "people", "tokens", "keys", "agents",
     "setup",
     "verify",
     "intake",
@@ -313,6 +314,9 @@ async function dispatch(argv, write, mainOptions) {
     // Command families below load when their command runs, so one command never pays for the others.
     if (argv[0] === 'health')
         return (await import("./health-cli.js")).runHealthCommand(argv.slice(1), write, mainOptions.team ?? mainOptions.remote);
+    // This computer's own service, read here and never on a central server.
+    if (argv[0] === 'doctor')
+        return (await import("./doctor.js")).runDoctorCommand(argv.slice(1), write);
     const central = await maybeRunRemoteCommand(argv, mainOptions.remote ?? mainOptions.team);
     if (typeof central === "number")
         return central;
@@ -360,6 +364,24 @@ async function dispatch(argv, write, mainOptions) {
     if (first !== undefined && OPERATE_COMMANDS.has(first)) {
         return runOperate(first, rest, write, mainOptions.operate ?? {});
     }
+    // Cockpit B1: the scan by name, and bare `toolroll` in a repository starting (or attaching to) its console.
+    if (first === "scan")
+        argv = rest;
+    else if (isBareInvocation(argv)) {
+        const databaseFile = mainOptions.operate?.databaseFile ?? databasePath(process.env, homedir());
+        const started = await runQuickStart(argv, write, {
+            databaseFile, cwd: process.cwd(), env: process.env, terminal: process.stdout.isTTY === true,
+            build: (await import("./monitoring.js")).packageVersion(),
+            findRepo: async (cwd) => { const top = await execRun("git", ["rev-parse", "--show-toplevel"], { cwd, timeoutMs: 10_000 }); return top.code === 0 ? top.stdout.trim() : null; },
+            enrolled: async (repo) => { const loaded = await loadRepos(registryBeside(databaseFile)); return !("error" in loaded) && loaded.repos.includes(repo); },
+            admit: repo => runReposCommand(["add", repo], write, mainOptions.onboard),
+            startUp: () => runOperate("up", [], write, mainOptions.operate ?? {}),
+            openBrowser: async (url) => { (await import("./operate.js")).openBrowser(url); },
+            ...mainOptions.quickStart,
+        });
+        if (started !== null)
+            return started;
+    }
     const parsed = parseArgs(argv);
     if ("error" in parsed) {
         write(parsed.error);

package/dist/coding-ui.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { html, joinHtml, postForm } from './html.js';
+import { html, joinHtml, passwordlessRendering, postForm, reauth } from './html.js';
 function linkedText(text) {
     const pattern = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|\x60([^\x60\n]+)\x60|\*\*([^*\n]+)\*\*|(https?:\/\/[^\s<>]+)/g;
     let end = 0;
@@ -42,7 +42,7 @@ function itemHtml(item) {
 }
 function requestHtml(request, session) {
     const questions = request.kind === 'questions';
-    const body = questions ? request.questions.map((q, index) => html `<label>${q.question}<input type="text" name="question:${q.id}"${q.options.length ? html ` list="coding-options-${request.id}-${index}"` : ''} required autocomplete="off">${q.options.length ? html `<datalist id="coding-options-${request.id}-${index}">${q.options.map(o => html `<option value="${o.label}">${o.description}</option>`)}</datalist>` : ''}</label>`) : html `<pre class="coding-permission-detail">${request.detail}</pre><label>Password to approve this request<input type="password" name="password" autocomplete="current-password" required></label>`;
+    const body = questions ? request.questions.map((q, index) => html `<label>${q.question}<input type="text" name="question:${q.id}"${q.options.length ? html ` list="coding-options-${request.id}-${index}"` : ''} required autocomplete="off">${q.options.length ? html `<datalist id="coding-options-${request.id}-${index}">${q.options.map(o => html `<option value="${o.label}">${o.description}</option>`)}</datalist>` : ''}</label>`) : html `<pre class="coding-permission-detail">${request.detail}</pre>${reauth(html `<label>Password to approve this request<input type="password" name="password" autocomplete="current-password" required></label>`)}`;
     return html `<section class="coding-request" data-coding-request="${request.id}"><h3>${request.title || (questions ? 'Your answer' : 'Allow extra access?')}</h3>${postForm(`${sessionUrl(session)}/answer`, html `${body}<div class="coding-actions"><button type="submit" name="decision" value="accept">${questions ? 'Send answer' : 'Approve access'}</button><button type="submit" name="decision" value="decline" formnovalidate class="coding-secondary">${questions ? 'Cancel question' : 'Decline'}</button></div>`, { attrs: { 'data-coding-form': 'answer' }, hidden: { requestId: request.id } })}</section>`;
 }
 function controlsHtml(session) {
@@ -69,7 +69,7 @@ export function codingWorkspaceHtml(input) {
     let main;
     if (!selected) {
         const options = input.projects.map(p => html `<option value="${p.path}"${selectedRepo === p.path ? html ` selected` : ''}>${p.name}</option>`);
-        main = html `<header class="coding-header"><h1>Build with Codex</h1></header>${warning}${input.projects.length ? postForm('/code/start', html `<label>Project<select name="repo" required>${options}</select></label><label>What would you like to change?<textarea name="prompt" rows="5" required maxlength="24000" placeholder="Describe the result you want…">${input.draft ?? ''}</textarea></label><details class="coding-options"><summary>Session options</summary><label>Title <span class="coding-meta">Optional</span><input name="title" maxlength="160" autocomplete="off"></label><label>Model <span class="coding-meta">Optional; uses the installed default</span><input name="model" maxlength="120" placeholder="Installed default" autocomplete="off"></label></details><p class="coding-terms">Codex uses this installation’s login and edits a separate copy of this project. It can run commands and read files outside the project. Connected tools (MCP servers) keep their own access to this computer and connected services. Additional command and file access requires your approval.</p><label>Password to start<input type="password" name="password" autocomplete="current-password" required></label><button type="submit"${input.available ? '' : html ` disabled`}>Start coding</button>`, { attrs: { 'data-coding-form': 'start', class: 'coding-start' }, hidden: { requestId: randomUUID() } }) : html `<div class="coding-empty"><p>Add a project to start coding.</p><a class="coding-link-button" href="/projects">Open projects</a></div>`}`;
+        main = html `<header class="coding-header"><h1>Build with Codex</h1></header>${warning}${input.projects.length ? postForm('/code/start', html `<label>Project<select name="repo" required>${options}</select></label><label>What would you like to change?<textarea name="prompt" rows="5" required maxlength="24000" placeholder="Describe the result you want…">${input.draft ?? ''}</textarea></label><details class="coding-options"><summary>Session options</summary><label>Title <span class="coding-meta">Optional</span><input name="title" maxlength="160" autocomplete="off"></label><label>Model <span class="coding-meta">Optional; uses the installed default</span><input name="model" maxlength="120" placeholder="Installed default" autocomplete="off"></label></details><p class="coding-terms">Codex uses this installation’s login and edits a separate copy of this project. It can run commands and read files outside the project. Connected tools (MCP servers) keep their own access to this computer and connected services. Additional command and file access requires your approval.</p>${reauth(html `<label>Password to start<input type="password" name="password" autocomplete="current-password" required></label>`)}<button type="submit"${input.available ? '' : html ` disabled`}>Start coding</button>`, { attrs: { 'data-coding-form': 'start', class: 'coding-start' }, hidden: { requestId: randomUUID() } }) : html `<div class="coding-empty"><p>Add a project to start coding.</p><a class="coding-link-button" href="/projects">Open projects</a></div>`}`;
     }
     else {
         const s = selected.session;
@@ -94,6 +94,8 @@ export const CODING_CSS = `
 @media(prefers-reduced-motion:reduce){.coding-workspace *{scroll-behavior:auto!important}}
 `;
 export function codingWorkspaceScript() {
+    // Passwordless: the request form the script builds leaves its password field out (the server proves the session).
+    const approvePassword = passwordlessRendering() ? "" : '<label>Password to approve this request<input type="password" name="password" autocomplete="current-password" required></label>';
     return String.raw `(() => {
   const root = document.querySelector('.coding-workspace');
   if (!root || root.dataset.codingMounted) return;
@@ -196,7 +198,7 @@ export function codingWorkspaceScript() {
   };
   const requestHtml = request => {
     const questions = request.kind === 'questions';
-    const body = questions ? request.questions.map((q,index) => '<label>' + e(q.question) + '<input type="text" name="question:' + e(q.id) + '"' + (q.options.length ? ' list="coding-options-' + e(request.id) + '-' + index + '"' : '') + ' required autocomplete="off">' + (q.options.length ? '<datalist id="coding-options-' + e(request.id) + '-' + index + '">' + q.options.map(o => '<option value="' + e(o.label) + '">' + e(o.description) + '</option>').join('') + '</datalist>' : '') + '</label>').join('') : '<pre class="coding-permission-detail">' + e(request.detail) + '</pre><label>Password to approve this request<input type="password" name="password" autocomplete="current-password" required></label>';
+    const body = questions ? request.questions.map((q,index) => '<label>' + e(q.question) + '<input type="text" name="question:' + e(q.id) + '"' + (q.options.length ? ' list="coding-options-' + e(request.id) + '-' + index + '"' : '') + ' required autocomplete="off">' + (q.options.length ? '<datalist id="coding-options-' + e(request.id) + '-' + index + '">' + q.options.map(o => '<option value="' + e(o.label) + '">' + e(o.description) + '</option>').join('') + '</datalist>' : '') + '</label>').join('') : '<pre class="coding-permission-detail">' + e(request.detail) + '</pre>' + ${JSON.stringify(approvePassword)};
     return '<section class="coding-request" data-coding-request="' + e(request.id) + '"><h3>' + e(request.title || (questions ? 'Your answer' : 'Allow extra access?')) + '</h3><form method="post" action="' + base + '/answer" data-coding-form="answer">' + h({csrf,requestId:request.id}) + body + '<div class="coding-actions"><button type="submit" name="decision" value="accept">' + (questions ? 'Send answer' : 'Approve access') + '</button><button type="submit" name="decision" value="decline" formnovalidate class="coding-secondary">' + (questions ? 'Cancel question' : 'Decline') + '</button></div></form></section>';
   };
   const render = snapshot => {