toolroll 0.9.63 → 0.9.65

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/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, () => {

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 doctor           check that Toolroll's service holds no key a build could read\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 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

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",
@@ -363,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 => {

package/dist/console-instance.d.ts

@@ -0,0 +1,124 @@
+import { type Socket } from "node:net";
+import type { Store } from "./store.js";
+export declare const CONSOLE_INSTANCE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS console_instance (\n  id         INTEGER PRIMARY KEY CHECK (id = 1),\n  secret     TEXT NOT NULL,\n  pid        INTEGER NOT NULL,\n  port       INTEGER NOT NULL,\n  build      TEXT NOT NULL,\n  socket     TEXT NOT NULL,\n  started_at TEXT NOT NULL\n);";
+/**
+ * The socket's own owner-only directory beside the database's REAL file (a symlinked database resolves to the one
+ * folder every spelling shares). Each console start binds a socket of its own, under a fresh random name recorded
+ * with its secret: no console ever needs to remove — or can remove — another console's socket.
+ */
+/** Toolroll's own name, so it never collides with a project or worktree that happens to sit beside the database. */
+export declare const INSTANCE_DIR = ".toolroll-run";
+export declare function instanceRunDir(databaseFile: string): string;
+/** The console's own answer to a challenge over HTTP (an edge route, no sign-in: it reveals nothing). */
+export declare const INSTANCE_PATH = "/__instance";
+export type InstanceRecord = {
+    secret: string;
+    pid: number;
+    port: number;
+    build: string;
+    socket: string;
+    startedAt: string;
+};
+export type HelloFacts = {
+    pid: number;
+    build: string;
+    database: string;
+    port: number;
+};
+/** The record as stored: none, one this build can't read (never taken for none), or the record. */
+export declare function readInstanceState(store: Store): {
+    state: "none";
+} | {
+    state: "invalid";
+} | {
+    state: "ok";
+    record: InstanceRecord;
+};
+export declare function readInstance(store: Store): InstanceRecord | null;
+/** A stopping console forgets itself — only its own record, never a newer start's. */
+export declare function clearInstance(store: Store, secret: string): void;
+export declare const socketProof: (secret: string, challenge: string) => string;
+export declare const httpProof: (secret: string, challenge: string, address: string, port: number) => string;
+/** The HTTP answer: bound to the address and port THIS connection was received on, as the console saw them. */
+export declare function instanceHttpAnswer(secret: string, challenge: string | null, local: {
+    address: string | undefined;
+    port: number | undefined;
+}): {
+    status: number;
+    body: string;
+};
+/**
+ * The run directory must be private to this user: a real, canonical directory owned by this user with no access for
+ * anyone else (0700), inside a canonical directory owned by this user that nobody else can write. Checked before any
+ * change is made, and before connecting or binding.
+ */
+export declare function runDirProblem(dir: string, uid?: number, mustExist?: boolean): string | null;
+/** A socket path that binds exactly (no truncation), named as a console names its own. */
+export declare function socketPathProblem(path: string): string | null;
+/**
+ * `up`: the run directory, made 0700 if it isn't there. An existing one is used only as it is (never chmodded): one
+ * that isn't private to this user is refused. Everything is checked before anything is created.
+ */
+export declare function prepareRunDir(dir: string, uid?: number): string | null;
+/** Ask a socket one question; null when nobody is listening (or it said nothing usable in time). */
+export declare function askSocket(socketPath: string, request: object, timeoutMs?: number, connect?: (path: string) => Socket): Promise<{
+    answer: Record<string, unknown>;
+} | {
+    none: "no-listener" | "no-answer";
+}>;
+/**
+ * The console's discovery socket: one line in, one line out. `hello` (with a challenge) answers the public facts and
+ * the socket proof; every other verb is refused. It reads nothing else and changes nothing. Bound under a fresh name
+ * no other process has, so it never clears or replaces anything; its own listener removes it on close.
+ */
+export declare function openInstanceSocket(databaseFile: string, facts: HelloFacts, secret: () => string | null): Promise<{
+    ok: true;
+    name: string;
+    close: () => void;
+} | {
+    ok: false;
+    problem: string;
+}>;
+/**
+ * A record's console: "live" (its socket answers a fresh challenge with the record's secret and pid), "gone" (nobody
+ * is listening on its socket, or the socket isn't there), or "unknown" (anything else: slow, malformed, a wrong proof).
+ * Only "gone" lets another start take the record.
+ */
+export declare function recordLiveness(databaseFile: string, record: InstanceRecord, ask?: typeof askSocket): Promise<"live" | "gone" | "unknown">;
+/**
+ * `up` claims the record for its socket — unless a live console already holds it (another start on the same
+ * database, by any spelling of its path). The write is a compare-and-set on the record it checked: two starts racing
+ * can't both win. Null: not claimed (this console runs, but `toolroll` won't attach to it).
+ */
+export declare function claimInstance(store: Store, databaseFile: string, facts: {
+    pid: number;
+    port: number;
+    build: string;
+    socket: string;
+}, now: Date, liveness?: (record: InstanceRecord) => Promise<"live" | "gone" | "unknown">): Promise<string | null>;
+export type AttachProof = {
+    ok: true;
+    url: string;
+    port: number;
+    pid: number;
+    build: string;
+} | {
+    ok: false;
+    state: "none";
+    message: string;
+} | {
+    ok: false;
+    state: "refused";
+    message: string;
+};
+export type AttachSeams = {
+    ask?: typeof askSocket;
+    fetch?: typeof fetch;
+    challenge?: () => string;
+};
+/**
+ * Prove the console this installation's database names is live, on both channels, before anything is shown or
+ * opened. "none": no console runs (no record, or nobody on the socket); "refused": something answers that can't
+ * prove it is the console (or a different build) — the person restarts it.
+ */
+export declare function proveLiveConsole(databaseFile: string, store: Store, build: string, seams?: AttachSeams): Promise<AttachProof>;