toolroll 0.9.103 → 0.9.105

package/dist/cli.js

@@ -1,15 +1,4 @@
 #!/usr/bin/env node
-/**
- * The command.
- *
- * `toolroll` with no arguments reads the repositories below the working
- * directory and prints what is in flight. It writes nothing, starts nothing,
- * and asks nothing. Everything it knows comes from git and from the operator's
- * own filesystem.
- *
- * `--json` exists because half the intended audience is an agent, and an agent
- * should not have to parse a column layout.
- */
 import { existsSync, lstatSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
@@ -18,7 +7,6 @@ import { configPath, loadRepos } from "./repos.js";
 import { addedWords, admitProject, commandLineActor, consoleRunning, proveProjectRoot, registryBeside, releaseProject } from "./project-admission.js";
 import { envValue } from "./names.js";
 import { CAPABILITIES, ENVELOPE_VERSION, capturedEnvelope, onEnvelopeCaptured, resetCapturedEnvelope } from "./envelope.js";
-// Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
 import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
 import { applyClaudeCodeInstall, applyInstall, contextBlock, defaultClaudeCodeSkillDir, planClaudeCodeInstall, planInstall, } from "./skills.js";
 import { GUIDES, guideNamed } from "./guides.js";
@@ -37,17 +25,15 @@ import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } fr
 import { openStore, openStoreReadOnly, databasePath } from "./store.js";
 import { renderReport, renderPulls, renderGraph } from "./render.js";
 import { DEFAULT_MAX_DEPTH } from "./scan.js";
-import { HELP, INTERNALS_HELP } from "./cli-help.js";
+import { HELP, INTERNALS_HELP, SCAN_HELP } from "./cli-help.js";
 import { withTaskAlias } from "./task-aliases.js";
 import { quickAnswer } from "./cli-fast.js";
 import { BIN_NAME, chooseTarget, planLink, applyLink, planUnlink, applyUnlink, } from "./link.js";
 const USAGE_EXIT = 2;
-/** The queue's commands live in operate.ts, the largest module graph here: loaded when one of them runs, not before. */
 async function runOperate(command, argv, write, options) {
     const operate = await import("./operate.js");
     return operate.runOperate(command, argv, write, options);
 }
-/** The top-level usage text (cli-help.ts), re-exported where it always lived. */
 export { HELP };
 export function parseArgs(argv) {
     const roots = [];
@@ -108,13 +94,10 @@ export function parseArgs(argv) {
         },
     };
 }
-/** The commands that operate the queue rather than report on the world. */
 export const OPERATE_COMMANDS = new Set([
     "up",
     "evals",
-    // Only `lead token` reaches here; the central service's lead verbs answer first.
     "lead",
-    // Only `release approve` reaches here: every other `release` form is release-cli.ts, routed before this set.
     "release",
     "onboard",
     "status",
@@ -142,7 +125,6 @@ export const OPERATE_COMMANDS = new Set([
     "memory",
     "flaky",
     "card",
-    // Follow-through (follow-through-cli.ts): findings and saved provider failures.
     "finding",
     "captures",
     "models",
@@ -188,13 +170,6 @@ export const OPERATE_COMMANDS = new Set([
     "webhook",
     "sync",
 ]);
-/**
- * Strip `-o <file>` / `--output <file>` before dispatch. The flag belongs to
- * the entry point, not to any one command: after the command runs, whatever
- * envelope it serialized is copied to the file, so an agent reads its answer
- * from a path instead of scraping a terminal. Requires `--json`, because the
- * file receives the machine envelope and nothing else does.
- */
 export function extractOutputFlag(argv) {
     const args = [];
     let outputFile;
@@ -229,17 +204,11 @@ export async function main(argv, write = line => console.log(line), mainOptions
         write("-o requires --json — the output file receives the machine envelope");
         return USAGE_EXIT;
     }
-    // A new API token is shown once, on screen: never saved to a file by the entry point.
     if (outputFile !== undefined && args.find(one => !one.startsWith("-")) === "tokens") {
         write("-o isn't used with tokens: a new token is shown once, never saved to a file");
         return USAGE_EXIT;
     }
     resetCapturedEnvelope();
-    // Long-running commands (serve, up) emit their ONE envelope at startup,
-    // when its URL is useful — so -o is preflighted BEFORE dispatch (an
-    // unwritable target refuses up front) and written the moment the
-    // envelope is captured, through a hook that never throws into the
-    // command (arc 2 findings 23/30).
     const firstWord = args.find(one => !one.startsWith("-"));
     const earlyFlush = outputFile !== undefined && (firstWord === "serve" || firstWord === "up");
     let earlyFlushProblem = null;
@@ -283,9 +252,6 @@ export async function main(argv, write = line => console.log(line), mainOptions
     if (outputFile !== undefined && !earlyFlush) {
         const captured = capturedEnvelope();
         if (captured !== null) {
-            // Envelopes can carry one-time credentials (runner register, approver
-            // add), so the file is written 0600 and never through a symlink or
-            // onto a non-regular target (Codex M5-M8 audit, IV-8).
             try {
                 const existing = lstatSync(outputFile, { throwIfNoEntry: false });
                 if (existing !== undefined) {
@@ -305,20 +271,15 @@ export async function main(argv, write = line => console.log(line), mainOptions
     }
     return code;
 }
-/** What every former `toolroll routine …` command says now (v115; kept for this release only). */
 export const ROUTINES_MOVED = "Routines are now scheduled flows: see `toolroll flows list` (your routines were moved there).";
 function routinesMoved(argv, write) {
     write(argv.includes("--json") ? envelopeJson({ ok: true, command: "routine", message: ROUTINES_MOVED }) : ROUTINES_MOVED);
     return 0;
 }
 async function dispatch(argv, write, mainOptions) {
-    // People's names for task commands (task send-back, retry, recheck) are the commands they name, before anything else.
     argv = withTaskAlias(argv);
-    // v115: routines became scheduled flows. Every old `routine …` invocation answers with one line pointing there —
-    // hidden from help and the contract, before anything remote or local opens, changing nothing.
     if (argv[0] === "routine")
         return routinesMoved(argv, write);
-    // D5: the central team CLI and native sessions are gone; each old invocation says so and changes nothing.
     const connectOptions = mainOptions.connect ?? mainOptions.remote;
     const removed = removedCommand(argv, () => hasCentralProfile(connectOptions ?? {}));
     if (removed !== null) {
@@ -326,16 +287,12 @@ async function dispatch(argv, write, mainOptions) {
         write(argv.includes("--json") ? envelopeJson({ ok: false, command: removed.named, reason: "removed", message }) : message);
         return 2;
     }
-    // A saved API token sends commands marked remote to the central server, before anything local opens.
-    // Command families below load when their command runs, so one command never pays for the others.
     if (argv[0] === 'health')
         return (await import("./health-cli.js")).runHealthCommand(argv.slice(1), write, mainOptions.connect ?? mainOptions.remote);
-    // The machine and agent commands, listed apart so top-level help stays about the work (each still runs by name).
     if (argv[0] === 'internals' && argv.slice(1).every(arg => arg === '--help' || arg === '-h')) {
         write(INTERNALS_HELP);
         return 0;
     }
-    // This computer's own service, read here and never on a central server.
     if (argv[0] === 'doctor')
         return (await import("./doctor.js")).runDoctorCommand(argv.slice(1), write);
     const central = await maybeRunRemoteCommand(argv, mainOptions.remote ?? mainOptions.connect);
@@ -350,8 +307,6 @@ async function dispatch(argv, write, mainOptions) {
         argv = argv.filter(arg => arg !== "--local");
     const [first, ...rest] = argv;
     if (first === "help") {
-        // The bare word, because somebody will type it — never scanned as a
-        // path named "help".
         write(HELP);
         return 0;
     }
@@ -360,7 +315,6 @@ async function dispatch(argv, write, mainOptions) {
     }
     if (first === "update")
         return (await import("./toolroll-update-cli.js")).runUpdateCommand(rest, write, mainOptions.update);
-    // `toolroll release approve`: a person's approval, with the operate commands' own credential prompt and context.
     if (first === "release" && rest[0] === "approve")
         return runOperate("release", rest, write, mainOptions.operate ?? {});
     if (first === "release") {
@@ -370,7 +324,7 @@ async function dispatch(argv, write, mainOptions) {
     if (first === "contract")
         return runContractCommand(rest, write);
     if (first === "demo")
-        return runDemoCommand(rest, write);
+        return runDemoCommand(rest, write, mainOptions.demo);
     if (first === "skills")
         return runSkillsCommand(rest, write);
     if (first === "repos")
@@ -382,8 +336,6 @@ async function dispatch(argv, write, mainOptions) {
     if (first !== undefined && OPERATE_COMMANDS.has(first)) {
         return runOperate(first, rest, write, mainOptions.operate ?? {});
     }
-    // Easy start (A): bare `toolroll` (or with --web / --project-root) at a person's terminal — no --json, not under a
-    // coding agent — starts this computer's Toolroll and opens the terminal UI. Anything else keeps its behaviour below.
     if (first !== "scan" && first !== "--json" && easyStartArgs(argv) !== null) {
         const terminal = mainOptions.easyStart?.terminal ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
         const agent = terminal && (mainOptions.easyStart?.underAgent ?? underAgent(process.env));
@@ -398,8 +350,8 @@ async function dispatch(argv, write, mainOptions) {
             return easy.runEasyStart("start", easyStartArgs(argv), { ...seams, ...mainOptions.easyStart?.seams });
         }
     }
-    // Cockpit B1: the scan by name, and bare `toolroll` in a repository starting (or attaching to) its console.
-    if (first === "scan")
+    const scanNamed = first === "scan";
+    if (scanNamed)
         argv = rest;
     else if (isBareInvocation(argv)) {
         const databaseFile = mainOptions.operate?.databaseFile ?? databasePath(process.env, homedir());
@@ -423,12 +375,10 @@ async function dispatch(argv, write, mainOptions) {
     }
     const { options } = parsed;
     if (options.help) {
-        write(HELP);
+        write(scanNamed ? SCAN_HELP : HELP);
         return 0;
     }
     const now = new Date();
-    // An enrolled list is a decision the operator already made; honour it unless
-    // they asked otherwise by naming paths or passing --all.
     const enrolled = await loadRepos(configFile());
     if ("error" in enrolled) {
         write(enrolled.error);
@@ -438,12 +388,6 @@ async function dispatch(argv, write, mainOptions) {
         return reportEnrolled(enrolled.repos, options, now, write);
     }
     const { present, missing } = partitionRoots(options.roots, existsSync);
-    // A path that does not exist is a typo, not an empty search, and saying
-    // "no repositories found" about it would be answering a question we never
-    // asked. Warnings go inside the envelope in JSON mode so it stays
-    // parseable — and when NOTHING was scannable the envelope says ok:false
-    // (aligned with `pulls`), because an all-missing scan that reported
-    // ok:true let a typo'd command read as success.
     if (present.length === 0) {
         write(options.json
             ? renderMissingJson(options.roots, missing, now)
@@ -465,14 +409,6 @@ async function dispatch(argv, write, mainOptions) {
     write(output);
     return 0;
 }
-/**
- * Pull requests and issues, unless the operator asked to stay local.
- *
- * Reading them is the difference between "every branch in flight" and "every
- * branch, pull request and issue in flight", which is what the milestone asks
- * for — but it is also the only part of this report that touches the network,
- * so it is bounded and `--local` turns it off entirely.
- */
 async function maybeReadRemote(repos, options) {
     if (options.local)
         return undefined;
@@ -482,11 +418,6 @@ async function maybeReadRemote(repos, options) {
 function configFile() {
     return configPath(process.env, homedir());
 }
-/**
- * Report the enrolled repositories directly. A path that has since been moved
- * or deleted is named rather than silently dropped — a list that quietly
- * shrinks is worse than one that tells you it is stale.
- */
 async function reportEnrolled(repos, options, now, write) {
     const { present, missing } = partitionRoots(repos, existsSync);
     const snapshots = await inspectAll(present, { dirty: options.dirty });
@@ -514,13 +445,6 @@ export function partitionRoots(roots, exists) {
         missing: roots.filter(root => !exists(root)),
     };
 }
-/**
- * A missing root that was typed as a bare word — no separator, no leading
- * dot, no home shorthand — is as likely a mistyped COMMAND as a missing
- * folder, and after `resolve()` the two are indistinguishable. The message
- * names both readings instead of guessing (Codex round-4 finding 18);
- * path-shaped roots keep the plain missing-path sentence.
- */
 function describeMissing(missing, rawRoots = [], roots = []) {
     const rawOf = new Map();
     roots.forEach((resolved, index) => {
@@ -531,11 +455,10 @@ function describeMissing(missing, rawRoots = [], roots = []) {
     const bareWord = (raw) => raw !== undefined && !/[/\\~]/.test(raw) && !raw.startsWith(".");
     return missing
         .map(root => bareWord(rawOf.get(root))
-        ? `${root} does not exist — if you meant a command, \`toolroll --help\` lists them; to scan a folder, give a path that exists.`
+        ? `${root} does not exist — if you meant a command, \`toolroll --help\` and \`toolroll internals\` list them; to scan a folder, give a path that exists.`
         : `${root} does not exist — check the path.`)
         .join("\n");
 }
-/** The all-missing scan envelope: honest ok:false with the scan fields kept. */
 function renderMissingJson(roots, missingRoots, now) {
     return envelopeJson({
         ok: false,
@@ -549,16 +472,7 @@ function renderMissingJson(roots, missingRoots, now) {
         repos: [],
     });
 }
-/**
- * `repos` with no arguments lists what is connected and shows how to change
- * it, so the way to adjust the list is visible at the moment you are looking
- * at it — rather than being something you have to remember a flag for.
- */
 async function runReposCommand(argv, write, onboard) {
-    // `repos` honors the machine contract like everything else (audit TG-3):
-    // --json answers with one envelope, whatever the outcome.
-    // The lead adds with its token (--token <t>, --token=<t> or TOOLROLL_LEAD_TOKEN); the owner needs none. A token is
-    // random base64url and may start with "--": it is the next argument, whatever it looks like.
     const tokenAt = argv.findIndex(argument => argument === "--token" || argument.startsWith("--token="));
     const tokenInline = tokenAt !== -1 && argv[tokenAt] !== "--token";
     const tokenFlag = tokenAt === -1 ? undefined : tokenInline ? argv[tokenAt].slice("--token=".length) : argv[tokenAt + 1];
@@ -574,7 +488,6 @@ async function runReposCommand(argv, write, onboard) {
     }
     const databaseFile = databasePath(process.env, homedir());
     const file = registryBeside(databaseFile);
-    // A dash-led token is the token, unless it is exactly one of this command's flags (never swallowed).
     if (tokenAt !== -1 && (tokenFlag === undefined || tokenFlag === "" || (!tokenInline && ["--json", "--remote", "--token"].includes(tokenFlag)))) {
         const message = "--token needs the lead token";
         write(json ? envelopeJson({ ok: false, command: `repos ${action ?? ""}`.trim(), reason: "usage", message }) : message);
@@ -582,10 +495,6 @@ async function runReposCommand(argv, write, onboard) {
     }
     const envLead = envValue(process.env, "LEAD_TOKEN");
     const leadToken = tokenFlag ?? (envLead === undefined || envLead === "" ? undefined : envLead);
-    // Dispatched BEFORE the registry load (verification finding 3): a
-    // malformed registry must not mask this command's own parsing, its
-    // read-only preview, or its taxonomy — enrollment reads the registry
-    // through the locked primitive at the moment it writes.
     if (action === "add-from-github") {
         return addFromGithubCommand(bare.slice(1), json, write, { databaseFile, registryFile: file, ...(leadToken === undefined ? {} : { leadToken }) }, onboard);
     }
@@ -613,7 +522,6 @@ async function runReposCommand(argv, write, onboard) {
         write(json ? envelopeJson({ ok: false, command: "repos", reason: "usage", message }) : message);
         return USAGE_EXIT;
     }
-    // `repos add` with no path means the repository you are standing in.
     const targets = (paths.length > 0 ? paths : [process.cwd()]).map(path => resolve(path));
     const lines = [];
     const said = {};
@@ -631,7 +539,6 @@ async function runReposCommand(argv, write, onboard) {
     }
     return code;
 }
-/** Open this installation's database as the owner (or its lead) for one addition or removal. */
 async function withAdmission(where, write, said, body) {
     let store;
     try {
@@ -677,13 +584,10 @@ function listRepos(repos, file, write, remotes) {
     write(`  ${file}`);
     return 0;
 }
-/** The exit code an admission failure answers with: a folder problem is the caller's to fix (usage). */
 function admissionExit(reason) {
     return reason === "not-git" || reason === "unavailable" ? USAGE_EXIT : 1;
 }
 async function addToRepos(admission, targets, write, said, remoteUrl) {
-    // Every folder is proved before anything is written: one that is not a
-    // repository fails here, not later and further away.
     let refused = false;
     for (const path of targets) {
         const proved = await proveProjectRoot(path);
@@ -701,8 +605,6 @@ async function addToRepos(admission, targets, write, said, remoteUrl) {
     for (const path of targets) {
         const admitted = await admitProject(admission.store, { registryFile: admission.registryFile, path, actor: admission.actor, now, captureOrigin: true, ...(remoteUrl === undefined ? {} : { remoteUrl }) });
         if (!admitted.ok) {
-            // The updater's own taxonomy survives (verification finding 4): a held
-            // lock or a malformed registry is an operational fact, never "usage".
             said.reason = admitted.reason;
             said.projects = projects;
             write(admitted.message);
@@ -734,14 +636,6 @@ async function removeFromRepos(admission, targets, write, said) {
     said.projects = projects;
     return 0;
 }
-/**
- * `repos add-from-github <owner/name>` — the console onboarding ceremony's
- * CLI twin (onboarding rounds 1-4; named in the ledger as the companion):
- * strict parse, gh preview BEFORE any write, the same large-repo gate, the
- * claim-first clone, and enrollment through the ONE locked registry
- * primitive. Preview by default; --yes clones. Windows refuses like the
- * console does — tree death cannot be proven there.
- */
 async function addFromGithubCommand(argv, json, write, where, onboard) {
     const command = "repos add-from-github";
     const answer = (reason, message, code, extra = {}) => {
@@ -797,8 +691,6 @@ async function addFromGithubCommand(argv, json, write, where, onboard) {
     }
     if (!lstatSync(root).isDirectory())
         return answer("usage", `--root ${rootGiven} is not a directory`, USAGE_EXIT);
-    // The platform refusal comes AFTER the invocation is proved well-formed
-    // (verification finding 3): a Windows user still learns their typo first.
     if (process.platform === "win32") {
         return answer("platform", "adding from GitHub is not supported on Windows yet — the clone's process tree cannot be proven dead there", 1);
     }
@@ -834,7 +726,6 @@ async function addFromGithubCommand(argv, json, write, where, onboard) {
     if (large && !largeOk) {
         return answer("large", `${previewed.preview.nameWithOwner} is large or of unknown size (${size}) — add --large-ok to clone it anyway; nothing was written`, 3);
     }
-    // Who may add is settled before anything is cloned.
     const said = {};
     const problems = [];
     const allowed = await withAdmission(where, line => problems.push(line), said, async () => 0);
@@ -849,7 +740,6 @@ async function addFromGithubCommand(argv, json, write, where, onboard) {
     if (cloned.target !== target) {
         return answer("malformed", "the clone answered with a different path than the preview promised — refused; nothing was connected", 1);
     }
-    // The clone joins through the same admission as `repos add` and the console.
     let words = "";
     const code = await withAdmission(where, line => problems.push(line), said, async (admission) => {
         const now = new Date();
@@ -873,12 +763,6 @@ async function addFromGithubCommand(argv, json, write, where, onboard) {
     write("Large-file objects were not downloaded — run `git lfs pull` in the repository when you need them.");
     return 0;
 }
-/**
- * `pulls` reads the same repositories the default report does, because the
- * question "what is waiting on me" is asked about the same set of work. It is
- * a separate command rather than part of the report because it costs a network
- * round trip per repository, and the default report is meant to stay local.
- */
 async function runPullsCommand(argv, write) {
     const json = argv.includes("--json");
     const unknown = argv.find(argument => argument.startsWith("-") && argument !== "--json");
@@ -904,12 +788,6 @@ async function runPullsCommand(argv, write) {
         : renderPulls(groups, { now: new Date() }));
     return 0;
 }
-/**
- * `graph` answers "what work graph is already here", which is the question
- * standing between discovery and anything autonomous. It reads the same
- * repositories the report does, and like everything else in M0 it writes
- * nothing: detection is not authorization.
- */
 async function runGraphCommand(argv, write) {
     const json = argv.includes("--json");
     const unknown = argv.find(argument => argument.startsWith("-") && argument !== "--json");
@@ -927,14 +805,7 @@ async function runGraphCommand(argv, write) {
         return USAGE_EXIT;
     }
     const detections = await detectGraphs(present);
-    // An enrolled backend outranks anything detection would have picked — the
-    // ladder's first rung, and now reachable because grants are persisted. An
-    // operator who already said which one must not be re-asked because a second
-    // tracker turned up somewhere else on the machine.
     const enrolled = enrolledBackend(present);
-    // The envelope carries the choice and the setup commands, not just the raw
-    // detections: an agent reading this has the same question a person does —
-    // what is here, what would you use, and what would I have to run.
     const envelope = {
         detections,
         choice: chooseBackend(detections, enrolled === undefined ? {} : { enrolled }),
@@ -945,13 +816,6 @@ async function runGraphCommand(argv, write) {
         : renderGraph(detections, enrolled === undefined ? {} : { enrolled }));
     return 0;
 }
-/**
- * The backend enrolled for any of these repositories, if one is.
- *
- * Read-only and failure-tolerant on purpose: `graph` is a reporting command,
- * and a queue that cannot be opened must degrade to plain detection rather
- * than take the report down with it.
- */
 function enrolledBackend(repos) {
     const store = openStoreReadOnly(databasePath(process.env, homedir()));
     if (store === null)
@@ -959,12 +823,9 @@ function enrolledBackend(repos) {
     try {
         const wanted = new Set(repos);
         const grant = store.listGrants().find((one) => wanted.has(one.repo));
-        // A grant may name the built-in store, which detection never reports, so
-        // only a backend the graph report knows about is passed through.
         return grant !== undefined && isBackendKind(grant.backend) ? grant.backend : undefined;
     }
     catch {
-        // An older or incomplete layout degrades to detection, never a migration.
         return undefined;
     }
     finally {
@@ -974,7 +835,6 @@ function enrolledBackend(repos) {
 function isBackendKind(name) {
     return Object.prototype.hasOwnProperty.call(GRAPH_LABELS, name);
 }
-/** null means the configuration could not be read, and was already reported. */
 async function defaultPullTargets(write) {
     const enrolled = await loadRepos(configFile());
     if ("error" in enrolled) {
@@ -1002,10 +862,6 @@ export function parseLinkArgs(argv) {
     }
     return { args };
 }
-/**
- * Both halves show their work before doing it. Nothing changes without --yes,
- * which is the same courtesy this tool extends to `bd init`.
- */
 async function runLinkCommand(command, argv, write, binSource) {
     const parsed = parseLinkArgs(argv);
     if ("error" in parsed) {
@@ -1018,8 +874,6 @@ async function runLinkCommand(command, argv, write, binSource) {
         home: homedir(),
         ...(to === undefined ? {} : { override: to }),
     });
-    // Only `link` needs something to point at. Demanding a build before you are
-    // allowed to uninstall would strand anyone whose dist/ has been cleaned.
     if (command === "unlink")
         return runUnlink(choice.dir, yes, write);
     const resolved = binSource === undefined ? resolveBinSource() : { source: binSource };
@@ -1029,10 +883,6 @@ async function runLinkCommand(command, argv, write, binSource) {
     }
     return runLink(resolved.source, choice, yes, write);
 }
-/**
- * A link must point at the built command. Running through tsx puts us in
- * src/, so resolve across to dist/ rather than linking a file node cannot run.
- */
 function resolveBinSource() {
     const here = fileURLToPath(import.meta.url);
     const source = here.endsWith(".ts") ? resolve(dirname(here), "..", "dist", "cli.js") : here;
@@ -1076,11 +926,6 @@ async function runLink(source, choice, yes, write) {
     }
     return 0;
 }
-/**
- * The instruction has to be one the operator can paste into the shell they are
- * actually in. `export` is meaningless in PowerShell, and the separator between
- * PATH entries is not `:` everywhere.
- */
 function describePathFix(dir) {
     if (process.platform === "win32") {
         return [
@@ -1113,16 +958,6 @@ async function runUnlink(dir, yes, write) {
     write("Removed.");
     return 0;
 }
-/**
- * `skills install`: with --claude-code, install this binary's lead guides
- * in the user's Claude Code skills directory. Without it, retain the older
- * repository-local Agent Skills entry and optional managed AGENTS.md block.
- * Both paths preview by default, write only with --yes, and refuse files
- * they do not own.
- */
-/** The skills subcommands and their EXACT flag vocabularies — consulted
- * by the parser above and compared verbatim by the command guide's tests
- * (arc-5 review, finding 5). */
 export const SKILLS_ACTIONS = ["install", "list", "get"];
 export const SKILLS_FLAGS = {
     install: { json: "flag", yes: "flag", "claude-code": "flag", dir: "value", "write-context": "flag", repo: "value" },
@@ -1139,9 +974,6 @@ function runSkillsCommand(argv, write) {
     if (action === undefined || !SKILLS_ACTIONS.includes(action)) {
         return usage("`toolroll skills install --claude-code [--dir <path>] [--yes]` · `skills install [--repo <path>] [--write-context] [--yes]` · `skills list` · `skills get <name>` — all take --json");
     }
-    // Exact per-action vocabularies (arc-5 review, finding 5): an unknown
-    // flag, a flagless --repo, or a stray positional is a usage refusal
-    // here, never a silent ignore.
     const allowed = SKILLS_FLAGS[action];
     const positionals = [];
     for (let index = 0; index < argv.length; index++) {
@@ -1181,8 +1013,6 @@ function runSkillsCommand(argv, write) {
             return usage("`toolroll skills get <name>` — one guide name from `skills list`");
         const guide = guideNamed(name);
         if (guide === null) {
-            // The command was valid and the named guide is absent: exit 3, the
-            // answer is no — same shape as an unknown task or template.
             write(json
                 ? envelopeJson({ ok: false, command: "skills get", reason: "unknown-skill", message: `no guide named ${name} — the guides are: ${GUIDES.map(one => one.name).join(", ")}` })
                 : `no guide named ${name} — the guides are: ${GUIDES.map(one => one.name).join(", ")}`);
@@ -1192,11 +1022,9 @@ function runSkillsCommand(argv, write) {
             write(envelopeJson({ ok: true, command: "skills get", name: guide.name, title: guide.title, content: guide.content }));
             return 0;
         }
-        // Raw markdown alone — an agent pipes or reads it; no banner.
         write(guide.content);
         return 0;
     }
-    // install
     const claudeCode = argv.includes("--claude-code");
     const confirmed = argv.includes("--yes");
     if (positionals.length > 1)
@@ -1304,23 +1132,13 @@ function runSkillsCommand(argv, write) {
     write("Agents that read Agent Skills (claude, codex, gemini, opencode) will discover the queue on their next session here.");
     return 0;
 }
-/**
- * `toolroll demo` (adoption track, step 4): a seeded throwaway
- * sandbox served on localhost — ninety seconds from npx to seeing the
- * product mid-flight. Everything under one temp directory; the database
- * is stamped `demo` before any row exists, so every spending or
- * external-effect command fails closed on it forever, kept or not. The
- * throwaway password prints to the terminal and to a 0600 file in the
- * sandbox — never into the --json envelope.
- */
-async function runDemoCommand(argv, write) {
+async function runDemoCommand(argv, write, seams = {}) {
     const json = argv.includes("--json");
     const keep = argv.includes("--keep");
     const portIndex = argv.indexOf("--port");
     const portGiven = portIndex === -1 ? "0" : (argv[portIndex + 1] ?? "");
     const port = Number(portGiven);
     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: 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;
@@ -1329,11 +1147,6 @@ async function runDemoCommand(argv, write) {
         write(json ? envelopeJson({ ok: false, command: "demo", reason: "usage", message: DEMO_USAGE }) : DEMO_USAGE);
         return 2;
     }
-    // Reachability, same flags as `serve`: --host binds beyond localhost
-    // (a tailnet, a LAN), and --allow-host names the Host headers the
-    // console will answer to there — a bind on 0.0.0.0 alone still refuses
-    // any name it was not told. Nothing here loosens the demo fence: the
-    // database stays stamped, spend stays refused.
     const hostIndex = argv.indexOf("--host");
     const host = hostIndex === -1 ? "127.0.0.1" : (argv[hostIndex + 1] ?? "");
     const allowIndex = argv.indexOf("--allow-host");
@@ -1356,12 +1169,11 @@ async function runDemoCommand(argv, write) {
     });
     const address = server.address();
     const boundPort = typeof address === "object" && address !== null ? address.port : port;
-    // The greeting names a road that will actually answer: the first allowed
-    // name when one was given, else the loopback.
     const url = allowedHosts.length > 0 ? `http://${allowedHosts[0]}` : `http://127.0.0.1:${boundPort}`;
+    const terminal = seams.terminal ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+    const demoSignIn = await import("./demo-sign-in.js");
+    const signIn = demoSignIn.demoSignInLink(server, seed.login.name, { stdin: terminal, stdout: terminal, agent: seams.underAgent ?? underAgent(process.env), json });
     if (json) {
-        // The password is deliberately NOT here (adoption review, finding 9):
-        // envelopes land in logs. It lives in the 0600 file and on the TTY.
         write(envelopeJson({ ok: true, command: "demo", url, sandbox, login: { name: seed.login.name, passwordFile }, keep }));
     }
     else {
@@ -1371,13 +1183,26 @@ async function runDemoCommand(argv, write) {
         write(`  login     ${seed.login.name} / ${seed.login.password}`);
         write(`  sandbox   ${sandbox}`);
         write("");
+        if (signIn !== null) {
+            write("Opened in your browser, signed in.");
+            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("For your own project, run `toolroll` 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."
             : "Ctrl-C stops the server and deletes the sandbox. --keep preserves it (still fenced from spending).");
     }
+    let removePage = () => { };
+    if (signIn !== null) {
+        const page = demoSignIn.writeSignInPage(sandbox, signIn);
+        removePage = demoSignIn.removeSignInPageWhenSpent(store, page, seed.login.name);
+        if (seams.openPage !== undefined)
+            seams.openPage(page);
+        else
+            demoSignIn.openSignInPage(page);
+    }
     await new Promise(done => {
         const stop = () => {
             process.off("SIGINT", stop);
@@ -1386,7 +1211,9 @@ async function runDemoCommand(argv, write) {
         };
         process.on("SIGINT", stop);
         process.on("SIGTERM", stop);
+        void seams.stop?.then(stop);
     });
+    removePage();
     lead.stop();
     await new Promise(closed => server.close(() => closed()));
     store.close();
@@ -1402,18 +1229,9 @@ async function runDemoCommand(argv, write) {
     }
     return 0;
 }
-/**
- * `contract` is the machine contract, stated by the machine: the envelope
- * version and the capability tokens an agent consumer can feature-detect on.
- * Behaviors, not versions — consumers ignore tokens they do not recognize.
- */
-/** contract's EXACT flags — consulted below and compared by the command
- * guide's tests (arc-5 review, finding 5). */
 export const CONTRACT_FLAGS = ["json", "commands"];
 function runContractCommand(argv, write) {
     const json = argv.includes("--json");
-    // Exact parsing (arc-5 review, finding 5): unknown flags and stray
-    // positionals refuse instead of being silently ignored.
     for (const argument of argv) {
         const bad = (message) => {
             write(json ? envelopeJson({ ok: false, command: "contract", reason: "usage", message }) : message);
@@ -1484,12 +1302,6 @@ function runContractCommand(argv, write) {
     write("`contract --commands` dumps the declared command guide.");
     return 0;
 }
-/**
- * The machine-readable envelope. Remote state is folded into each repository
- * rather than sitting in a parallel map, so a consumer never has to join two
- * collections to answer "what is happening in this repo" — and `remoteRead`
- * says whether the absence of pull requests means none or means we did not ask.
- */
 function renderJson(repos, roots, missingRoots, now, remote) {
     const withRemote = repos.map(repo => {
         const state = remote?.get(repo.path);
@@ -1497,10 +1309,6 @@ function renderJson(repos, roots, missingRoots, now, remote) {
             ...repo,
             pulls: state?.pulls ?? [],
             issues: state?.issues ?? [],
-            // Per repository, not only at the top level. An empty `pulls` means
-            // three different things — none open, not asked, or asked and failed —
-            // and a consumer should not have to join two parts of the envelope to
-            // find out which.
             pullsRead: state?.pullsRead ?? false,
             issuesRead: state?.issuesRead ?? false,
             remoteSkipped: state?.skipped ?? false,
@@ -1517,14 +1325,6 @@ function renderJson(repos, roots, missingRoots, now, remote) {
         repos: withRemote,
     });
 }
-/**
- * Whether this module is the program being run, rather than an import.
- *
- * Node resolves a module to its real path while argv[1] keeps whatever name it
- * was invoked by, so a symlinked `toolroll` on PATH compares unequal to
- * itself unless both sides are resolved. Getting this wrong is silent: the
- * command runs, prints nothing, and exits 0.
- */
 export function isDirectInvocation(moduleUrl, entry, toRealPath = realpathSync) {
     if (entry === undefined)
         return false;
@@ -1535,20 +1335,6 @@ export function isDirectInvocation(moduleUrl, entry, toRealPath = realpathSync)
         return false;
     }
 }
-/**
- * Node prints `ExperimentalWarning: SQLite is an experimental feature` to
- * stderr the first time the store is opened. One line is fair warning; one
- * line per invocation, in a dispatch loop that runs the command thousands of
- * times overnight, is a log nobody can read.
- *
- * It is filtered here and nowhere else. This runs only when the CLI is the
- * program — a process it legitimately owns — so importing any of these modules
- * as a library still leaves the host's warnings exactly as they were. The
- * mechanism matters too: wrapping `process.emitWarning`, which is what Node's
- * own experimental notice goes through, leaves every `warning` listener anyone
- * else registered working normally. An earlier attempt swapped the listeners
- * themselves and quietly made everybody's `once` permanent.
- */
 function hushExperimentalSqlite() {
     const original = process.emitWarning.bind(process);
     process.emitWarning = ((warning, ...rest) => {
@@ -1559,7 +1345,6 @@ function hushExperimentalSqlite() {
         original(warning, ...rest);
     });
 }
-/** The process entry the bin calls: the SQLite notice hushed, the exit code set. */
 export async function runCliProcess(argv) {
     hushExperimentalSqlite();
     process.exitCode = await main(argv);