toolroll 0.9.104 → 0.9.105

package/dist/setup-guide.js

@@ -1,4 +1,3 @@
-/** Read-only suggestions for the shared desktop and browser setup flow. */
 import { withAcp } from "./acp-agents.js";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
@@ -14,15 +13,12 @@ export const ASSISTANTS = withAcp({
     openrouter: { name: "OpenRouter", description: "Use a model from your OpenRouter account." },
 }, agent => ({ name: agent.name, description: `Use ${agent.name} for builds, once it's checked on this computer.` }));
 export function modelChoices(provider, configured, home = homedir()) {
-    // Aliases documented at https://code.claude.com/docs/en/model-config.
     let choices = provider === "claude"
-        // Exact ids first: Sonnet 5.5 builds routine tasks under "Sized by job" (Settings → Models); the short names float.
         ? [{ value: "claude-sonnet-5-5", label: "Sonnet 5.5 — routine tasks" }, { value: "claude-opus-5-5", label: "Opus 5.5 — large or risky tasks" },
             { value: "claude-haiku-5-5", label: "Haiku 5.5 — small tasks" }, { value: "sonnet", label: "Sonnet (floating) — moves to the newest version" },
             { value: "opus", label: "Opus (floating) — moves to the newest version" }, { value: "haiku", label: "Haiku (floating) — moves to the newest version" }]
         : [];
     if (provider === "codex") {
-        // Use the local CLI's own catalog, including account-specific availability.
         try {
             const path = join(home, ".codex", "models_cache.json");
             if (lstatSync(path).size < 2_000_000) {
@@ -31,14 +27,13 @@ export function modelChoices(provider, configured, home = homedir()) {
                     .slice(0, 30).map(one => ({ value: one.slug, label: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
             }
         }
-        catch { /* A missing catalog leaves the explicit model option available. */ }
+        catch { }
     }
     if (configured && !choices.some(one => one.value === configured))
         choices.unshift({ value: configured, label: `${configured} — current choice` });
     return choices;
 }
 export function detectPreparation(repo) {
-    // In the console, a folder that hasn't answered a look lately is not read on its thread (folder-gate.ts).
     if (!folderAnswers(repo))
         return null;
     const has = (file) => existsSync(join(repo, file));
@@ -61,7 +56,6 @@ export function detectPreparation(repo) {
         return { command: "go mod download", label: "Download Go dependencies", evidence: "go.mod" };
     return null;
 }
-/** Browser installation may write only this known file inside its project. */
 export function previewProjectInstructions(repo) {
     if (!folderAnswers(repo))
         return { ok: false, message: "This project folder didn't answer. Try again in a moment." };
@@ -90,8 +84,6 @@ export function previewProjectInstructions(repo) {
     const content = skillContent();
     const current = existsSync(plan.skillPath) ? readFileSync(plan.skillPath, "utf8") : null;
     const fingerprint = createHash("sha256").update(JSON.stringify({ repo, current, content })).digest("hex");
-    // Installed means the CURRENT instructions are in place: a stale copy, or one only in the folder from before the
-    // rename, still offers Review so applyInstall can bring it up to date (the first-run checklist counts either).
     return { ok: true, plan, content, fingerprint, installed: current === content };
 }
 export function addProjectInstructions(repo, fingerprint) {

package/dist/shared-deps.js

@@ -1,21 +1,3 @@
-/**
- * Shared dependencies: one installed node_modules per (project, lockfile, setup, node) under the state folder
- * (`deps/<key>`), linked into each new checkout instead of a fresh `npm ci` there. Measured Oct 2: a checkout of
- * Toolroll is 20,500 files and 18,066 of them were its own node_modules; forty checkouts created and deleted ~800k
- * files, most of the churn behind a bloated fseventsd, and each install cost time.
- *
- * The first checkout with a new key runs the approved setup itself; its node_modules then moves (one rename, same
- * volume) into `deps/<key>`, is made read-only, and is linked back. Later checkouts link it: symlinks, else an
- * APFS/reflink clone, else the plain setup as before. A linked node_modules is a real folder holding one symlink per
- * top-level entry (a few hundred files, not tens of thousands), so caches tools write there stay the checkout's own.
- * Only a setup that installs and does nothing else is shared (`npm ci`, `npm install`): skipping any other command
- * would skip its other effects.
- *
- * The link is read-only to the build. A checkout whose package.json or lockfile no longer matches the copy it links
- * gets its own install (the link goes, the approved setup runs there) and the shared copy is never touched; a copy
- * whose installed tree changed anyway is retired, never linked again. `toolroll storage clean` removes a copy no
- * checkout links or matches; the plane's daily storage sweep removes one no checkout has used for a week.
- */
 import { createHash, randomBytes } from "node:crypto";
 import { execFile, spawnSync } from "node:child_process";
 import { rm } from "node:fs/promises";
@@ -26,28 +8,17 @@ import { QUARANTINE_NOTE, quarantine, quarantineEntries, claimQuarantine, releas
 export const DEPS_FOLDER = "deps";
 const READY = "ready.json";
 const RETIRED = "retired";
-/** In a linked node_modules: the shared copy it links. */
 const LINK_NOTE = ".toolroll-shared";
 const NODE_MODULES = "node_modules";
-/** A copy linked or made this recently is never removed by a clean-up: a lease may be about to link it. */
 export const SHARED_GRACE_MS = 60 * 60_000;
-/** The daily storage sweep removes a copy no checkout uses and none has linked for this long. */
 export const SHARED_UNUSED_MS = 7 * 24 * 60 * 60_000;
-/** A half-made copy (a crash mid-promotion) is debris after this long. */
 const PARTIAL_STALE_MS = 24 * 60 * 60_000;
 export function sharedDepsRoot(databaseFile) {
     return join(dirname(databaseFile), DEPS_FOLDER);
 }
-/** A setup whose whole effect is node_modules: `npm ci` or `npm install`, with plain flags only. */
 export function installsOnly(command) {
     return /^\s*npm\s+(?:ci|install|i)(?:\s+--?[A-Za-z][\w-]*(?:=[\w.@/:+-]+)?)*\s*$/.test(command);
 }
-/**
- * The checkout's dependency identity: its npm lockfile and package.json, hashed together without the root
- * package's own version, as in release-check.mjs versionOnly(). null when either JSON file is invalid, there is no
- * lockfile, or the lockfile links local folders (workspaces, `file:`), whose links would point into the shared
- * folder instead of the checkout.
- */
 export function lockDigest(checkout) {
     return dependencyInputs(checkout)?.digest ?? null;
 }
@@ -84,8 +55,6 @@ function dependencyInputs(checkout) {
         return null;
     }
 }
-/** Replace only root version values, preserving every other byte for comparison with a pre-normalization hash.
- * The caller already parsed the JSON. Token offsets let compact and indented files keep their original layout. */
 function withRootVersion(text, version, isLock) {
     const tokens = [...text.matchAll(/"(?:[^"\\]|\\.)*"|[{}[\]:,]|[^\s{}[\]:,]+/g)];
     let cursor = 0;
@@ -95,7 +64,7 @@ function withRootVersion(text, version, isLock) {
         if (start[0] === "{") {
             while (tokens[cursor][0] !== "}") {
                 const key = JSON.parse(tokens[cursor++][0]);
-                cursor++; // colon
+                cursor++;
                 value([...path, key]);
                 if (tokens[cursor][0] === ",")
                     cursor++;
@@ -122,8 +91,6 @@ function withRootVersion(text, version, isLock) {
         text = text.slice(0, edit.start) + JSON.stringify(version) + text.slice(edit.end);
     return text;
 }
-/** Old copies did not save the manifests. npm's hidden lock records their root version; reconstruct only those
- * version fields and require the exact old raw digest. Never infer equality from the installed packages alone. */
 function matchesInputs(dir, ready, inputs) {
     if (ready.lock === inputs.digest || ready.lock === digestPair(inputs.lock, inputs.manifest))
         return true;
@@ -136,7 +103,6 @@ function matchesInputs(dir, ready, inputs) {
     }
 }
 const nodeSeen = new Map();
-/** The node a setup on this PATH would install with: version, platform and architecture (native modules differ). */
 export function nodeIdentity(path = process.env["PATH"] ?? "") {
     if (nodeSeen.has(path))
         return nodeSeen.get(path);
@@ -150,7 +116,6 @@ export function nodeIdentity(path = process.env["PATH"] ?? "") {
 export function depsKey(repo, setupDigest, lock, node) {
     return createHash("sha256").update([repo, setupDigest, lock, node].join("\u0000"), "utf8").digest("hex").slice(0, 24);
 }
-/** What a checkout would share: its key and the facts behind it, or null when it can't share. */
 export function sharingFor(args) {
     if (!installsOnly(args.setup.command))
         return null;
@@ -167,8 +132,7 @@ export function sharingFor(args) {
         try {
             names = readdirSync(args.root).filter(name => /^[0-9a-f]{24}$/.test(name));
         }
-        catch { /* no copies yet */ }
-        // Keep a currently linked copy first. Reusing its old directory preserves every existing checkout's links.
+        catch { }
         for (const name of new Set([linkedKey(args.worktree, args.root), key, ...names])) {
             if (name === null)
                 continue;
@@ -190,7 +154,6 @@ function readReady(dir) {
         return null;
     }
 }
-/** npm's record of what it installed: changes when anything installs or removes a package in the tree. */
 function treeDigest(nodeModules) {
     try {
         return createHash("sha256").update(readFileSync(join(nodeModules, ".package-lock.json"))).digest("hex");
@@ -199,7 +162,6 @@ function treeDigest(nodeModules) {
         return null;
     }
 }
-/** The shared node_modules for a key, when one is ready and unchanged since it was made. A changed one is retired. */
 export function readyCopy(root, key) {
     if (!/^[0-9a-f]{24}$/.test(key))
         return null;
@@ -215,21 +177,12 @@ export function readyCopy(root, key) {
     }
     return join(dir, NODE_MODULES);
 }
-/**
- * Take a changed copy out of use. It stays where it is, so a checkout still linking it keeps working; no new
- * checkout links it, and a clean-up removes it once nothing links it.
- */
 function retire(dir) {
     try {
         writeFileSync(join(dir, RETIRED), `${new Date().toISOString()}\n`, "utf8");
     }
-    catch { /* the next look retires it */ }
+    catch { }
 }
-/**
- * The shared copy a checkout's node_modules links, or null (none, or its own install). A linked node_modules is a
- * small real folder: one link per top-level entry of the shared copy and a note naming it. Tools that write a cache
- * there (`node_modules/.vite`, `.cache`) write into the checkout's own folder, never the shared copy.
- */
 export function linkedKey(worktree, root) {
     let target;
     try {
@@ -244,11 +197,9 @@ export function linkedKey(worktree, root) {
     const [key, folder, ...rest] = inside.split(/[\\/]/);
     return key !== undefined && folder === NODE_MODULES && rest.length === 0 ? key : null;
 }
-/** Remove a checkout's linked node_modules (its links and caches, never what they point to). True when there was one. */
 export function detachShared(worktree, root) {
     if (linkedKey(worktree, root) === null)
         return false;
-    // rm removes a link itself; it never follows one into the shared copy.
     rmSync(join(worktree, NODE_MODULES), { recursive: true, force: true });
     return true;
 }
@@ -257,10 +208,6 @@ function writable(path, on) {
         return;
     spawnSync("chmod", ["-R", on ? "u+w" : "a-w", path], { timeout: 120_000 });
 }
-/**
- * Put a shared copy into a checkout that has no node_modules: links (a junction per folder on Windows), else a
- * copy-on-write clone the build owns. null: neither worked, and the caller runs the plain setup.
- */
 export function linkInto(worktree, shared) {
     const at = join(worktree, NODE_MODULES);
     if (existsSync(at) || isLink(at))
@@ -270,8 +217,6 @@ export function linkInto(worktree, shared) {
         return null;
     try {
         mkdirSync(at);
-        // Publish intent before reading the copy. A sweep that renames it mid-link sees this user and restores it;
-        // if the sweep won before the intent, the final ready check fails and no broken link is handed to a run.
         writeFileSync(join(at, LINK_NOTE), `${shared}\n`, "utf8");
         touch(dirname(shared));
         for (const entry of readdirSync(shared, { withFileTypes: true })) {
@@ -300,7 +245,7 @@ export function linkInto(worktree, shared) {
         writable(at, true);
         rmSync(at, { recursive: true, force: true });
     }
-    catch { /* a partial clone stays for a person */ }
+    catch { }
     return null;
 }
 function isLink(path) {
@@ -316,13 +261,8 @@ function touch(dir) {
     try {
         utimesSync(join(dir, READY), now, now);
     }
-    catch { /* the age only guards a clean-up */ }
+    catch { }
 }
-/**
- * After the approved setup succeeded in a checkout with no copy for its key: move its node_modules into
- * `deps/<key>` (one rename), make it read-only and link it back. Returns how the checkout now has it, or null when it
- * kept its own install (a different volume, a setup that rewrote the lockfile, a race lost cleanly).
- */
 export function promoteInstall(args) {
     const own = join(args.worktree, NODE_MODULES);
     try {
@@ -337,7 +277,6 @@ export function promoteInstall(args) {
     const partial = join(args.root, `${args.key}.partial-${process.pid}-${randomBytes(4).toString("hex")}`);
     try {
         mkdirSync(partial, { recursive: true });
-        // Spotlight leaves shared installs alone (never-index.ts).
         markNeverIndex(args.root);
         renameSync(own, join(partial, NODE_MODULES));
     }
@@ -354,28 +293,25 @@ export function promoteInstall(args) {
         shared = join(args.root, args.key, NODE_MODULES);
     }
     catch {
-        // Another checkout made this copy first: use theirs.
         shared = readyCopy(args.root, args.key);
     }
     const linked = shared === null ? null : linkInto(args.worktree, shared);
     if (linked === null && !existsSync(partial) && shared === join(args.root, args.key, NODE_MODULES) && !existsSync(own)) {
-        // Ours became the shared copy but couldn't be linked: it goes back to being this checkout's own install.
         writable(shared, true);
         try {
             renameSync(shared, own);
             rmSync(join(args.root, args.key), { recursive: true, force: true });
         }
-        catch { /* left for a clean-up */ }
+        catch { }
         return null;
     }
     if (existsSync(partial)) {
-        // Lost the race: ours goes back if nothing else could be linked, else it's removed.
         if (linked === null && !existsSync(own)) {
             writable(join(partial, NODE_MODULES), true);
             try {
                 renameSync(join(partial, NODE_MODULES), own);
             }
-            catch { /* left for a clean-up */ }
+            catch { }
         }
         removeTree(partial);
     }
@@ -385,7 +321,6 @@ function removeTree(path) {
     writable(path, true);
     rmSync(path, { recursive: true, force: true });
 }
-/** Every shared copy on disk, newest first. */
 export function sharedCopies(root) {
     let names = [];
     try {
@@ -405,12 +340,11 @@ export function sharedCopies(root) {
         try {
             usedAt = statSync(join(root, name, READY)).mtime.toISOString();
         }
-        catch { /* createdAt stands */ }
+        catch { }
         copies.push({ key: name, dir: join(root, name), repo: ready.repo, lock: ready.lock, node: ready.node, createdAt: ready.createdAt, usedAt, retired: existsSync(join(root, name, RETIRED)) });
     }
     return copies.sort((a, b) => b.usedAt.localeCompare(a.usedAt));
 }
-/** Which checkouts use each copy: those linking it, and those whose lockfile it was installed from. */
 export function sharedUse(root, checkouts) {
     return useCopies(root, sharedCopies(root), checkouts);
 }
@@ -436,7 +370,6 @@ function useCopies(root, copies, checkouts) {
     }
     return copies.map(one => ({ ...one, checkouts: [...users.get(one.key)].sort() }));
 }
-/** Half-made copies under deps/ (a crash mid-promotion), old enough that nothing is still making them. */
 export function sharedDebris(root, now) {
     let names = [];
     try {
@@ -456,12 +389,10 @@ export function sharedDebris(root, now) {
         }
     }).map(name => join(root, name));
 }
-/** What `storage clean` removes: copies no checkout uses and none linked within the grace period, plus debris. */
 export function unusedShared(root, checkouts, now) {
     const copies = sharedUse(root, checkouts).filter(one => one.checkouts.length === 0 && now.getTime() - Date.parse(one.usedAt) > SHARED_GRACE_MS);
     return { copies, debris: sharedDebris(root, now) };
 }
-/** Remove one copy or debris folder (read-only on disk, so made writable first). */
 export function removeShared(path) {
     if (basename(dirname(path)) !== DEPS_FOLDER)
         return false;
@@ -473,11 +404,6 @@ export function removeShared(path) {
         return false;
     }
 }
-/**
- * The daily sweep: remove each copy no checkout uses and none has linked for `unusedMs` (a week), and old debris.
- * Right before a copy goes, who uses it, when it was last linked and whether live work uses it (`spare`,
- * storage-sweep.ts) are read again; a copy a checkout picked up in between stays. Removal never holds the event loop.
- */
 export async function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_UNUSED_MS, options = {}) {
     const stale = (one) => one.checkouts.length === 0 && now.getTime() - Date.parse(one.usedAt) > unusedMs;
     const removed = [];
@@ -492,7 +418,7 @@ export async function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_
                 try {
                     usedAt = statSync(join(trash.path, READY)).mtime.toISOString();
                 }
-                catch { /* partially deleted trash */ }
+                catch { }
                 const fresh = useCopies(root, [{ ...copy, dir: trash.path, usedAt }], checkouts())[0];
                 used ||= !stale(fresh);
             }
@@ -547,7 +473,6 @@ export async function pruneUnusedShared(root, checkouts, now, unusedMs = SHARED_
     return { removed, failed };
 }
 const nextTurn = () => new Promise(resolve => setImmediate(resolve));
-/** removeShared without holding the event loop: chmod and rm run off it. */
 async function removeSharedLater(path) {
     if (process.platform !== "win32")
         await new Promise(resolve => execFile("chmod", ["-R", "u+w", path], { timeout: 120_000 }, () => resolve()));

package/dist/sign-in-guard.js

@@ -3,26 +3,15 @@ import { createHmac, randomBytes } from "node:crypto";
 import { sourceKey } from "./source-key.js";
 export const DEFAULT_GUARD_POLICY = { failuresBeforeLock: 5, firstLockMs: 15 * 60_000, maxLockMs: 24 * 60 * 60_000, firstSlowMs: 60_000 };
 const TRACKED = 10_000;
-/** Default/loopback source for callers without an explicit native CLI context. */
 export const LOCAL_SOURCE = "local";
-/** Native CLI only: no HTTP peer or forwarded header can select this source. */
 export const CLI_PASSWORD_SOURCE = "local-cli";
 export const ACCOUNT_PASSWORD_TRIES = 3;
 export const ACCOUNT_PASSWORD_WINDOW_MS = 60_000;
 const LOCAL_PEERS = new Set(["127.0.0.1", "::1"]);
 const passwordSource = new AsyncLocalStorage();
-/** Run `work` with every password check inside it counted against `source`. */
 export const withPasswordSource = (source, work) => passwordSource.run(source, work);
-/** Where the password being checked now came from (LOCAL_SOURCE outside a request). */
 export const currentPasswordSource = () => passwordSource.getStore() ?? LOCAL_SOURCE;
-/** Set only after the server validates a browser session, never from submitted form fields. */
 export const provenPasswordAccount = new AsyncLocalStorage();
-/**
- * Keep the first TRACKED live keys exactly; further keys share TRACKED overflow buckets. Hashes use the guard's
- * private secret, so callers cannot choose collisions. Neither tier evicts live state. Overflow never mutates the
- * exact tier, and cannot move into a freed exact slot until all overflow state expires: moving would reset budgets.
- * A success may clear its exact record, but never a shared bucket (which could also hold another name's failures).
- */
 class KeyedGuardState {
     secret;
     domain;
@@ -70,7 +59,6 @@ class KeyedGuardState {
         pruneEntries(this.overflow);
         return next;
     }
-    /** Individual source/name records; shared overflow storage has its own fixed TRACKED-bucket bound. */
     get size() { return this.entries.size; }
 }
 export class PasswordGuard {
@@ -79,7 +67,6 @@ export class PasswordGuard {
     sources = new KeyedGuardState(this.secret, "source/name");
     slowdowns = new KeyedGuardState(this.secret, "name");
     nextPruneAt = Infinity;
-    /** Told once per lock: the account (as typed), and for how long. */
     onLock = null;
     constructor(policy = DEFAULT_GUARD_POLICY) {
         this.policy = policy;
@@ -89,13 +76,11 @@ export class PasswordGuard {
         const key = sourceKey(source);
         return `${LOCAL_PEERS.has(key) ? LOCAL_SOURCE : key}\u0000${PasswordGuard.key(account)}`;
     }
-    /** Prune by the supplied time, even below capacity; retain a lock's escalation history for a day. */
     prune(now) {
         if (now < this.nextPruneAt)
             return;
         this.nextPruneAt = Math.min(this.sources.prune(now, this.policy.maxLockMs), this.slowdowns.prune(now, this.policy.maxLockMs));
     }
-    /** Source-local snapshot for existing callers. Authentication must use preflight to spend the shared budget. */
     lockedFor(account, now, source = currentPasswordSource()) {
         this.prune(now);
         const pair = PasswordGuard.pair(account, source);
@@ -103,10 +88,8 @@ export class PasswordGuard {
         if (tries === undefined)
             return 0;
         const slowdown = this.slowdowns.get(PasswordGuard.key(account));
-        // Legacy observation only: account existence never affects authentication or state retention.
         return Math.max(0, tries.lockedUntil - now, slowdown?.observedAccount === true ? slowdown.until - now : 0);
     }
-    /** Reserve one password check, or return its wait. No password derivation may precede this call. */
     preflight(account, now, source = currentPasswordSource(), proven = false) {
         this.prune(now);
         const tries = this.sources.get(PasswordGuard.pair(account, source));
@@ -124,7 +107,6 @@ export class PasswordGuard {
         slowdown.admissions.push(now);
         return 0;
     }
-    /** A wrong password; only a database lookup may establish `exists`. */
     failed(account, now, source = currentPasswordSource(), exists = false) {
         this.prune(now);
         const pair = PasswordGuard.pair(account, source);
@@ -148,17 +130,14 @@ export class PasswordGuard {
         if (over >= 0)
             slowdown.until = now + Math.min(this.policy.maxLockMs, this.policy.firstSlowMs * 2 ** Math.min(over, 32));
     }
-    /** The right password clears individually tracked state; shared overflow buckets must expire by time. */
     succeeded(account, source = currentPasswordSource()) {
         const pair = PasswordGuard.pair(account, source);
         this.sources.clear(pair);
         this.slowdowns.clear(PasswordGuard.key(account));
     }
-    /** Individually tracked source-and-name entries (at most TRACKED), excluding fixed shared overflow buckets. */
     get size() { return this.sources.size; }
 }
 const guards = new WeakMap();
-/** The guard for one database (a store): every password check against it counts. */
 export function passwordGuardOf(owner) {
     let guard = guards.get(owner);
     if (guard === undefined) {
@@ -167,11 +146,6 @@ export function passwordGuardOf(owner) {
     }
     return guard;
 }
-/**
- * Wrong passwords from one address, across every account: at most `tries`
- * in `windowMs`. What a lockout per account can't see (one address trying
- * many names) this does.
- */
 export class SourceBudget {
     tries;
     windowMs;
@@ -180,7 +154,6 @@ export class SourceBudget {
         this.tries = tries;
         this.windowMs = windowMs;
     }
-    /** Milliseconds until this address may try again (0: it may). */
     waitFor(address, now) {
         const recent = (this.sources.get(sourceKey(address)) ?? []).filter(at => now - at < this.windowMs);
         return recent.length < this.tries ? 0 : this.windowMs - (now - recent[0]);

package/dist/skills-ui.js

@@ -2,13 +2,11 @@ import { randomUUID } from "node:crypto";
 import { whenUtc } from "./when-html.js";
 import { html, joinHtml, postForm } from "./html.js";
 import { acts, btn, chip, disclose, facts, formRow, input, note, notice, select, settingsRecord, settingsSection, textarea } from "./server/kit.js";
-// Hidden fields as they always were: a missing value is an empty field.
 const fields = (data) => Object.fromEntries(Object.entries(data).map(([k, v]) => [k, String(v ?? "")]));
 export const SKILLS_CSS = `.skills{max-width:780px;min-width:0;overflow-wrap:anywhere}.skills h2{font-size:1.1rem}.skills .card{padding:18px;margin:14px 0;min-width:0}.skills form,.skills label{display:grid;gap:10px}.skills input,.skills textarea,.skills select{box-sizing:border-box;width:100%;max-width:100%;min-width:0}.skills textarea{resize:vertical;min-height:130px}.skills button{justify-self:start;white-space:nowrap;min-height:44px}.skills summary{cursor:pointer;min-height:44px;display:flex;align-items:center;gap:10px;flex-wrap:wrap}.skills pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:360px;overflow:auto;font-size:.9rem}.skills .skill-heading{display:flex;align-items:baseline;justify-content:space-between;gap:12px}.skills .skill-heading h2{margin:0}.skills .skill-state{font-size:.85rem;flex-shrink:0}.skills .skill-source{font-size:.85rem}.skills .skill-controls{display:flex;gap:12px;flex-wrap:wrap}.skills .skill-controls form{margin:0}.skills details details{margin-top:10px}.skills [hidden]{display:none!important}.skills .skill-files{max-height:200px;overflow:auto}.skills .problem{padding:12px}@media(max-width:600px){.skills input,.skills textarea,.skills select{font-size:16px}.skills .card{padding:14px}.skills .skill-heading{align-items:flex-start}}`;
 function source(skill) {
     return html `<p class="skill-source">${skill.source} · ${skill.sha.slice(0, 10)}</p><p>${skill.files.length} files · ${Math.ceil(skill.files.reduce((n, f) => n + Buffer.from(f.base64, "base64").length, 0) / 1024)} KB</p><pre>${Buffer.from(skill.files.find((f) => f.path === "SKILL.md").base64, "base64").toString("utf8")}</pre><details><summary>Package files</summary><ul class="skill-files">${skill.files.map((f) => html `<li>${f.path}</li>`)}</ul></details>`;
 }
-/** A skill's package as the settings page shows it: where it came from, its size, its SKILL.md, its files. */
 function sourceKit(skill) {
     const kb = Math.ceil(skill.files.reduce((n, f) => n + Buffer.from(f.base64, "base64").length, 0) / 1024);
     return joinHtml([

package/dist/skills.js

@@ -1,43 +1,16 @@
-/**
- * `toolroll skills install` (M7.13) — how a repository tells its
- * agents this queue exists.
- *
- * Two artifacts, both operator-invoked, previewed by default, and marked
- * as managed so nothing here ever overwrites a file it does not own:
- *
- *   - `.claude/skills/toolroll/SKILL.md` — the Agent Skills entry
- *     (the cross-vendor layout Claude Code, Codex, Gemini CLI, and
- *     opencode all read). Router-style: the description says when to
- *     reach for the CLI; the body carries the operating contract and
- *     defers to live `--help` for everything else, because a skill that
- *     duplicates the manual drifts from it.
- *   - a managed AGENTS.md block (CLAUDE.md-compatible), written only
- *     with --write-context, replaced only between its own markers.
- *
- * DESIGN's "nothing is ever installed for you" holds: this command runs
- * when the operator runs it, shows exactly what it would write, and
- * touches nothing without --yes.
- */
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { guideNamed } from "./guides.js";
 export const SKILL_DIR = join(".claude", "skills", "toolroll");
-/** Where installs before the rename to Toolroll put the skill: still found, and replaced by the new one. */
 export const LEGACY_SKILL_DIR = join(".claude", "skills", "standing-orders");
 export const SKILL_FILE = "SKILL.md";
 export const MANAGED_MARK = "managed by toolroll — edits outside the markers survive reinstalls";
 const LEGACY_MANAGED_MARK = "managed by standing-orders — edits outside the markers survive reinstalls";
-/** Frontmatter a skill of ours starts with, under either name. */
 const OWN_HEADERS = ["---\nname: toolroll\n", "---\nname: standing-orders\n"];
 const ownHeader = (content) => OWN_HEADERS.some(header => content.startsWith(header));
 export const CONTEXT_BEGIN = "<!-- standing-orders:begin -->";
 export const CONTEXT_END = "<!-- standing-orders:end -->";
-/** The skill, complete. The description is the routing contract. The body
- * is the binary-served `operating` guide (guides.ts) — ONE source, so the
- * installed snapshot and `skills get operating` cannot drift apart within
- * a version. The frontmatter prefix and the managed mark are the ownership
- * signature planInstall checks — do not reword them. */
 export function skillContent() {
     const operating = guideNamed("operating");
     if (operating === null)
@@ -53,7 +26,6 @@ ${operating.content}
 <!-- end ${MANAGED_MARK} -->
 `;
 }
-/** The AGENTS.md block, marker-fenced so reinstalls replace only themselves. */
 export function contextBlock() {
     return `${CONTEXT_BEGIN}
 This repository's unattended work runs through the \`toolroll\` CLI
@@ -63,7 +35,8 @@ envelope per command, stable \`reason\` tokens, exit 3 means "no" not
 \`held\`, \`fenced\`, \`reserved\`, \`unapproved\`, and \`external\` are
 answers to branch on, not errors to retry. Details:
 \`.claude/skills/toolroll/SKILL.md\`, or \`toolroll --help\`,
-which is authoritative — and \`toolroll skills get <name>\` serves
+which is authoritative (\`toolroll internals\` and
+\`toolroll contract --commands --json\` list every command) — and \`toolroll skills get <name>\` serves
 version-matched guides straight from the binary (\`skills list\` names
 them). Project memory (instructions, references, lessons, decisions) lives
 in the plane: read \`skills get knowledge\`, search it with
@@ -72,14 +45,11 @@ in the plane: read \`skills get knowledge\`, search it with
 merge anything yourself.
 ${CONTEXT_END}`;
 }
-/** What install would do, computed without writing anything. */
 export function planInstall(repo, writeContext) {
     const skillPath = join(repo, SKILL_DIR, SKILL_FILE);
     let skillAction = "create";
     if (existsSync(skillPath)) {
         const current = readFileSync(skillPath, "utf8");
-        // Ownership is the exact header AND the managed mark — a foreign file
-        // that merely quotes the mark somewhere is not ours (audit C-10).
         const ours = ownHeader(current) && (current.includes(MANAGED_MARK) || current.includes(LEGACY_MANAGED_MARK));
         skillAction = ours ? "replace" : "refuse-foreign";
     }
@@ -97,7 +67,6 @@ export function planInstall(repo, writeContext) {
     }
     return { skillPath, skillAction, legacySkillPath, contextPath, contextAction };
 }
-/** Apply the plan. Refuses a foreign skill file rather than eating it. */
 export function applyInstall(repo, writeContext) {
     const plan = planInstall(repo, writeContext);
     if (plan.skillAction === "refuse-foreign") {
@@ -107,15 +76,10 @@ export function applyInstall(repo, writeContext) {
             message: `${plan.skillPath} exists and was not written by this installer — refusing to overwrite a file that is not mine`,
         };
     }
-    // EVERY validation happens before EITHER file is touched — "nothing was
-    // written" must be true when it is said (arc-5 review, finding 6; the
-    // old order wrote the skill first and then refused on damaged markers).
     let contextNext = null;
     if (plan.contextPath !== null && plan.contextAction !== "create") {
         const current = readFileSync(plan.contextPath, "utf8");
         if (plan.contextAction === "replace") {
-            // Exactly one well-ordered pair, or a typed refusal — a half block
-            // must never produce a silent false success (audit C-10).
             const begins = current.split(CONTEXT_BEGIN).length - 1;
             const ends = current.split(CONTEXT_END).length - 1;
             const begin = current.indexOf(CONTEXT_BEGIN);
@@ -130,7 +94,6 @@ export function applyInstall(repo, writeContext) {
             contextNext = current.slice(0, begin) + contextBlock() + current.slice(end + CONTEXT_END.length);
         }
         else {
-            // insert: append after existing content, never rewriting a word of it.
             contextNext = `${current.replace(/\n*$/, "\n\n")}${contextBlock()}\n`;
         }
     }
@@ -146,31 +109,21 @@ export function applyInstall(repo, writeContext) {
     }
     return { ok: true, plan, wrote };
 }
-/**
- * The user-level Claude Code skill is separate from the repository-local
- * skill above. The former teaches one Claude Code installation how to use
- * this exact Toolroll binary; the latter remains part of the shared
- * project setup flow.
- */
 export const CLAUDE_CODE_MANAGED_MARK = "<!-- standing-orders:claude-code-skill:v1 -->";
 export const CLAUDE_CODE_GUIDES = ["console", "operating", "runner", "release"];
-/** The thin user-level skill `toolroll onboard` writes (agent-onboard.ts). */
 export const OPERATOR_SKILL_MARK = "<!-- toolroll:operator-skill:v1";
 export function defaultClaudeCodeSkillDir(home = homedir()) {
     return join(home, ".claude", "skills", "toolroll");
 }
-/** Where installs before the rename put the Claude Code skill. */
 export function legacyClaudeCodeSkillDir(home = homedir()) {
     return join(home, ".claude", "skills", "standing-orders");
 }
-/** A regular file (not a link) whose text says it is ours. */
 function isOwnFile(path, ours) {
     if (!existsSync(path))
         return false;
     const entry = lstatSync(path);
     return !entry.isSymbolicLink() && entry.isFile() && entry.size <= 2_000_000 && ours(readFileSync(path, "utf8"));
 }
-/** A folder that is itself, not a link to somewhere else. */
 function realFolder(path) {
     try {
         const entry = lstatSync(path);
@@ -180,7 +133,6 @@ function realFolder(path) {
         return false;
     }
 }
-/** Remove files of ours, then their folder only if nothing else is left in it. */
 function removeOwn(paths) {
     for (const path of paths)
         unlinkSync(path);
@@ -189,7 +141,6 @@ function removeOwn(paths) {
         if (readdirSync(folder).length === 0)
             rmdirSync(folder);
 }
-/** SKILL.md links to the full guides instead of copying their detail. */
 export function claudeCodeSkillContent() {
     return `---
 name: toolroll
@@ -208,7 +159,6 @@ Use the installed \`toolroll\` command. Its live help is authoritative.
 - [Release guide](release.md) — releasing Toolroll itself with \`toolroll release <branch>\`.
 `;
 }
-/** One linked file, generated from the guide embedded in this binary. */
 export function claudeCodeGuideContent(name) {
     const guide = guideNamed(name);
     if (guide === null)
@@ -231,7 +181,6 @@ function isClaudeCodeManaged(name, content) {
     }
     return content.startsWith(`${CLAUDE_CODE_MANAGED_MARK}\n\n`);
 }
-/** Compute the complete write set without changing the filesystem. */
 export function planClaudeCodeInstall(directory = defaultClaudeCodeSkillDir(), legacyDirectory = directory === defaultClaudeCodeSkillDir() ? legacyClaudeCodeSkillDir() : null) {
     let directoryAction = "create";
     if (existsSync(directory)) {
@@ -257,7 +206,6 @@ export function planClaudeCodeInstall(directory = defaultClaudeCodeSkillDir(), l
         : claudeCodeFiles(legacyDirectory).filter(({ name, path }) => isOwnFile(path, content => isClaudeCodeManaged(name, content))).map(({ path }) => path);
     return { directory, directoryAction, files, legacyFiles };
 }
-/** Refresh every managed file, after validating the whole set first. */
 export function applyClaudeCodeInstall(directory = defaultClaudeCodeSkillDir(), legacyDirectory = directory === defaultClaudeCodeSkillDir() ? legacyClaudeCodeSkillDir() : null) {
     const plan = planClaudeCodeInstall(directory, legacyDirectory);
     const refused = plan.files.find(file => file.action === "refuse-foreign");