toolroll 0.9.6 → 0.9.8

package/dist/cli.js

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

package/dist/demo-chat.js

@@ -3,6 +3,7 @@
  * rendered as plain server HTML with native forms. One small script keeps a
  * running build's progress live; without it the page still works by reload.
  */
+import { START_COMMAND } from "./first-run.js";
 import { headlineOf } from "./task-status.js";
 const SUGGESTIONS = ["Fix the flaky refund test", "Rewrite the empty Payouts page", "Put the new invoice view behind a flag"];
 const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -100,7 +101,9 @@ export function demoThreadHtml(exchanges, csrf, resultOf) {
         if (exchange.state === "ready" || exchange.state === "complete" || exchange.state === "sent-back")
             parts.push(resultCard(exchange, csrf, resultOf(exchange)));
         if (exchange.state === "complete") {
-            parts.push(`<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`);
+            parts.push(`<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, `<section class="card demo-handoff" data-demo-handoff aria-label="Your own project"><h2>Now try it on your own project</h2>` +
+                `<p>In your repository's folder, run:</p><pre class="demo-command"><code>${esc(START_COMMAND)}</code></pre>` +
+                `<p class="meta">It opens in your browser, already signed in.</p></section>`);
         }
         return `<article class="demo-turn" id="demo-${exchange.id}">${parts.join("")}</article>`;
     }).join("");

package/dist/dispatch.js

@@ -12,6 +12,8 @@ import { approvalOf } from "./scope.js";
 import { plannerSourceProblemOf } from "./planner-source.js";
 import { authPauseOf, authWaitOf, providerName, signInReason } from "./provider-auth.js";
 import { REVIEW_TOKENS, resultStatusOf, reviewFactsOf } from "./workspace-ui.js";
+import { replacedWords } from "./task-status.js";
+import { buildReviewOf } from "./review-switch.js";
 import { BUILT_IN, parseCapabilityKey } from "./store.js";
 export const DEFAULT_MAX_OPEN_DECISIONS = 5;
 /**
@@ -186,7 +188,7 @@ export function diagnoseTaskDispatch(store, taskId, now) {
         const reviewFacts = reviewFactsOf(retry, runner => {
             const reviewer = store.getRunner(runner)?.runner;
             return reviewer !== undefined && isAlive(reviewer, now);
-        });
+        }, result !== undefined && buildReviewOf(store, result.id)?.state === "pending");
         // A no-change conclusion owes no proof beyond its handoff and sealed
         // diff (the task page's own "attested floor"); with both on record it
         // is complete, not verification-needed.
@@ -210,8 +212,12 @@ export function diagnoseTaskDispatch(store, taskId, now) {
             ? `${status.detail} Its independent review succeeded on attempt ${review.attempt} of ${review.cap}.`
             : status.detail, { action: "open-result", review });
     }
-    if (task.state === "cancelled")
-        return answer("cancelled", "terminal", "Cancelled", "Nothing else will run for this task.");
+    if (task.state === "cancelled") {
+        // Replaced, never "Cancelled": a successor carries the work on.
+        const successor = store.replacementOf(taskId);
+        return successor === null ? answer("cancelled", "terminal", "Cancelled", "Nothing else will run for this task.")
+            : answer("cancelled", "terminal", replacedWords(successor), `${replacedWords(successor)}. Nothing else will run for this task.`);
+    }
     if (task.state === "failed")
         return answer("failed", "terminal", "Needs a retry", "The last attempt stopped; review its incident, then retry it.", { action: "retry-task" });
     if (store.hasLiveClaim(ref.id, now))

package/dist/dispose.d.ts

@@ -73,13 +73,22 @@ export type Disposition = {
     kind: "stopped";
     stopRun: number;
     requeued: boolean;
+}
+/** The service stopped or restarted while the attempt ran (no one stopped
+ * the task): its work is preserved, the run ends as interrupted, and the
+ * task is back in the queue — no strike, no backoff — so the next builder
+ * pass resumes it from the kept work. */
+ | {
+    kind: "handed-back";
+    requeued: boolean;
 } | {
     kind: "invariant";
     reason: string;
 };
-/** Compatibility for historical integrations: finished work is handed to the
- * lead. No model review is requested and no signed history is rewritten. */
-export declare function maybeRequestAutoReview(_store: Store, _repo: string, _runId: number, _committed: boolean, _noChange: boolean, _now: Date): void;
+/** A committed build whose approved check passed gets the project's one
+ * automatic review when its review switch is on (build-review.ts). No-change
+ * results and failed checks go straight to the person, as before. */
+export declare function maybeRequestAutoReview(store: Store, repo: string, runId: number, committed: boolean, noChange: boolean, now: Date, root?: string): void;
 export declare function disposeBuildOutcome(context: DisposeContext, result: BuildResult): Disposition;
 /**
  * The stale-approval HOLD, shared by the post-build disposition above and

package/dist/dispose.js

@@ -14,10 +14,12 @@ import { originalTaskBase, focusedTestCommandSupported } from "./observations.js
  * inlined before.
  */
 import { createHash } from "node:crypto";
-import { completeFenced, finalizeFailureFenced, finalizeMalformedFenced, finalizeParkFenced, interruptIfStopped, release, } from "./claim.js";
+import { completeFenced, finalizeFailureFenced, finalizeHandBackFenced, finalizeMalformedFenced, finalizeParkFenced, interruptIfStopped, release, } from "./claim.js";
 import { bodyHashOf, publicationBody } from "./publish.js";
 import { modeTermsFromJson } from "./modes.js";
-import { readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
+import { evidenceRoot, readVerifiedArtifact, writeEvidenceFile } from "./evidence.js";
+import { queueBuildReview } from "./build-review.js";
+import { homedir } from "node:os";
 import {} from "./proof.js";
 import { verificationEvidence, failedVerificationEvidence } from "./verification-evidence.js";
 import { classifyGateFailure, describeGateFailure, gateFailureSummary } from "./gate-failure.js";
@@ -55,9 +57,14 @@ const STANDALONE_BROKE_REASONS = new Set([
     "timeout",
     "git",
 ]);
-/** Compatibility for historical integrations: finished work is handed to the
- * lead. No model review is requested and no signed history is rewritten. */
-export function maybeRequestAutoReview(_store, _repo, _runId, _committed, _noChange, _now) { }
+/** A committed build whose approved check passed gets the project's one
+ * automatic review when its review switch is on (build-review.ts). No-change
+ * results and failed checks go straight to the person, as before. */
+export function maybeRequestAutoReview(store, repo, runId, committed, noChange, now, root = evidenceRoot(homedir())) {
+    if (!committed || noChange)
+        return;
+    queueBuildReview(store, repo, runId, root, now);
+}
 export function disposeBuildOutcome(context, result) {
     // Stop and every terminal side effect compete under the same SQLite
     // write lock. A separate preliminary transaction leaves a completion gap.
@@ -238,6 +245,7 @@ function disposeBuildOutcomeLocked(context, result) {
             // proves the credential, clearing any quota stamp.
             store.resetStrikes(taskRef);
             store.clearQuota(runner, provider, model ?? "");
+            maybeRequestAutoReview(store, repo, runId, result.committed, result.noChange === true, clock(), context.evidenceRoot);
             return { kind: "built", committed: result.committed, noChange: result.noChange === true };
         }
         store.transact(() => {
@@ -338,6 +346,12 @@ function disposeBuildOutcomeLocked(context, result) {
         });
         return { kind: "malformed", sealed: sealed.ok };
     }
+    // A stop no operator asked for is the SERVICE stopping (the fence above
+    // already settled every task stop): hand the attempt back, never strike it.
+    if (result.reason === "stopped" && policy === "tick" && leaseId !== undefined && store.getRun(runId)?.role === "builder") {
+        const handed = finalizeHandBackFenced(store, { leaseId, runId, taskId, message: result.message, now: clock() });
+        return { kind: "handed-back", requeued: handed.requeued };
+    }
     if (TICK_FAILURE_REASONS.has(result.reason)) {
         // One fenced transaction decides what the failure means. The
         // classification trusts only what the machine itself observed.

package/dist/exec.d.ts

@@ -113,6 +113,11 @@ export type RunOptions = ProcessTreeObserver & {
     /** Fires once the child exists, with its pid (the process-group id when
      * processGroup is set) — the slot ledger records it (v14 finding 26). */
     onSpawn?: (pid: number) => void;
+    /** Fires instead of onSpawn when a spawn that beforeSpawn admitted made no
+     * process at all (the OS call threw — ENOENT, EAGAIN — returned no pid, or
+     * its OS object could not be made), so its reserved witness can be settled
+     * as never started in the same step. Never fires once a child exists. */
+    onSpawnFailed?: () => void;
     /** Fires before any target spawn, so a crash cannot lose its OS object. */
     onContainer?: (info: {
         backend: ContainmentBackendId;

package/dist/exec.js

@@ -84,9 +84,24 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         throw new ContainmentRefusal(effective.refusal);
     if (bag.beforeSpawn?.() === false)
         throw new Error("the attempt stopped before this process could spawn");
-    const made = effective === null ? { container: null } : createContainer(effective, label);
-    if ("refused" in made)
+    // From here a witness may be reserved: every road that makes no process
+    // says so through onSpawnFailed before it returns or throws.
+    const neverStarted = () => { try {
+        bag.onSpawnFailed?.();
+    }
+    catch { /* the reservation stays unproven */ } };
+    let made;
+    try {
+        made = effective === null ? { container: null } : createContainer(effective, label);
+    }
+    catch (error) {
+        neverStarted();
+        throw error;
+    }
+    if ("refused" in made) {
+        neverStarted();
         throw new ContainmentRefusal(made.refused);
+    }
     const container = made.container;
     try {
         if (container !== null)
@@ -94,6 +109,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     }
     catch (error) {
         container?.release();
+        neverStarted();
         throw error;
     }
     let launch;
@@ -102,6 +118,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     }
     catch (error) {
         container?.release();
+        neverStarted();
         throw error;
     }
     let child;
@@ -123,6 +140,7 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         }
         catch { }
         container?.release();
+        neverStarted();
         throw error;
     }
     if (container !== null) {
@@ -143,6 +161,12 @@ function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
         if (child.pid !== undefined) {
             bag.onSpawn?.(child.pid);
         }
+        else if (container === null) {
+            // No pid: the OS refused the spawn (ENOENT, EACCES) and only an
+            // 'error' event follows. A contained spawn settles once its object is
+            // proven empty, and its transport's return finishes the witness.
+            neverStarted();
+        }
     }
     catch (error) {
         throw new SpawnCustodyFailure(child, error);
@@ -201,7 +225,7 @@ function containmentOf(container, empty, attachFailure) {
 }
 /** The streaming transports' spawn: contained when the spawn is a provider (process group), plain otherwise. */
 function spawnStream(file, args, options, stdio, childEnv) {
-    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
+    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
 }
 /** The refusal-before-spawn shape shared by every containable transport. */
 function refusedResult(error) {
@@ -506,6 +530,7 @@ export function run(file, args, options = {}) {
             ...(cwd === undefined ? {} : { cwd }),
             ...(childEnv === undefined ? {} : { childEnv }),
             ...(options.onSpawn === undefined ? {} : { onSpawn: options.onSpawn }),
+            ...(options.onSpawnFailed === undefined ? {} : { onSpawnFailed: options.onSpawnFailed }),
             ...(options.owner === undefined ? {} : { owner: options.owner }),
             ...(options.beforeSpawn === undefined ? {} : { beforeSpawn: options.beforeSpawn }),
             ...(options.onStdout === undefined ? {} : { onStdout: options.onStdout }),
@@ -553,7 +578,7 @@ function runBufferedGroup(file, args, bag) {
         let container = null;
         let attached;
         try {
-            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
+            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
             child = spawned.child;
             container = spawned.container;
             attached = spawned.attached;
@@ -1578,6 +1603,7 @@ export function startClaudeHeldSession(file, args, options) {
             }, options.owner ?? "held", {
                 beforeSpawn: options.beforeSpawn,
                 onSpawn: options.onSpawn,
+                onSpawnFailed: options.onSpawnFailed,
                 onContainer: options.onContainer,
                 onContainerEmpty: options.onContainerEmpty,
                 onUnknown: options.onUnknown,

package/dist/export.js

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

package/dist/first-run.d.ts

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

package/dist/first-run.js

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

package/dist/flow-gallery-ui.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The flow gallery in the console (Flows → New and Settings → Flows): cards grouped by what they're for, each with
+ * its promise, a small drawing of its zones, what it needs and "Use this". A template's page asks only what it
+ * needs, previews in plain words what it will do and never do, and creates it — the same answers it previewed.
+ */
+import { type GalleryAnswers, type GalleryPreview, type GalleryTemplate } from "./flow-gallery.js";
+import type { FlowDefinition } from "./flows.js";
+export declare const GALLERY_CSS: string;
+/** A small drawing of a flow's zones where they sit on its canvas, with its paths; a person's decisions stand out. */
+export declare function zonesDiagram(definition: FlowDefinition, label: string): string;
+/** The gallery: every template, grouped, each with one "Use this". `repo` carries a chosen project to the template's page. */
+export declare function galleryHtml(input: {
+    repo: string | null;
+    canUse: boolean;
+}): string;
+/** A template's page: its questions, then what it will do and never do, then Create. */
+export declare function galleryUseHtml(input: {
+    template: GalleryTemplate;
+    projects: readonly {
+        path: string;
+        name: string;
+    }[];
+    repo: string;
+    answers: GalleryAnswers;
+    name: string;
+    preview: GalleryPreview | null;
+    problem: string | null;
+    csrf: string;
+    diagram: FlowDefinition | null;
+}): string;

package/dist/flow-gallery-ui.js

@@ -0,0 +1,85 @@
+/**
+ * The flow gallery in the console (Flows → New and Settings → Flows): cards grouped by what they're for, each with
+ * its promise, a small drawing of its zones, what it needs and "Use this". A template's page asks only what it
+ * needs, previews in plain words what it will do and never do, and creates it — the same answers it previewed.
+ */
+import { BLANK, GALLERY, GALLERY_GROUPS, galleryDiagram, OUTDATED_COMMANDS } from "./flow-gallery.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const GALLERY_CSS = `.gallery{max-width:1120px;min-width:0}.gallery h2{margin:28px 0 10px;font-size:.9375rem}.gallery h2:first-of-type{margin-top:8px}` +
+    `.gallery-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:12px}` +
+    `.gallery-card{display:flex;flex-direction:column;gap:8px;padding:16px;border:1px solid var(--so-line);border-radius:10px;background:var(--so-paper);min-width:0}` +
+    `.gallery-card h3{margin:0;font-size:.9375rem}.gallery-card p{margin:0;overflow-wrap:anywhere}.gallery-card .gallery-promise{line-height:1.5;flex:1}` +
+    `.gallery-zones{display:block;width:100%;height:56px;border-radius:8px;background:var(--so-raised)}.gallery-zones rect{fill:var(--so-paper);stroke:var(--so-input-line);stroke-width:1.5}` +
+    `.gallery-zones rect[data-person="true"]{fill:var(--so-signal-soft,var(--so-raised));stroke:var(--so-ink)}.gallery-zones line{stroke:var(--so-input-line);stroke-width:1.5}` +
+    `.gallery-needs{display:flex;flex-wrap:wrap;gap:4px;list-style:none;padding:0;margin:0}.gallery-needs li{font-size:11.5px;font-weight:500;line-height:18px;padding:1px 6px;border-radius:5px;background:var(--so-neutral-soft,var(--so-raised));color:var(--so-neutral-ink,var(--so-muted))}` +
+    // An outline action in a list (the Quiet List Rule), over the workspace's ink default for .button-link.
+    `.gallery .gallery-card a.button-link{align-self:flex-start;min-height:36px;background:var(--so-paper);color:var(--so-ink);border:1px solid var(--so-input-line)}` +
+    `.gallery-blank{margin-top:20px}` +
+    `.gallery-use{max-width:720px;min-width:0}.gallery-use .gallery-zones{height:88px;margin:4px 0 12px}.gallery-use form{display:grid;gap:12px;margin:0}.gallery-use label{display:grid;gap:4px;font-weight:500}` +
+    `.gallery-use label small{font-weight:400;color:var(--so-muted)}` +
+    `.gallery-use input:not([type=hidden]),.gallery-use select{box-sizing:border-box;width:100%;max-width:100%;min-height:32px;padding:0 10px;border:1px solid var(--so-input-line);border-radius:8px;background:var(--so-paper);color:var(--so-ink);font:inherit}` +
+    `.gallery-preview{display:grid;gap:8px;padding:16px;border:1px solid var(--so-line);border-radius:10px;background:var(--so-paper);min-width:0}.gallery-preview h2{margin:0;font-size:.9375rem}` +
+    `.gallery-preview ul{margin:0;padding-left:18px;line-height:1.55}.gallery-preview p{margin:0;overflow-wrap:anywhere}.gallery-preview .gallery-never{font-weight:600}` +
+    `.gallery-preview details ol{margin:6px 0 0;padding-left:20px;white-space:pre-line;font-size:.875rem;line-height:1.5;color:var(--so-muted)}.gallery-preview details li{margin:0 0 6px;overflow-wrap:anywhere}` +
+    `.gallery-preview summary{cursor:pointer;min-height:36px;display:flex;align-items:center;font-weight:500}` +
+    `.gallery-actions{display:flex;flex-wrap:wrap;gap:8px;margin:0}.gallery-actions button{min-height:36px;white-space:nowrap}` +
+    `.gallery-use .gallery-actions button[value=create]{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary);font-weight:600}.gallery-heading{margin:36px 0 0;font-size:1.05rem}` +
+    `@media(max-width:760px){.gallery-grid{grid-template-columns:minmax(0,1fr)}.gallery .gallery-card a.button-link{min-height:44px;align-self:stretch;justify-content:center}` +
+    `.gallery-use input:not([type=hidden]),.gallery-use select{font-size:16px;min-height:44px}.gallery-actions button{flex:1 1 auto;min-height:44px}}`;
+/** A small drawing of a flow's zones where they sit on its canvas, with its paths; a person's decisions stand out. */
+export function zonesDiagram(definition, label) {
+    const zones = definition.stages.map(one => one.zone);
+    const minX = Math.min(...zones.map(one => one.x)), minY = Math.min(...zones.map(one => one.y));
+    const maxX = Math.max(...zones.map(one => one.x + one.w)), maxY = Math.max(...zones.map(one => one.y + one.h));
+    const pad = 40;
+    const box = `${minX - pad} ${minY - pad} ${maxX - minX + pad * 2} ${maxY - minY + pad * 2}`;
+    const centre = (id) => { const at = definition.stages.find(one => one.id === id)?.zone; return at === undefined ? null : { x: at.x + at.w / 2, y: at.y + at.h / 2 }; };
+    const lines = definition.stages.flatMap(stage => [stage.next, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? [])].map(to => {
+        const from = centre(stage.id), end = centre(to);
+        return from === null || end === null ? "" : `<line x1="${from.x}" y1="${from.y}" x2="${end.x}" y2="${end.y}" vector-effect="non-scaling-stroke"/>`;
+    })).join("");
+    const rects = definition.stages.map(one => `<rect x="${one.zone.x}" y="${one.zone.y}" width="${one.zone.w}" height="${one.zone.h}" rx="36" data-person="${one.kind === "approval"}" vector-effect="non-scaling-stroke"/>`).join("");
+    return `<svg class="gallery-zones" viewBox="${box}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="${e(label)}">${lines}${rects}</svg>`;
+}
+const needsList = (template) => template.needs.length === 0 ? `<ul class="gallery-needs"><li>Nothing to connect</li></ul>`
+    : `<ul class="gallery-needs" aria-label="Needs">${template.needs.map(one => `<li>${e(one)}</li>`).join("")}</ul>`;
+/** The gallery: every template, grouped, each with one "Use this". `repo` carries a chosen project to the template's page. */
+export function galleryHtml(input) {
+    const href = (id) => `/flows/new/${id}${input.repo === null ? "" : `?repo=${encodeURIComponent(input.repo)}`}`;
+    const card = (template) => {
+        const definition = galleryDiagram(template);
+        return `<article class="gallery-card" data-template="${e(template.id)}"><h3>${e(template.name)}</h3><p class="gallery-promise">${e(template.promise)}</p>` +
+            zonesDiagram(definition, `Zones: ${definition.stages.map(one => one.title).join(", ")}`) + needsList(template) +
+            (input.canUse ? `<a class="button-link" href="${e(href(template.id))}" aria-label="Use ${e(template.name)}">Use this</a>` : "") + `</article>`;
+    };
+    const groups = GALLERY_GROUPS.map(group => `<h2 id="gallery-${group.id}">${e(group.label)}</h2><div class="gallery-grid" data-group="${group.id}">${GALLERY.filter(one => one.group === group.id).map(card).join("")}</div>`).join("");
+    return `<section class="gallery">${groups}${input.canUse ? `<p class="gallery-blank meta"><a href="${e(href(BLANK.id))}">Start from a blank flow</a></p>` : `<p class="meta">An approver creates flows.</p>`}</section>`;
+}
+/** A template's page: its questions, then what it will do and never do, then Create. */
+export function galleryUseHtml(input) {
+    const { template } = input;
+    const field = (ask) => {
+        const value = input.answers[ask.key] ?? ask.default;
+        const hint = ask.hint === undefined ? "" : ` <small>${e(ask.hint)}</small>`;
+        if (ask.key === "outdated")
+            return `<label>${e(ask.label)}<select name="outdated">${Object.entries(OUTDATED_COMMANDS).map(([id, one]) => `<option value="${id}"${id === value ? " selected" : ""}>${e(one.label)}</option>`).join("")}</select></label>`;
+        return `<label>${e(ask.label)}${hint}<input name="${ask.key}" value="${e(value)}" required maxlength="${ask.key === "command" ? 500 : 100}"${ask.key === "command" ? ' spellcheck="false" autocapitalize="off"' : ""}></label>`;
+    };
+    const project = input.projects.length > 1
+        ? `<label>Project<select name="repo">${input.projects.map(one => `<option value="${e(one.path)}"${one.path === input.repo ? " selected" : ""}>${e(one.name)}</option>`).join("")}</select></label>`
+        : `<input type="hidden" name="repo" value="${e(input.repo)}">`;
+    const preview = input.preview === null ? "" : `<section class="gallery-preview" aria-labelledby="gallery-will">` +
+        `<h2 id="gallery-will">What it will do</h2><ul>${input.preview.built.does.map(one => `<li>${e(one)}</li>`).join("")}</ul>` +
+        `<p class="gallery-never">${e(input.preview.built.never)}</p>` +
+        (input.preview.startsFrom.length === 0 ? `<p class="meta">Cards start when you add them.</p>` : input.preview.startsFrom.map(one => `<p class="meta">Starts from: ${e(one)}</p>`).join("")) +
+        `<details><summary>Every step</summary><ol>${input.preview.steps.map(one => `<li>${e(one.replace(/^\d+\.\s/, ""))}</li>`).join("")}</ol></details></section>`;
+    const asks = template.asks.length > 0 || input.projects.length > 1;
+    return `<section class="gallery-use" data-gallery-template="${e(template.id)}">` +
+        (input.problem === null ? "" : `<p class="problem" role="alert">${e(input.problem)}</p>`) +
+        `<p>${e(template.promise)}</p>${input.diagram === null ? "" : zonesDiagram(input.diagram, `Zones: ${input.diagram.stages.map(one => one.title).join(", ")}`)}${needsList(template)}` +
+        `<form method="post" action="/flows/new/${e(template.id)}" data-gallery-use><input type="hidden" name="csrf" value="${e(input.csrf)}">` +
+        `<input type="hidden" name="previewed" value="${e(input.preview?.digest ?? "")}">${project}${template.asks.map(field).join("")}` +
+        `<label>Name<input name="name" value="${e(input.name)}" maxlength="80"></label>${preview}` +
+        `<p class="gallery-actions">${input.preview === null ? "" : `<button type="submit" name="intent" value="create">Create flow</button>`}${asks || input.preview === null ? `<button type="submit" name="intent" value="preview" class="secondary">${input.preview === null ? "Preview" : "Update preview"}</button>` : ""}</p>` +
+        `</form><p class="meta"><a href="/flows/new">All templates</a></p></section>`;
+}