toolroll 0.9.4 → 0.9.6

package/dist/browser-workspace.d.ts

@@ -8,6 +8,7 @@ import type { Store } from './store.js';
 import type { WorkSummaryAccess } from './work-summary.js';
 import type { StatusTone } from './workspace-ui.js';
 import type { AssignmentCard } from './assignment-ui.js';
+import type { TaskStatus } from './task-status.js';
 import type { FirstRunStep, FirstTaskSuggestion } from './first-run.js';
 export type BrowserProject = {
     name: string;
@@ -365,12 +366,6 @@ export type BrowserProjectsView = {
     };
 };
 export type BrowserResultTab = 'summary' | 'changes' | 'checks';
-export type BrowserResultChip = {
-    tone: 'success' | 'danger' | 'warning' | 'info' | 'neutral';
-    label: string;
-    icon: 'check' | 'x' | null;
-    title: string | null;
-};
 /** The shared result panel in parts. Each tab's content, the feedback
  * section and the learning card are the server's own HTML; the page script
  * binds to the same data attributes and ids (tabs, drafts, line notes). */
@@ -378,12 +373,20 @@ export type BrowserResultPanel = {
     attributes: Record<string, string>;
     heading: string;
     outcome: string;
-    verdict: {
-        chips: BrowserResultChip[];
-        by: string | null;
-    } | null;
+    /** The shared task status (task-status.ts): headline, sentence and detail rows. */
+    status: TaskStatus | null;
     reviewHistory: string | null;
     attention: string[];
+    /** Requirements only a person can confirm, in plain words, and the one
+     * Accept that records the decision (null when it is not offered here). */
+    youCheck: {
+        lines: string[];
+        accept: {
+            action: string;
+            run: number;
+            returnTo: string;
+        } | null;
+    } | null;
     /** Storage limits on saved output (shortened logs or diffs): shown on request. */
     limits: string[];
     tabs: {

package/dist/chat-acceptance.js

@@ -6,7 +6,7 @@ export function acceptanceStatus(proof, accepted) {
     if (accepted)
         return manualReviewOnly(proof) ? "Accepted by a person" : "Accepted with an exception";
     if (manualReviewOnly(proof))
-        return "Ready to inspect";
+        return "You check the remaining requirements";
     return proof === null ? "No checks recorded" : ({ verified: "Checks passed", attested: "Checks reported by the agent", short: "Some required material is missing", refuted: "Saved result conflicts with the approved scope" }[proof.verdict] ?? "Some required material is missing");
 }
 export function readAcceptanceEvidence(store, who, root, task, runId, offset = 0) {
@@ -75,7 +75,7 @@ export function readAcceptanceEvidence(store, who, root, task, runId, offset = 0
             accepted: acceptance !== null, acceptance: acceptance === null ? null : { at: acceptance.acceptedAt, note: brief(acceptance.note) },
             reasons: (recorded?.reasons ?? []).map(one => brief(one)), gate,
             criteriaTotal: matrix.length, nextCriterionOffset: offset + page.length < matrix.length ? offset + page.length : null,
-            criteria: page.map(row => ({ id: row.id, requirement: brief(row.statement), state: row.state === "manual-review" ? "Human review required" : row.state,
+            criteria: page.map(row => ({ id: row.id, requirement: brief(row.statement), state: row.state === "manual-review" ? "You check" : row.state,
                 details: row.detail.map(one => brief(one)), requiredEvidence: row.requiredEvidence,
                 reviewer: row.review == null ? null : { judgement: row.review.judgement, note: brief(row.review.note) },
                 evidence: row.answered.map(one => ({ kind: one.kind, reference: brief(one.ref) })),

package/dist/chat-quiet.js

@@ -7,6 +7,7 @@
 import { assignmentOf } from "./assignment.js";
 import { chatControlHref } from "./chat-controls.js";
 import { telegramProgressCard } from "./telegram-progress.js";
+import { assignmentStatusFacts, headlineEmoji, taskStatusOf } from "./task-status.js";
 import { phoneText, projectLabel } from "./telegram-status.js";
 import { isLifecycleNotification } from "./store.js";
 /** What always makes a new message, even in quiet mode: a question or approval waiting, a failure or other
@@ -37,15 +38,16 @@ function cardRun(store, taskRef) {
     return store.runsFor(taskRef).find(run => run.role === "builder" && run.contestant === null) ?? null;
 }
 /** Before any attempt starts, the card says where the task stands in the words of its last lifecycle fact. */
+const before = (headline) => ({ icon: headlineEmoji(headline), status: headline });
 const BEFORE_RUN = {
-    "task-filed": { icon: "📝", status: "Filed" },
-    "scope-approved": { icon: "✓", status: "Approved · Waiting to start" },
-    "approval-withdrawn": { icon: "📝", status: "Approval withdrawn" },
-    "task-held": { icon: "⏸", status: "Paused" },
-    "task-released": { icon: "✓", status: "Waiting to start" },
-    "task-queued": { icon: "✓", status: "Waiting to start" },
-    "task-requeued": { icon: "✓", status: "Waiting to start" },
-    "task-cancelled": { icon: "⏹", status: "Cancelled" },
+    "task-filed": before("Queued"),
+    "scope-approved": before("Queued"),
+    "approval-withdrawn": before("Needs you"),
+    "task-held": before("Stopped"),
+    "task-released": before("Queued"),
+    "task-queued": before("Queued"),
+    "task-requeued": before("Queued"),
+    "task-cancelled": before("Stopped"),
 };
 function taskLine(store, taskRef, now, root) {
     const ref = store.refById(taskRef);
@@ -85,10 +87,8 @@ export function quietCardView(store, taskRefs, now, root) {
 export function readyPingView(store, run, taskId, project, now, root) {
     const card = telegramProgressCard(store, run, taskId, project, now, root);
     const [title = "", shown = ""] = card.entities.map(one => card.text.slice(one.offset, one.offset + one.length));
-    // A saved result is Ready even in the moment before its worker lets go of the task.
-    const saved = shown.endsWith(" Result saved");
-    const heading = saved ? "✅ Ready" : shown;
-    const next = card.next !== "" ? card.next : saved ? "Next: open the result, then mark it complete or request changes." : "";
+    const heading = shown;
+    const next = card.next;
     const first = `${heading} · ${title}`;
     return { text: next === "" ? first : `${first}\n${next}`, entities: [{ type: "bold", offset: 0, length: heading.length }], link: card.link };
 }
@@ -120,18 +120,19 @@ export function eveningDigestText(store, account, now, root) {
             failed.set(row.taskId, title(row.taskId));
     }
     for (const taskId of new Set(facts.map(row => row.taskId).filter((one) => one !== null))) {
-        let state = null;
+        let headline = null;
         try {
             const project = facts.find(row => row.taskId === taskId).project;
-            state = assignmentOf(store, taskId, now, { principal: "operator", repos: [project] }, root)?.state ?? null;
+            const assignment = assignmentOf(store, taskId, now, { principal: "operator", repos: [project] }, root);
+            headline = assignment === null ? null : taskStatusOf(assignmentStatusFacts(assignment)).headline;
         }
         catch {
-            state = null;
+            headline = null;
         }
-        if (state === "ready-to-check")
-            waits.set(taskId, `${title(taskId)} · Ready for review`);
-        else if (state === "needs-decision")
-            waits.set(taskId, `${title(taskId)} · Needs your decision`);
+        if (headline === "Ready for review" || headline === "Needs you")
+            waits.set(taskId, `${title(taskId)} · ${headline}`);
+        else if (headline === "Failed")
+            failed.set(taskId, title(taskId));
     }
     if (finished.size + failed.size + waits.size === 0)
         return null;

package/dist/cli.js

@@ -1225,7 +1225,7 @@ async function runDemoCommand(argv, write) {
     const DEMO_USAGE = "`toolroll demo [--port <n>] [--host <addr>] [--allow-host name:port,…] [--keep]` — the port is a number under 65536; absent, a free one is picked";
     // Asking how it works never starts a sandbox.
     if (argv.includes("--help") || argv.includes("-h")) {
-        write(json ? envelopeJson({ ok: true, command: "demo", usage: DEMO_USAGE }) : `${DEMO_USAGE}\n\nA throwaway sandbox with a seeded fleet and flows mid-flight. It never spends and never reaches outside; Ctrl-C removes it unless --keep.`);
+        write(json ? envelopeJson({ ok: true, command: "demo", usage: DEMO_USAGE }) : `${DEMO_USAGE}\n\nA throwaway sandbox: a scripted lead in Chat, sample projects and flows mid-flight. It never calls a model, spends or reaches outside; Ctrl-C removes it unless --keep.`);
         return 0;
     }
     if (!Number.isInteger(port) || port < 0 || port > 65_535) {
@@ -1248,9 +1248,9 @@ async function runDemoCommand(argv, write) {
     const { createDemoSandbox } = await import("./demo.js");
     const { createDecisionServer } = await import("./serve.js");
     const now = new Date();
-    const { sandbox, store, seed, evidenceRoot, passwordFile } = createDemoSandbox(now);
+    const { sandbox, store, seed, evidenceRoot, passwordFile, lead } = createDemoSandbox(now);
     const server = createDecisionServer({
-        store, evidenceRoot, clock: () => new Date(), repos: seed.repos,
+        store, evidenceRoot, clock: () => new Date(), repos: seed.repos, demoLead: lead,
         ...(allowedHosts.length === 0 ? {} : { allowedHosts }),
     });
     await new Promise((ready, failed) => {
@@ -1268,14 +1268,13 @@ async function runDemoCommand(argv, write) {
         write(envelopeJson({ ok: true, command: "demo", url, sandbox, login: { name: seed.login.name, passwordFile }, keep }));
     }
     else {
-        write("Demo sandbox is up — seeded fleet, zero spend, zero remotes.");
+        write("Demo sandbox is up. A scripted lead answers Chat: no model, no key, no spend, nothing leaves this machine.");
         write("");
         write(`  open      ${url}`);
         write(`  login     ${seed.login.name} / ${seed.login.password}`);
         write(`  sandbox   ${sandbox}`);
         write("");
-        write("Two projects are seeded. The inbox works project-free; the board and");
-        write("routines ask you to open one first — pick payments-api.");
+        write("Open Chat and ask for a change, like \"fix the flaky refund test\".");
         write("");
         write(keep
             ? "Ctrl-C stops the server; the sandbox is KEPT. It stays a demo forever — every spending command refuses it."
@@ -1290,6 +1289,7 @@ async function runDemoCommand(argv, write) {
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
     });
+    lead.stop();
     await new Promise(closed => server.close(() => closed()));
     store.close();
     if (!keep) {

package/dist/containment.d.ts

@@ -103,6 +103,11 @@ export type EffectiveContainment = {
 export declare function effectiveContainment(policy: ContainmentPolicy, capability: ContainmentCapability): EffectiveContainment;
 /** One-line status words for `daemon status`, `up`, and the certificate. */
 export declare function describeContainment(effective: EffectiveContainment): string;
+/** The one sentence a person reads at start when agents on Linux run
+ * without native containment that the machine could offer once set up;
+ * null when there is nothing a person needs to read. The exact
+ * `describeContainment` line stays in --verbose and in a service log. */
+export declare function containmentNotice(effective: EffectiveContainment): string | null;
 /** The status envelope's shape: no paths a person did not already know, no secrets. */
 export declare function containmentStatus(effective: EffectiveContainment): Record<string, unknown>;
 /**

package/dist/containment.js

@@ -191,6 +191,15 @@ export function describeContainment(effective) {
         return `containment: observed (preferred native, ${backend} unavailable) — ${effective.capability.detail}`;
     return `containment: observed (${effective.policy}) — ${effective.capability.detail}`;
 }
+/** The one sentence a person reads at start when agents on Linux run
+ * without native containment that the machine could offer once set up;
+ * null when there is nothing a person needs to read. The exact
+ * `describeContainment` line stays in --verbose and in a service log. */
+export function containmentNotice(effective) {
+    if (effective.refusal !== null || effective.mode !== "observed" || effective.capability.platform !== "linux" || effective.capability.available)
+        return null;
+    return "Agents run without Linux process containment on this machine (it needs a delegated cgroup). That's fine for trying Toolroll; see docs/guide/linux.md to turn it on.";
+}
 /** The status envelope's shape: no paths a person did not already know, no secrets. */
 export function containmentStatus(effective) {
     return {

package/dist/demo-chat.d.ts

@@ -0,0 +1,32 @@
+import type { DemoExchange } from "./demo.js";
+/** What a finished exchange's stored result holds, read back from its evidence. */
+export type DemoResultView = {
+    diff: string | null;
+    checkLog: string | null;
+    checks: {
+        status: string;
+        detail: string;
+    };
+    screenshot: {
+        href: string;
+        caption: string;
+    } | null;
+    additions: number;
+    deletions: number;
+    files: number;
+    taskHref: string;
+};
+/** The conversation itself; the live script swaps this region in place. */
+export declare function demoThreadHtml(exchanges: readonly DemoExchange[], csrf: string, resultOf: (exchange: DemoExchange) => DemoResultView | null): string;
+export declare function demoChatHtml(input: {
+    exchanges: readonly DemoExchange[];
+    csrf: string;
+    version: number;
+    problem: string | null;
+    resultOf: (exchange: DemoExchange) => DemoResultView | null;
+}): string;
+/**
+ * Keeps a running build live: polls while one is working and swaps the
+ * thread in place, unless the visitor is typing inside it. Enter sends.
+ */
+export declare const DEMO_CHAT_SCRIPT = "(() => {\n  const thread = () => document.getElementById(\"demo-thread\");\n  let timer = 0;\n  const editing = region => region.contains(document.activeElement) && document.activeElement.matches(\"textarea, input\") || region.querySelector(\"details[open] textarea:not(:placeholder-shown)\") !== null;\n  const tick = async () => {\n    const region = thread();\n    if (!region) { timer = setTimeout(tick, 400); return; }\n    if (region.dataset.working !== \"1\") return;\n    try {\n      const answer = await fetch(\"/chat/demo/live\", { headers: { accept: \"application/json\" }, credentials: \"same-origin\" });\n      if (answer.ok) {\n        const next = await answer.json();\n        if (String(next.version) !== region.dataset.version && !editing(region)) {\n          region.innerHTML = next.html;\n          region.dataset.version = String(next.version);\n          region.dataset.working = next.working ? \"1\" : \"0\";\n          if (!next.working) {\n            const last = region.querySelector(\".demo-turn:last-of-type .demo-result\");\n            if (last) last.scrollIntoView({ block: \"nearest\", behavior: matchMedia(\"(prefers-reduced-motion: reduce)\").matches ? \"auto\" : \"smooth\" });\n          }\n        }\n      }\n    } catch { /* the next tick tries again */ }\n    if (thread()?.dataset.working === \"1\") timer = setTimeout(tick, 700);\n  };\n  const start = () => { clearTimeout(timer); tick(); };\n  document.addEventListener(\"keydown\", event => {\n    const field = event.target;\n    if (event.key !== \"Enter\" || event.shiftKey || event.isComposing || !(field instanceof HTMLTextAreaElement) || field.id !== \"demo-message\") return;\n    if (field.value.trim() === \"\") return;\n    event.preventDefault();\n    field.form?.requestSubmit();\n  });\n  window.addEventListener(\"standing-orders:workspace-rendered\", start);\n  if (document.readyState === \"loading\") document.addEventListener(\"DOMContentLoaded\", start); else start();\n})();";

package/dist/demo-chat.js

@@ -0,0 +1,158 @@
+/**
+ * Chat in `toolroll demo`: the scripted lead's conversation (src/demo.ts),
+ * rendered as plain server HTML with native forms. One small script keeps a
+ * running build's progress live; without it the page still works by reload.
+ */
+import { headlineOf } from "./task-status.js";
+const SUGGESTIONS = ["Fix the flaky refund test", "Rewrite the empty Payouts page", "Put the new invoice view behind a flag"];
+const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+const hidden = (csrf) => `<input type="hidden" name="csrf" value="${esc(csrf)}">`;
+function hint(csrf) {
+    return `<section class="demo-hint" aria-label="Get started">` +
+        `<p class="demo-hint-title">Ask for something, like “fix the flaky refund test”</p>` +
+        `<form method="post" action="/chat/demo/ask" class="demo-suggestions">${hidden(csrf)}` +
+        SUGGESTIONS.map(one => `<button type="submit" name="message" value="${esc(one)}">${esc(one)}</button>`).join("") +
+        `</form></section>`;
+}
+function planCard(exchange, csrf) {
+    const plan = exchange.plan;
+    const goal = exchange.note === null ? plan.goal : `${plan.goal} Also: ${exchange.note}`;
+    const actions = exchange.state === "proposed"
+        ? `<div class="demo-actions">` +
+            `<form method="post" action="/chat/demo/${exchange.id}/approve" class="approve-form">${hidden(csrf)}<button type="submit">Approve</button></form>` +
+            `<details class="demo-more"><summary>Change it</summary>` +
+            `<form method="post" action="/chat/demo/${exchange.id}/change">${hidden(csrf)}` +
+            `<label for="demo-change-${exchange.id}">What should change?</label>` +
+            `<textarea id="demo-change-${exchange.id}" name="note" rows="2" maxlength="500" required></textarea>` +
+            `<button type="submit">Update plan</button></form></details></div>`
+        : exchange.state === "replaced"
+            ? `<p class="meta">Replaced by the updated plan below.</p>`
+            : `<p class="meta">Approved.</p>`;
+    return `<section class="card demo-plan" aria-label="Plan">` +
+        `<p class="demo-kicker">Plan · ${esc(plan.project)}</p>` +
+        `<h2>${esc(plan.title)}</h2>` +
+        `<p>${esc(goal)}</p>` +
+        `<h3>Boundaries</h3><ul>${plan.boundaries.map(one => `<li>${esc(one)}</li>`).join("")}</ul>` +
+        `<h3>Checks</h3><ul>${plan.checks.map(one => `<li>${esc(one)}</li>`).join("")}</ul>` +
+        actions + `</section>`;
+}
+function buildCard(exchange) {
+    const stages = [["planning", "Planning"], ["building", "Building"], ["checking", "Running checks"]];
+    const at = stages.findIndex(([key]) => key === exchange.stage);
+    return `<section class="card demo-build" id="demo-${exchange.id}-work" aria-label="Build" aria-busy="true">` +
+        `<p class="demo-kicker">${esc(exchange.plan.project)}</p>` +
+        `<h2>${esc(stages[Math.max(0, at)][1])}…</h2>` +
+        `<ol class="demo-steps">${stages.map(([, label], index) => `<li class="${index < at ? "done" : index === at ? "now" : ""}"${index === at ? ` aria-current="step"` : ""}>${esc(label)}</li>`).join("")}</ol>` +
+        (exchange.progress === null ? "" : `<p class="meta demo-progress">${esc(exchange.progress)}</p>`) +
+        `</section>`;
+}
+function diffHtml(diff) {
+    return diff.replace(/\n$/, "").split("\n").map(line => {
+        const kind = line.startsWith("diff --git") || line.startsWith("new file") ? "file"
+            : line.startsWith("+++") || line.startsWith("---") ? "meta"
+                : line.startsWith("@@") ? "hunk"
+                    : line.startsWith("+") ? "add" : line.startsWith("-") ? "del" : "ctx";
+        return `<span class="demo-diff-${kind}">${esc(line) || " "}</span>`;
+    }).join("");
+}
+function resultCard(exchange, csrf, result) {
+    if (result === null)
+        return `<section class="card demo-result"><p class="meta">This result's saved evidence is unavailable.</p></section>`;
+    const passed = result.checks.status === "passed";
+    // The shared headline (task-status.ts): the same words as every real task.
+    const headline = headlineOf({ stage: exchange.state === "complete" ? "complete" : exchange.state === "sent-back" ? "building" : "finished",
+        checks: { status: passed ? "passed" : "failed", exitCode: null, head: null } });
+    const status = `<span class="badge${headline === "Complete" ? " demo-complete" : headline === "Ready for review" ? " demo-ready" : ""}" data-headline="${headline}">${headline}</span>`;
+    const summary = `${result.files} file${result.files === 1 ? "" : "s"} changed · +${result.additions} −${result.deletions} · ` +
+        `<span class="${passed ? "demo-pass" : "demo-fail"}">${esc(result.checks.detail)}</span>`;
+    const actions = exchange.state === "ready"
+        ? `<div class="demo-actions">` +
+            `<form method="post" action="/chat/demo/${exchange.id}/complete">${hidden(csrf)}<button type="submit" class="demo-primary">Complete</button></form>` +
+            `<details class="demo-more"><summary>Request changes</summary>` +
+            `<form method="post" action="/chat/demo/${exchange.id}/revise">${hidden(csrf)}` +
+            `<label for="demo-revise-${exchange.id}">What should change?</label>` +
+            `<textarea id="demo-revise-${exchange.id}" name="note" rows="2" maxlength="500" required></textarea>` +
+            `<button type="submit">Send back</button></form></details></div>`
+        : `<p class="meta"><a href="${esc(result.taskHref)}">Open in Tasks</a></p>`;
+    return `<section class="card demo-result" id="demo-${exchange.id}-work" aria-label="Result">` +
+        `<p class="demo-state">${status}<span class="meta">${esc(exchange.plan.project)}</span></p>` +
+        `<h2>${esc(exchange.plan.title)}</h2>` +
+        `<p>${esc(exchange.plan.conclusion)}</p>` +
+        `<p class="meta">${summary}</p>` +
+        actions +
+        (result.diff === null ? "" : `<details class="demo-evidence"${exchange.state === "ready" ? " open" : ""}><summary>Changes</summary><pre class="demo-diff">${diffHtml(result.diff)}</pre></details>`) +
+        (result.checkLog === null ? "" : `<details class="demo-evidence"><summary>Check log</summary><pre class="demo-log">${esc(result.checkLog)}</pre></details>`) +
+        (result.screenshot === null ? "" : `<details class="demo-evidence"><summary>Screenshot</summary><figure><img src="${esc(result.screenshot.href)}" alt="${esc(result.screenshot.caption)}" width="960" height="600"><figcaption class="meta">${esc(result.screenshot.caption)}</figcaption></figure></details>`) +
+        `</section>`;
+}
+/** The conversation itself; the live script swaps this region in place. */
+export function demoThreadHtml(exchanges, csrf, resultOf) {
+    if (exchanges.length === 0)
+        return hint(csrf);
+    return exchanges.map(exchange => {
+        const parts = [
+            `<div class="demo-said demo-you"><p>${esc(exchange.asked)}</p></div>`,
+            `<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>${esc(exchange.reply)}</p></div>`,
+            planCard(exchange, csrf),
+        ];
+        if (exchange.state === "working")
+            parts.push(buildCard(exchange));
+        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>`);
+        }
+        return `<article class="demo-turn" id="demo-${exchange.id}">${parts.join("")}</article>`;
+    }).join("");
+}
+export function demoChatHtml(input) {
+    const working = input.exchanges.some(one => one.state === "working");
+    return `<div class="demo-chat">` +
+        (input.problem === null ? "" : `<p class="problem" role="alert">${esc(input.problem)}</p>`) +
+        `<div id="demo-thread" class="demo-thread" aria-live="polite" data-version="${input.version}" data-working="${working ? "1" : "0"}">` +
+        demoThreadHtml(input.exchanges, input.csrf, input.resultOf) + `</div>` +
+        `<form method="post" action="/chat/demo/ask" class="demo-composer">${hidden(input.csrf)}` +
+        `<label for="demo-message" class="so-sr-only">Message the lead</label>` +
+        `<textarea id="demo-message" name="message" rows="2" maxlength="500" placeholder="Ask the lead for a change" required></textarea>` +
+        `<button type="submit" class="demo-primary">Send</button></form></div>`;
+}
+/**
+ * Keeps a running build live: polls while one is working and swaps the
+ * thread in place, unless the visitor is typing inside it. Enter sends.
+ */
+export const DEMO_CHAT_SCRIPT = `(() => {
+  const thread = () => document.getElementById("demo-thread");
+  let timer = 0;
+  const editing = region => region.contains(document.activeElement) && document.activeElement.matches("textarea, input") || region.querySelector("details[open] textarea:not(:placeholder-shown)") !== null;
+  const tick = async () => {
+    const region = thread();
+    if (!region) { timer = setTimeout(tick, 400); return; }
+    if (region.dataset.working !== "1") return;
+    try {
+      const answer = await fetch("/chat/demo/live", { headers: { accept: "application/json" }, credentials: "same-origin" });
+      if (answer.ok) {
+        const next = await answer.json();
+        if (String(next.version) !== region.dataset.version && !editing(region)) {
+          region.innerHTML = next.html;
+          region.dataset.version = String(next.version);
+          region.dataset.working = next.working ? "1" : "0";
+          if (!next.working) {
+            const last = region.querySelector(".demo-turn:last-of-type .demo-result");
+            if (last) last.scrollIntoView({ block: "nearest", behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
+          }
+        }
+      }
+    } catch { /* the next tick tries again */ }
+    if (thread()?.dataset.working === "1") timer = setTimeout(tick, 700);
+  };
+  const start = () => { clearTimeout(timer); tick(); };
+  document.addEventListener("keydown", event => {
+    const field = event.target;
+    if (event.key !== "Enter" || event.shiftKey || event.isComposing || !(field instanceof HTMLTextAreaElement) || field.id !== "demo-message") return;
+    if (field.value.trim() === "") return;
+    event.preventDefault();
+    field.form?.requestSubmit();
+  });
+  window.addEventListener("standing-orders:workspace-rendered", start);
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start); else start();
+})();`;

package/dist/demo.d.ts

@@ -52,4 +52,102 @@ export declare function createDemoSandbox(now: Date): {
     seed: DemoSeed;
     evidenceRoot: string;
     passwordFile: string;
+    lead: DemoLead;
 };
+type DemoProject = "payments-api" | "web-console";
+type DemoFile = {
+    path: string;
+    before: string | null;
+    after: string;
+};
+export type DemoPlan = {
+    kind: "flaky-test" | "bug" | "copy" | "flag" | "default";
+    project: DemoProject;
+    title: string;
+    goal: string;
+    boundaries: string[];
+    checks: string[];
+    /** What the builder reports while it works, one line per beat. */
+    progress: string[];
+    conclusion: string;
+    checkOutput: string;
+    screenshot: {
+        caption: string;
+        accent: readonly [number, number, number];
+    };
+    files: DemoFile[];
+};
+/** The scripted lead's choice: a plan named by the request's words, else the default. */
+export declare function pickDemoPlan(text: string): DemoPlan;
+export type DemoExchange = {
+    id: number;
+    /** What the visitor typed, or the note that asked for this plan. */
+    asked: string;
+    reply: string;
+    plan: DemoPlan;
+    /** A visitor's extra instruction carried into the plan by Change it or Request changes. */
+    note: string | null;
+    state: "proposed" | "replaced" | "working" | "ready" | "complete" | "sent-back";
+    stage: "planning" | "building" | "checking" | null;
+    progress: string | null;
+    taskId: string | null;
+    runId: number | null;
+    approvedAt: number | null;
+};
+export type DemoLead = {
+    exchanges(): readonly DemoExchange[];
+    /** Changes whenever anything a reader would see changes. */
+    version(): number;
+    ask(text: string, now: Date): DemoExchange;
+    approve(id: number, now: Date): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    change(id: number, note: string, now: Date): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    requestChanges(id: number, note: string, now: Date): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    /** Complete through the real completion act, then mark the exchange. */
+    complete(id: number, now: Date, act: (taskId: string, runId: number) => {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    advance(now: Date): void;
+    stop(): void;
+};
+/**
+ * The scripted lead. `stepMs` is one beat: planning takes one, building two
+ * (one per progress line), checks one, so a build lands Ready in four beats.
+ * State advances on a timer AND whenever someone reads, so a page and the
+ * Tasks list agree without anyone polling.
+ */
+export declare function createDemoLead(input: {
+    store: Store;
+    repos: {
+        api: string;
+        web: string;
+    };
+    evidenceRoot: string;
+    approver: string;
+    token: string;
+    stepMs?: number;
+    clock?: () => Date;
+}): DemoLead;
+export {};