toolroll 0.9.103 → 0.9.105

package/dist/daemon.js

@@ -1,40 +1,3 @@
-/**
- * The daemon manager: the loop as a service, with no crontab in sight.
- *
- * `toolroll daemon install` writes the platform's own supervision unit —
- * a launchd LaunchAgent on macOS, a systemd user unit on Linux, a Task
- * Scheduler task on Windows, chosen by process.platform — pointed at
- * `toolroll watch`, and loads it. The OS keeps it alive across crashes
- * and reboots; watch's incarnation recovery is what makes those restarts
- * safe, so the two halves were built for each other.
- *
- * The runner token never enters the unit file. It is written 0600 to a
- * credential file beside the database (the same discipline as the Telegram
- * bot token), and the unit runs `watch --token-file <path>`. A unit file is
- * the kind of thing that ends up in a dotfiles repo; a credential file
- * beside the database is the kind of thing backup tooling already treats
- * as sensitive.
- *
- * The lifecycle (OS containment and login recovery plan) is ONE contract
- * for the CLI daemon and the desktop service, which share the launchd road
- * below:
- *   - an installed always-on controller restarts after an unexpected
- *     clean exit as well as a crash (launchd KeepAlive=true, systemd
- *     Restart=always, a cmd restart loop under Task Scheduler);
- *   - start is idempotent — a healthy running service is never killed
- *     because the installer or the app window ran again;
- *   - a CHANGED definition (runtime, entry, flags) really reloads: the old
- *     job is booted out, its disappearance is awaited (the pending-bootout
- *     race), and the new unit is bootstrapped;
- *   - explicit stop unloads AND disables, so nothing relaunches it until a
- *     person installs again — which re-enables;
- *   - status tells a loaded definition from a fresh working controller,
- *     and names a missing runtime, a missing entry, or a disabled service.
- *
- * Everything here is generation plus one supervisor invocation, both
- * injectable — the tests read the generated unit and script `launchctl`,
- * and never touch the machine's real supervision.
- */
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
@@ -43,16 +6,9 @@ import { dirname, join } from "node:path";
 import { isAlive } from "./runner.js";
 import { envTwins } from "./names.js";
 import { sleep as defaultSleep } from "./sleep.js";
-/** A stable fingerprint of a unit's text: the changed-definition test. */
 export function definitionDigest(unitContent) {
     return createHash("sha256").update(unitContent).digest("hex").slice(0, 16);
 }
-/**
- * `launchctl bootout` can return before the old label has disappeared from
- * the user domain. Bootstrapping the replacement during that short window
- * appears to succeed, then the pending bootout removes the new job too. Wait
- * for the observable supervisor boundary before loading the replacement.
- */
 async function waitForLaunchdBootout(run, service, attempts = 50, sleep = defaultSleep) {
     for (let attempt = 0; attempt < attempts; attempt += 1) {
         const status = await run("launchctl", ["print", service]);
@@ -62,16 +18,6 @@ async function waitForLaunchdBootout(run, service, attempts = 50, sleep = defaul
     }
     return false;
 }
-/**
- * Pin a service to the Node runtime that is executing Toolroll.
- *
- * launchd does not inherit an interactive shell's PATH, so invoking a JS
- * package bin through `#!/usr/bin/env node` can install successfully and then
- * fail before the CLI starts. The service instead runs the absolute Node
- * binary with the package entry as its first argument. An explicitly supplied
- * non-JavaScript executable remains an escape hatch for wrappers and packaged
- * binaries.
- */
 export function daemonLaunchCommand(args) {
     if (args.explicitBin !== undefined) {
         return /\.(?:c|m)?js$/i.test(args.explicitBin)
@@ -82,11 +28,9 @@ export function daemonLaunchCommand(args) {
         return null;
     return { bin: args.execPath, binArgs: [args.entry] };
 }
-/** One service per repo, named so two repos' watches never collide. */
 export function labelFor(repo) {
     return `com.toolroll.watch.${watchSlug(repo)}`;
 }
-/** The label a watch installed before the rename to Toolroll runs under: still found, stopped and uninstalled. */
 export function legacyLabelFor(repo) {
     return `com.standing-orders.watch.${watchSlug(repo)}`;
 }
@@ -98,17 +42,9 @@ function watchSlug(repo) {
         .slice(-40);
     return slug === "" ? "root" : slug;
 }
-/** The uid launchd's gui domain is keyed by. */
 function launchdUid() {
     return typeof process.getuid === "function" ? process.getuid() : 501;
 }
-/**
- * The launchd unit shared by the CLI daemon and the desktop service.
- * KeepAlive requests relaunch after either clean exit or crash. macOS may
- * defer nondemand launches; the desktop's live controller supervisor covers
- * controller exits independently. Login/OS-service recovery requires the
- * physical certification, not just a valid plist.
- */
 export function launchdPlist(args) {
     if (args.startInterval !== undefined && (!Number.isSafeInteger(args.startInterval) || args.startInterval < 1))
         throw Error("Invalid launchd start interval.");
@@ -116,8 +52,6 @@ export function launchdPlist(args) {
         throw new Error("Invalid associated app bundle identifier.");
     const escaped = args.command.map(part => `    <string>${xml(part)}</string>`).join("\n");
     const digest = createHash("sha256").update(JSON.stringify(args));
-    // Include executable and package code identity so an update at the same
-    // path reloads the service. Files are only read; credentials are excluded.
     for (const file of args.command.slice(0, 2)) {
         try {
             if (file && existsSync(file))
@@ -173,10 +107,6 @@ ${environment}
 </plist>
 `;
 }
-/**
- * Everything `install` would do, computed without doing it — the unit text,
- * where it goes, where logs land. `--dry-run` prints exactly this.
- */
 export function planDaemon(args) {
     const { platform, bin, binArgs, runner, repo, configDir, watchFlags } = args;
     const home = args.home ?? homedir();
@@ -216,14 +146,6 @@ export function planDaemon(args) {
         };
     }
     if (platform === "win32") {
-        // Task Scheduler is Windows' launchd: a logon-triggered task, restarted
-        // on failure, created from an XML definition — no admin, no Service
-        // wrapper. schtasks does not redirect output, so the action runs
-        // through cmd with an append redirection into the same log file the
-        // other platforms use. RestartOnFailure covers a crash only; a clean
-        // exit would end the task, so the action itself is a bounded restart
-        // loop (15 s between runs, like ThrottleInterval) — `schtasks /End`
-        // (explicit stop) ends the loop's whole tree.
         const inner = [quoteWin(bin), ...binArgs.map(quoteWin), "watch",
             "--runner", quoteWin(runner), "--token-file", quoteWin(tokenFile),
             "--repo", quoteWin(repo), ...watchFlags.map(quoteWin)].join(" ");
@@ -269,10 +191,6 @@ export function planDaemon(args) {
             entry,
         };
     }
-    // Restart=always: a clean exit the operator did not ask for comes back
-    // too; `systemctl --user stop` / `disable --now` (explicit stop) does
-    // not trigger a restart. Whether the user manager itself survives logout
-    // is linger (`loginctl enable-linger`) — documented, not assumed.
     const unitContent = `[Unit]
 Description=toolroll watch — ${repo}
 
@@ -300,7 +218,6 @@ WantedBy=default.target
         entry,
     };
 }
-/** The desktop shell's always-on controller: the same launchd contract, pointed at the desktop host. */
 export function planDesktopService(args) {
     const home = args.home ?? homedir();
     const logPath = join(args.stateDir, "service.log");
@@ -322,21 +239,11 @@ export function planDesktopService(args) {
         entry: args.helper,
     };
 }
-/** The file on disk does not identify the definition launchd has loaded. */
 function loadedLaunchdMatches(unit, status) {
-    // Either name: a unit written before the rename carries only the older one.
     const wanted = /<key>(?:TOOLROLL|STANDING_ORDERS)_SERVICE_DIGEST<\/key>\s*<string>([a-f0-9]{64})<\/string>/.exec(unit)?.[1];
     const actual = /(?:TOOLROLL|STANDING_ORDERS)_SERVICE_DIGEST\s*=>\s*([a-f0-9]{64})/.exec(status)?.[1];
     return wanted !== undefined && actual === wanted;
 }
-/**
- * The shared launchd road. Idempotent start: a loaded job whose definition
- * is unchanged is kickstarted WITHOUT -k (a running one is left alone; a
- * stopped one starts); a loaded job whose definition changed is booted out,
- * awaited, and bootstrapped afresh; an unloaded label is enabled (an
- * explicit stop had disabled it) and bootstrapped. Nothing here kills a
- * healthy service to prove it can.
- */
 export async function installLaunchdService(definition, run) {
     const uid = launchdUid();
     const service = `gui/${uid}/${definition.label}`;
@@ -363,28 +270,21 @@ export async function installLaunchdService(definition, run) {
             return { ok: false, message: "launchd did not finish stopping the previous worker; try the install again" };
         }
     }
-    // An explicit stop disables the label; installing again is the only road back.
     const enabled = await run("launchctl", ["enable", service]);
     if (enabled.code !== 0)
         return { ok: false, message: `launchctl could not enable the service: ${firstLine(enabled.stderr) || enabled.code}` };
     const modern = await run("launchctl", ["bootstrap", `gui/${uid}`, definition.unitPath]);
     if (modern.code === 0) {
-        // RunAtLoad starts the job; the kickstart (no -k: never a restart) gives
-        // the installer a synchronous boundary instead of "the plist parsed".
         const started = await run("launchctl", ["kickstart", service]);
         if (started.code === 0)
             return { ok: true, changed, action: loaded ? "reloaded" : "bootstrapped" };
         return { ok: false, message: `loaded, but launchctl could not start the worker: ${firstLine(started.stderr) || `exit ${started.code}`}` };
     }
-    // Modern first, legacy fallback: `bootstrap` replaced `load` but older
-    // macOS answers only to the old verb.
     const legacy = await run("launchctl", ["load", "-w", definition.unitPath]);
     if (legacy.code === 0)
         return { ok: true, changed, action: loaded ? "reloaded" : "bootstrapped" };
     return { ok: false, message: `launchctl refused the unit: ${firstLine(modern.stderr) || firstLine(legacy.stderr) || `exit ${legacy.code}`}` };
 }
-/** Replace a file whole: a flushed temporary beside it, renamed over it, and the directory flushed, so a crash
- * leaves the old text or the new, never a torn one. */
 export function writeFileDurably(file, content, mode = 0o600) {
     const temp = join(dirname(file), `.${file.slice(dirname(file).length + 1)}.${randomUUID().slice(0, 8)}.tmp`);
     const fd = openSync(temp, "wx", mode);
@@ -407,8 +307,6 @@ export function writeFileDurably(file, content, mode = 0o600) {
         }
     }
 }
-/** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. `waitMs` is how long
- * the job may take to leave launchd (5 s by default; a watch's `toolroll up` can take 45 s to exit). */
 export async function stopLaunchdService(definition, run, wait = {}) {
     const service = `gui/${launchdUid()}/${definition.label}`;
     const disabled = await run("launchctl", ["disable", service]);
@@ -421,23 +319,10 @@ export async function stopLaunchdService(definition, run, wait = {}) {
         return { ok: false, message: `launchctl did not stop ${definition.label}; the service is still loaded` };
     return { ok: true, wasLoaded: modern.code === 0 };
 }
-/**
- * The same repo's watch as installed under the label it had before the
- * rename to Toolroll, when its unit is still on disk; null otherwise.
- * Installing the new one stops and removes it, so two watches never run.
- */
 export function installedLegacyDaemon(args) {
     const legacy = planDaemon({ ...args, label: legacyLabelFor(args.repo) });
     return "error" in legacy || !existsSync(legacy.unitPath) ? null : legacy;
 }
-/**
- * Install the watch, then retire its copy from before the rename. The new
- * job goes in first: when its install fails the legacy watch is left
- * running, so the repo is never left without one. Only once the new job is
- * installed is the legacy one stopped and removed; the new one is then
- * started again, since it may have stepped aside while the legacy watch
- * still held the repo's lease.
- */
 export async function installReplacingLegacy(plan, token, legacy, run) {
     const installed = await installDaemon(plan, token, run);
     if (!installed.ok || legacy === null)
@@ -451,7 +336,6 @@ export async function installReplacingLegacy(plan, token, legacy, run) {
     const restarted = await installDaemon(plan, token, run);
     return restarted.ok ? installed : restarted;
 }
-/** Write the token 0600 and the unit, then hand the unit to the supervisor. */
 export async function installDaemon(plan, token, run) {
     writeFileSync(plan.tokenFile, `${token}\n`, { mode: 0o600 });
     chmodSync(plan.tokenFile, 0o600);
@@ -463,9 +347,6 @@ export async function installDaemon(plan, token, run) {
     mkdirSync(join(plan.unitPath, ".."), { recursive: true });
     writeFileSync(plan.unitPath, plan.unitContent, { mode: 0o644 });
     if (plan.platform === "win32") {
-        // /F replaces an existing definition, so re-install is idempotent. A
-        // task already running under an UNCHANGED definition is left alone; a
-        // changed one is ended and run again so the new action takes effect.
         const created = await run("schtasks", ["/Create", "/TN", plan.label, "/XML", plan.unitPath, "/F"]);
         if (created.code !== 0) {
             return { ok: false, message: `schtasks /Create failed: ${firstLine(created.stderr) || `exit ${created.code}`}` };
@@ -488,8 +369,6 @@ export async function installDaemon(plan, token, run) {
     }
     const active = (await run("systemctl", ["--user", "is-active", plan.label])).stdout.trim() === "active";
     if (active && changed) {
-        // `enable --now` leaves a running service on its OLD definition; only a
-        // restart loads the new one.
         const restarted = await run("systemctl", ["--user", "restart", plan.label]);
         if (restarted.code !== 0)
             return { ok: false, message: `systemctl restart failed: ${firstLine(restarted.stderr)}` };
@@ -522,12 +401,6 @@ export async function uninstallDaemon(plan, run) {
     }
     return { ok: true, existed };
 }
-/**
- * The definition a label is INSTALLED under, read back from the unit file
- * (the certificate's view: whatever is on disk is the baseline, so `stale`
- * is false by construction and the runtime/entry are the installed ones).
- * Null when no unit file exists for the label.
- */
 export function installedServiceDefinition(args) {
     const platform = args.platform ?? process.platform;
     if (platform !== "darwin" && platform !== "linux" && platform !== "win32")
@@ -558,7 +431,6 @@ export function installedServiceDefinition(args) {
 function unxml(text) {
     return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
 }
-/** Runtime facts that make a loaded definition unable to become a working controller. */
 export function runtimeProblems(definition) {
     const problems = [];
     if (!existsSync(definition.bin))
@@ -617,14 +489,6 @@ export async function daemonStatus(plan, run) {
         ? { state: "running", pid: pid > 0 ? pid : null, detail: "active", ...facts }
         : { state: "loaded", pid: null, detail: "installed, inactive", ...facts };
 }
-/**
- * A supervisor PID is necessary but not sufficient: macOS can leave a
- * process stuck behind a protected-folder access check before it ever
- * opens the queue. The credentialed runner heartbeat is the end-to-end
- * readiness receipt that proves a service reached the work loop — and a
- * FRESH one, newer than what stood before the start, so a stale row from
- * the previous incarnation cannot pass for the new controller.
- */
 export async function awaitFreshHeartbeat(store, runnerName, heartbeatBefore, deadlineMs = 5_000, sleep = defaultSleep) {
     const deadline = Date.now() + deadlineMs;
     for (;;) {
@@ -639,7 +503,6 @@ export async function awaitFreshHeartbeat(store, runnerName, heartbeatBefore, de
 function xml(text) {
     return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-/** cmd.exe quoting: wrap anything with spaces; embedded quotes are not survivable in cmd — refuse them upstream by construction (paths and flags here never carry them). */
 function quoteWin(part) {
     return /[\s&|<>^]/.test(part) ? `"${part}"` : part;
 }

package/dist/database-reclaim.js

@@ -1,5 +1,3 @@
-/** Reclaim whole free pages on databases created without auto_vacuum. Call only after committing writes.
- * A migration needs at least 1 MiB to justify the I/O; retention reclaims whenever more than 25% is free. */
 export function reclaimDatabase(db, reason) {
     const free = Number(db.prepare("PRAGMA freelist_count").get()["freelist_count"]);
     const pages = Number(db.prepare("PRAGMA page_count").get()["page_count"]);
@@ -7,7 +5,6 @@ export function reclaimDatabase(db, reason) {
     if (reason === "migration" ? free * size < 1024 * 1024 : free * 4 <= pages)
         return false;
     db.exec("VACUUM");
-    // VACUUM writes through WAL too: checkpoint so the main file (and its backups) shrinks now.
     db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
     return true;
 }

package/dist/decision.js

@@ -1,51 +1,17 @@
-/**
- * The decision payload, validated (§7).
- *
- * The convention agents drift from in prose is a schema here, and the schema
- * is fail-closed: a payload missing anything a person would need on a phone
- * screen at 7am is not a decision, it is a malformed one — and the caller's
- * next move is bounded repair, not a guess at what the agent meant.
- *
- * Everything in the payload is written by an agent, which means everything in
- * it is untrusted twice over: it will be rendered into a web page, printed
- * into terminals, and — after the operator answers — quoted back into another
- * agent's brief. The caps and the control-character rejection here are the
- * first line of that defence; the escaping at each sink is the second. The
- * caps also keep one screen one screen: an option list that needs scrolling
- * has already failed the milestone sentence.
- */
 import { readDecisionPayload } from "./contracts/decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
-/** One screen's worth, enforced rather than hoped for. The payload's fields are bounded by its schema (src/contracts/decision.ts, from TEXT_LIMITS). */
 export const LIMITS = {
-    /** Bytes, before parsing. Applied by the reader too; this is the backstop. */
     payload: 64 * 1024,
-    /** UTF-16 code units (TEXT_LIMITS.note: revise feedback, steering and decision notes); the byte backstop lives in validateNote. */
     note: TEXT_LIMITS.note,
 };
-/** Bytes an operator's note may occupy — the UTF-8 backstop under LIMITS.note. */
 export const NOTE_BYTE_CAP = TEXT_LIMITS.noteBytes;
-/** Why a question closed without an answer (v119), in plain words. */
 export function closedQuestionReason(reason) {
     return reason === "scope-changed" ? "The scope changed, so planning started again." : "The task was cancelled.";
 }
-/** The same, said once on one line wherever its answer would show. */
 export function closedQuestionWords(reason) {
     return `Closed without an answer. ${closedQuestionReason(reason)}`;
 }
-/**
- * Unicode that reorders or breaks lines invisibly: bidi controls and the
- * line/paragraph separators. A note carrying these can spoof what a
- * reviewer SEES agreeing to — rejected outright, never stripped
- * (Codex free-text review, prescribed caps).
- */
 const FORBIDDEN_INVISIBLES = /[\u2028\u2029\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/;
-/**
- * The one validator every note passes — before a draft persists AND inside
- * the answer CAS, which stays the final gate. Trims, then refuses empty,
- * oversized (units or bytes), control-carrying, or invisibly-reordering
- * text. Ordinary Unicode with internal newlines and tabs passes untouched.
- */
 export function validateNote(raw) {
     const note = raw.trim();
     if (note === "")
@@ -60,33 +26,14 @@ export function validateNote(raw) {
     }
     return { ok: true, note };
 }
-/**
- * Multi-line prose may contain newlines and tabs; nothing anywhere in a
- * decision may contain the rest of C0/C1 — those are how text stops being
- * text and starts being terminal escape sequences.
- */
-// eslint-disable-next-line no-control-regex
 const FORBIDDEN_MULTILINE = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/;
-// eslint-disable-next-line no-control-regex
 const FORBIDDEN_SINGLE_LINE = /[\u0000-\u001F\u007F-\u009F]/;
-/** Whether text carries controls that could become escapes at a sink. Newlines and tabs pass. */
 export function hasForbiddenControls(text) {
     return FORBIDDEN_MULTILINE.test(text);
 }
-/**
- * Controls OR direction-override invisibles — the full disguise kit. For
- * text that becomes standing authority or a task identity (setup commands,
- * imported issue titles): a title reading "fix docs" while spelled
- * backwards is not a title, it is a costume.
- */
 export function hasDisguisedText(text) {
     return FORBIDDEN_MULTILINE.test(text) || FORBIDDEN_INVISIBLES.test(text);
 }
-/**
- * A parked decision, read against its contract (src/contracts/decision.ts): fail closed, every problem at once, each
- * naming its path (`options[1].reversible: required`) under the reason code the repair turn, incidents and tests have
- * always used (`missing-reversible`). A decision written without `version` reads as it always did.
- */
 export function parseDecision(raw) {
     if (Buffer.byteLength(raw, "utf8") > LIMITS.payload) {
         return refuse("too-large", `payload: over ${LIMITS.payload} bytes — one screen does not need that`);
@@ -117,12 +64,10 @@ export function parseDecision(raw) {
             options: payload.options.map(option => ({ id: option.id, label: option.label.trim(), consequence: option.consequence.trim(), reversible: option.reversible })),
             recommendation: recommendedId(payload.recommendation),
             assignee: payload.assignee === undefined || payload.assignee === null ? null : payload.assignee.trim(),
-            // Normalized so the store's lexicographic-comparison invariant holds.
             deadline: payload.deadline === undefined || payload.deadline === null ? null : new Date(Date.parse(payload.deadline)).toISOString(),
         },
     };
 }
-/** The reason code a contract issue has always had: `missing-recap`, `too-few-options`, `bad-option-id`. */
 function decisionReasonOf(issue) {
     const at = issue.path;
     const text = (field) => (issue.kind === "too-long" ? `${field}-too-long` : `missing-${field}`);
@@ -146,14 +91,7 @@ function decisionReasonOf(issue) {
     return text(at);
 }
 const decisionProblemOf = (issue) => ({ reason: decisionReasonOf(issue), message: issue.line });
-/** True when `problems` name `field` or anything under it. */
 const touched = (problems, field) => problems.some(problem => problem.message.startsWith(`${field}:`) || problem.message.startsWith(`${field}[`) || problem.message.startsWith(`${field}.`));
-/**
- * The rules JSON Schema cannot state, in plain code with named errors: text not blank once trimmed and free of control
- * characters (a label or assignee on one line), unique option ids, a recommendation naming one of them, and a deadline
- * that is a timestamp. Fields the contract already refused are skipped, so every problem is reported once and all at
- * once.
- */
 function decisionRuleProblems(body, contract) {
     const problems = [];
     const text = (value, path, slug, oneLine) => {
@@ -194,7 +132,6 @@ function decisionRuleProblems(body, contract) {
     }
     return problems;
 }
-/** The option id a recommendation names: a bare id, or the id before the first ":" in "<id>: why". */
 function recommendedId(recommendation) {
     const colon = recommendation.indexOf(":");
     return (colon === -1 ? recommendation : recommendation.slice(0, colon)).trim();
@@ -214,14 +151,9 @@ function truncate(text, at) {
 }
 export const HANDOFF_VERSION = 2;
 export const HANDOFF_CONCLUSION_CAP = 600;
-/** The handoff's whole-file and list caps, exported so the brief states
- * exactly what the parser holds it to (raw authority repair). */
 export const HANDOFF_PAYLOAD_CAP = 16 * 1024;
 export const HANDOFF_LIST_CAP = 8;
 export const HANDOFF_ITEM_CAP = 240;
-/** Agent prose is display material, not authority. Once the structural
- * outcome is valid, excess verbosity is compacted deterministically rather
- * than throwing away completed code and paying for a whole new attempt. */
 function compactHandoffText(value, cap) {
     const clean = value.replace(/\s+/g, " ").trim();
     if (clean.length <= cap)
@@ -297,16 +229,6 @@ export function parseHandoff(raw) {
         },
     };
 }
-/**
- * The compact error a repair turn is resumed with: every problem by name,
- * then the one instruction. Written for an agent that already holds the
- * context — it needs the list of what failed, not the theory of why.
- */
-/**
- * Every unattended agent runs headless (run 2085): its turn ending IS the
- * process exiting, so a command left in the background, a wakeup or a loop
- * never gets a second turn — the attempt just ends without its handoff.
- */
 export const HEADLESS_RULE = [
     "- You run headless: run every command in the foreground and wait for it,",
     "  however long it takes. Never background a command to wait on it, and",

package/dist/demo-chat.js

@@ -1,14 +1,9 @@
-/**
- * Chat in `toolroll demo`: the scripted lead's conversation (src/demo.ts),
- * rendered as plain server HTML with native forms. One small script keeps a
- * running build's progress live; without it the page still works by reload.
- */
 import { START_COMMAND } from "./first-run.js";
 import { html, postForm } from "./html.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"];
 function hint() {
-    return html `<section class="demo-hint" aria-label="Get started"><h2 class="demo-hint-title">What should the crew do?</h2><p class="demo-hint-sub">Ask for something, like “fix the flaky refund test”, or start from one of these.</p>${postForm("/chat/demo/ask", SUGGESTIONS.map(one => html `<button type="submit" name="message" value="${one}">${one}</button>`), { attrs: { class: "demo-suggestions" } })}</section>`;
+    return html `<section class="demo-hint" aria-label="Get started"><h2 class="demo-hint-title">What should we work on?</h2><p class="demo-hint-sub">Ask for something, like “fix the flaky refund test”, or start from one of these.</p>${postForm("/chat/demo/ask", SUGGESTIONS.map(one => html `<button type="submit" name="message" value="${one}">${one}</button>`), { attrs: { class: "demo-suggestions" } })}</section>`;
 }
 function planCard(exchange) {
     const plan = exchange.plan;
@@ -38,7 +33,6 @@ function resultCard(exchange, result) {
     if (result === null)
         return html `<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 = html `<span class="badge${headline === "Complete" ? " demo-complete" : headline === "Ready for review" ? " demo-ready" : ""}" data-headline="${headline}">${headline}</span>`;
@@ -48,14 +42,13 @@ function resultCard(exchange, result) {
         : html `<p class="meta"><a href="${result.taskHref}">Open in Tasks</a></p>`;
     return html `<section class="card demo-result" id="demo-${exchange.id}-work" aria-label="Result"><p class="demo-state">${status}<span class="meta">${exchange.plan.project}</span></p><h2>${exchange.plan.title}</h2><p>${exchange.plan.conclusion}</p><p class="meta">${summary}</p>${actions}${result.diff === null ? "" : html `<details class="demo-evidence"${exchange.state === "ready" ? html ` open` : ""}><summary>Changes</summary><pre class="demo-diff">${diffHtml(result.diff)}</pre></details>`}${result.checkLog === null ? "" : html `<details class="demo-evidence"><summary>Check log</summary><pre class="demo-log">${result.checkLog}</pre></details>`}${result.screenshot === null ? "" : html `<details class="demo-evidence"><summary>Screenshot</summary><figure><img src="${result.screenshot.href}" alt="${result.screenshot.caption}" width="960" height="600"><figcaption class="meta">${result.screenshot.caption}</figcaption></figure></details>`}</section>`;
 }
-/** The conversation itself; the live script swaps this region in place. */
 export function demoThreadHtml(exchanges, resultOf) {
     if (exchanges.length === 0)
         return hint();
     return html `${exchanges.map(exchange => {
         const parts = [
             html `<div class="demo-said demo-you"><p>${exchange.asked}</p></div>`,
-            html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">L</span>Lead</p><p>${exchange.reply}</p></div>`,
+            html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">T</span>Toolroll</p><p>${exchange.reply}</p></div>`,
             planCard(exchange),
         ];
         if (exchange.state === "working")
@@ -63,19 +56,15 @@ export function demoThreadHtml(exchanges, resultOf) {
         if (exchange.state === "ready" || exchange.state === "complete" || exchange.state === "sent-back")
             parts.push(resultCard(exchange, resultOf(exchange)));
         if (exchange.state === "complete") {
-            parts.push(html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">L</span>Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, html `<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>${START_COMMAND}</code></pre><p class="meta">It opens in your browser, already signed in.</p></section>`);
+            parts.push(html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">T</span>Toolroll</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, html `<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>${START_COMMAND}</code></pre><p class="meta">It opens in that terminal. Press w there to open it in the browser.</p></section>`);
         }
         return html `<article class="demo-turn" id="demo-${exchange.id}">${parts}</article>`;
     })}`;
 }
 export function demoChatHtml(input) {
     const working = input.exchanges.some(one => one.state === "working");
-    return html `<div class="demo-chat${input.exchanges.length === 0 ? " demo-chat--empty" : ""}">${input.problem === null ? "" : html `<p class="problem" role="alert">${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.resultOf)}</div>${postForm("/chat/demo/ask", html `<label for="demo-message" class="so-sr-only">Message the lead</label><div class="demo-composer-card"><textarea id="demo-message" name="message" rows="1" maxlength="500" placeholder="Ask the lead for a change" required aria-describedby="demo-composer-hint"></textarea><div class="demo-composer-bar"><span id="demo-composer-hint">Enter to send · Shift + Enter for a new line</span><button type="submit" class="demo-primary demo-send" aria-label="Send"><svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg></button></div></div>`, { attrs: { class: "demo-composer" } })}</div>`;
+    return html `<div class="demo-chat${input.exchanges.length === 0 ? " demo-chat--empty" : ""}">${input.problem === null ? "" : html `<p class="problem" role="alert">${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.resultOf)}</div>${postForm("/chat/demo/ask", html `<label for="demo-message" class="so-sr-only">Ask for a change</label><div class="demo-composer-card"><textarea id="demo-message" name="message" rows="1" maxlength="500" placeholder="Ask for a change" required aria-describedby="demo-composer-hint"></textarea><div class="demo-composer-bar"><span id="demo-composer-hint">Enter to send · Shift + Enter for a new line</span><button type="submit" class="demo-primary demo-send" aria-label="Send"><svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg></button></div></div>`, { attrs: { class: "demo-composer" } })}</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;

package/dist/demo-sign-in.js

@@ -0,0 +1,77 @@
+import { spawn as spawnChild } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SIGN_IN_LINK_MS, SIGN_IN_LINK_PATH } from "./server/session.js";
+export function demoLoopbackOrigin(address) {
+    if (address === null || typeof address === "string")
+        return null;
+    if (!Number.isInteger(address.port) || address.port < 1 || address.port > 65_535)
+        return null;
+    if (address.address === "127.0.0.1")
+        return `http://127.0.0.1:${address.port}`;
+    if (address.address === "::1")
+        return `http://[::1]:${address.port}`;
+    return null;
+}
+export function demoSignInLink(server, account, caller) {
+    if (!caller.stdin || !caller.stdout || caller.agent || caller.json)
+        return null;
+    const origin = demoLoopbackOrigin(server.address());
+    if (origin === null)
+        return null;
+    const path = server.mintSignInLink(account);
+    if (path === null || !path.startsWith(SIGN_IN_LINK_PATH))
+        return null;
+    return `${origin}${path}`;
+}
+export function writeSignInPage(parent, link) {
+    const dir = mkdtempSync(join(parent, "sign-in-"));
+    chmodSync(dir, 0o700);
+    const file = join(dir, "open.html");
+    const attribute = link.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+    writeFileSync(file, `<!doctype html><meta charset="utf-8"><meta name="referrer" content="no-referrer">`
+        + `<meta http-equiv="refresh" content="0;url=${attribute}"><title>Toolroll</title>`
+        + `<script>location.replace(${JSON.stringify(link).replace(/</g, "\\u003c")})</script><p>Opening Toolroll…</p>\n`, { mode: 0o600 });
+    chmodSync(file, 0o600);
+    return file;
+}
+export function removeSignInPage(file) {
+    rmSync(join(file, ".."), { recursive: true, force: true });
+}
+export function openSignInPage(file, spawn = spawnChild, platform = process.platform) {
+    const command = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : null;
+    if (command === null)
+        return false;
+    try {
+        spawn(command, [file], { detached: true, stdio: "ignore" }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function removeSignInPageWhenSpent(store, file, account, options = {}) {
+    const sinceRow = store.handle.prepare("SELECT coalesce(max(id), 0) AS id FROM action_ledger").get();
+    const since = Number(sinceRow?.["id"] ?? 0);
+    const spent = store.handle.prepare("SELECT 1 FROM action_ledger WHERE id > ? AND source = 'sign-in' AND actor = ? AND action = 'signed in' AND outcome = 'one-time link' LIMIT 1");
+    let done = false;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        clearInterval(timer);
+        clearTimeout(expiry);
+        removeSignInPage(file);
+    };
+    const timer = setInterval(() => { try {
+        if (spent.get(since, account) !== undefined)
+            finish();
+    }
+    catch {
+        finish();
+    } }, options.everyMs ?? 500);
+    const expiry = setTimeout(finish, options.expiresMs ?? SIGN_IN_LINK_MS);
+    timer.unref?.();
+    expiry.unref?.();
+    return finish;
+}