toolroll 0.9.103 → 0.9.105

package/dist/push.js

@@ -1,33 +1,12 @@
-/**
- * Web push, zero-dependency (arc 3).
- *
- * Three layers, kept apart: CRYPTO (RFC 8291 aes128gcm message encryption
- * and RFC 8292 VAPID authorization, byte-exact, node:crypto only),
- * TRANSPORT (one hardened fetch to an allow-listed push service), and the
- * PASS (claim pairs from the store's ledger, fence, send, settle by the
- * full outcome table). The payload that transits Apple's and Google's
- * servers is a fixed phrase keyed on the notification's CLASS plus a
- * machine-minted console path. Check progress may also send one validated
- * suite/count line; task titles, branches and repository names stay local.
- *
- * 'accepted' means the push service took the message (RFC 8030). Nothing
- * here ever claims a phone displayed anything, and delivery is
- * AT-LEAST-ONCE: a crash between acceptance and settlement re-sends after
- * the pair's lease expires (the payload's tag collapses the duplicate on
- * the lock screen).
- */
 import { closeSync, constants as fsConstants, fsyncSync, openSync, readFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { createCipheriv, createECDH, createPrivateKey, hkdfSync, randomBytes, createHash, sign as cryptoSign } from "node:crypto";
 import { isCheckProgressLine } from "./check-progress.js";
 import { RELEASE_PUSH_WORDS, releasePushOf, releaseReadyObsolete } from "./release-approval.js";
 export const VAPID_FILE = "vapid-keys.json";
-/** RFC 8291 §4: rs 4096 leaves room for the record's delimiter and tag. */
 const RECORD_SIZE = 4096;
-/** The plaintext ceiling that keeps one record inside rs (RFC 8291 §4). */
 export const PLAINTEXT_CEILING = 3993;
 const REQUEST_TIMEOUT_MS = 10_000;
-/** The pair lease strictly exceeds the request timeout (finding 12). */
 export const PUSH_CLAIM_TTL_MS = 30_000;
 const BACKOFF_MS = [60_000, 300_000, 1_500_000, 7_200_000];
 const MAX_ATTEMPTS = 8;
@@ -36,16 +15,9 @@ const fromB64url = (text) => Buffer.from(text, "base64url");
 export function vapidFingerprint(publicKey) {
     return createHash("sha256").update(publicKey, "utf8").digest("hex").slice(0, 16);
 }
-/** Load the saved pair only (null when none is saved yet): what a page reads (docs/plans/get-side-effects.md). */
 export function loadVapidKeys(dir) {
     return readVapidKeys(join(dir, VAPID_FILE));
 }
-/**
- * Mint-or-load, atomically across processes (finding 29): exclusive
- * creation; the loser of a race re-reads the winner's file; and a loaded
- * pair is VALIDATED — the stored public key must derive from the stored
- * private key, or the file is refused rather than trusted.
- */
 export function loadOrCreateVapidKeys(dir) {
     const path = join(dir, VAPID_FILE);
     const read = () => readVapidKeys(path);
@@ -67,7 +39,6 @@ export function loadOrCreateVapidKeys(dir) {
         return { ...fresh, fingerprint: vapidFingerprint(fresh.publicKey) };
     }
     catch {
-        // Another process won the exclusive create — its keys are the keys.
         const winner = read();
         if (winner === null)
             throw new Error(`could not create or read ${VAPID_FILE}`);
@@ -93,12 +64,6 @@ function readVapidKeys(path) {
     }
     return { publicKey: parsed.publicKey, privateKey: parsed.privateKey, fingerprint: vapidFingerprint(parsed.publicKey) };
 }
-// ---- RFC 8291 encryption ----------------------------------------------------
-/**
- * The deterministic core, exported for the Appendix A vector test: given
- * the subscriber's materials, an application-server ECDH object, and a
- * salt, produce the complete aes128gcm body — header || ciphertext.
- */
 export function encryptWithMaterials(uaPublic, authSecret, asKeys, salt, plaintext) {
     if (uaPublic.length !== 65 || uaPublic[0] !== 0x04)
         throw new Error("subscriber key is not a 65-byte uncompressed P-256 point");
@@ -109,14 +74,11 @@ export function encryptWithMaterials(uaPublic, authSecret, asKeys, salt, plainte
     if (plaintext.length > PLAINTEXT_CEILING)
         throw new Error(`payload over ${PLAINTEXT_CEILING} bytes`);
     const asPublic = asKeys.getPublicKey();
-    // computeSecret rejects off-curve points — the caller maps that throw to
-    // an invalid subscription, never a crash.
     const ecdhSecret = asKeys.computeSecret(uaPublic);
     const keyInfo = Buffer.concat([Buffer.from("WebPush: info", "ascii"), Buffer.from([0]), uaPublic, asPublic]);
     const ikm = Buffer.from(hkdfSync("sha256", ecdhSecret, authSecret, keyInfo, 32));
     const cek = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.concat([Buffer.from("Content-Encoding: aes128gcm", "ascii"), Buffer.from([0])]), 16));
     const nonce = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.concat([Buffer.from("Content-Encoding: nonce", "ascii"), Buffer.from([0])]), 12));
-    // One record: plaintext, the last-record delimiter 0x02, zero padding.
     const record = Buffer.concat([plaintext, Buffer.from([2])]);
     const cipher = createCipheriv("aes-128-gcm", cek, nonce);
     const ciphertext = Buffer.concat([cipher.update(record), cipher.final(), cipher.getAuthTag()]);
@@ -126,21 +88,14 @@ export function encryptWithMaterials(uaPublic, authSecret, asKeys, salt, plainte
     header.writeUInt8(65, 20);
     return Buffer.concat([header, asPublic, ciphertext]);
 }
-/** The production wrapper: fresh ephemeral keys and a fresh salt per message. */
 export function encryptPushPayload(p256dh, auth, plaintext) {
     const ephemeral = createECDH("prime256v1");
     ephemeral.generateKeys();
     return encryptWithMaterials(fromB64url(p256dh), fromB64url(auth), ephemeral, randomBytes(16), Buffer.from(plaintext, "utf8"));
 }
-// ---- RFC 8292 VAPID ---------------------------------------------------------
-/**
- * The VAPID authorization header: an ES256 JWT over { aud, exp, sub? },
- * signed with the STABLE server key (distinct from every message's
- * ephemeral key), in JWS P1363 form — never DER (finding 4).
- */
 export function vapidAuthorization(endpoint, keys, now, contact) {
     const aud = new URL(endpoint).origin;
-    const exp = Math.floor(now.getTime() / 1000) + 12 * 60 * 60; // ≤ 24h per RFC 8292
+    const exp = Math.floor(now.getTime() / 1000) + 12 * 60 * 60;
     const claims = { aud, exp };
     if (contact !== undefined && (contact.startsWith("mailto:") || contact.startsWith("https:")))
         claims["sub"] = contact;
@@ -161,8 +116,6 @@ export function vapidAuthorization(endpoint, keys, now, contact) {
     const signature = cryptoSign("sha256", Buffer.from(signingInput, "utf8"), { key: privateKey, dsaEncoding: "ieee-p1363" });
     return `vapid t=${signingInput}.${b64url(signature)}, k=${keys.publicKey}`;
 }
-// ---- endpoint discipline ----------------------------------------------------
-/** The closed allow-list of push services (finding 7): SSRF dies here. */
 const PUSH_HOSTS = [
     { exact: "fcm.googleapis.com" },
     { suffix: ".push.apple.com" },
@@ -194,7 +147,6 @@ export function validatePushEndpoint(raw) {
         return { ok: false, problem: "that host is not a known push service — extending the list is a code change, deliberately" };
     return { ok: true, url };
 }
-/** Fixed words, except for one validated machine-only suite/count line. */
 export const PUSH_WORDS = {
     decision: { title: "Toolroll", body: "a decision needs you" },
     pick: { title: "Toolroll", body: "agents finished — pick a winner" },
@@ -203,11 +155,7 @@ export const PUSH_WORDS = {
     progress: { title: "Toolroll", body: "checks in progress" },
     release: { title: "Toolroll", body: RELEASE_PUSH_WORDS },
 };
-// `/approve/<n>`: a release's opaque locator (a task ref number: no version, commit or branch), resolved by the console.
 const RELEASE_LINK = /^\/approve\/[0-9]{1,15}$/;
-/** The relative links a push may carry (docs/plans/plain-toolroll.md P1.4): every shape an older worker took, kept for
- * good (/next and /review now redirect to Home and Tasks' Ready view; the rest keep their pages), then Home, Tasks'
- * Ready and Board views, and a task by its stored number (/n/<n>, resolved under the viewer's own access). */
 export const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/, RELEASE_LINK,
     /^\/$/, /^\/tasks\?view=ready$/, /^\/tasks\?view=board$/, /^\/n\/[1-9][0-9]{0,14}$/];
 const CLASS_FALLBACK = {
@@ -218,25 +166,19 @@ const CLASS_FALLBACK = {
     progress: "/",
     release: "/",
 };
-/** Static words and machine-minted numbers only — re-proved at send time. */
 export function safePushLink(pushClass, link) {
-    // The release locator rides only the derived `release` class: a stored link of that shape on any other row is not one.
     if (link !== null && RELEASE_LINK.test(link))
         return pushClass === "release" ? link : CLASS_FALLBACK[pushClass];
     if (link !== null && LINK_SHAPES.some(shape => shape.test(link)))
         return link;
     return CLASS_FALLBACK[pushClass];
 }
-/** One line per ping (docs/plans/plain-toolroll.md P1.5), built only from the task's stored number and fixed words: no
- * title, no free text. A fact about a task opens that task (/n/<n>); anything else keeps its class's fixed words and
- * its own allow-listed link. Rows are tried in order; the first that matches says the line. */
 export const PUSH_LINES = [
     { when: one => one.kind === "plan-ready", say: number => `#${number}: plan ready` },
     { when: one => one.pushClass === "decision" || one.kind === "task-ask" || one.kind === "decision", say: number => `#${number} has a question` },
     { when: one => one.pushClass === "merge" || one.pushClass === "pick" || one.kind === "pull-request-ready" || one.kind === "acceptance-ready", say: number => `#${number} is ready to review` },
     { when: () => true, say: number => `#${number} needs you` },
 ];
-/** The one line a ping says, and where its tap lands. */
 export function pushLineOf(notification) {
     const pushClass = notification.pushClass;
     if (pushClass === "progress" && isCheckProgressLine(notification.body))
@@ -248,20 +190,13 @@ export function pushLineOf(notification) {
     }
     return { body: PUSH_WORDS[pushClass].body, url: safePushLink(pushClass, notification.link) };
 }
-/** `release`: the class and link the plane derived for this row at send time (releasePushOf): fixed words and a release's
- * own link, never the task line. Absent or null, the row's own line. */
 export function buildPushPayload(notification, waiting = null, release = null) {
     const line = release !== null ? { body: PUSH_WORDS.release.body, url: safePushLink("release", release.link) } : pushLineOf(notification);
     return JSON.stringify({
         title: "Toolroll",
         body: line.body,
         url: line.url,
-        // The opaque tag collapses a crash-duplicate on the lock screen.
         tag: release === null && notification.pushClass === "progress" && notification.run !== null ? `so-run-${notification.run}` : `so-${notification.id}`,
-        // The app-icon badge (Phase 2E, v2 S4): the server-computed
-        // waiting-on-you COUNT at send time — a number, never content, so the
-        // closed-class discipline holds. The console page recomputes and
-        // clears; a stale push never outranks a fresh page.
         ...(waiting === null ? {} : { waiting }),
     });
 }
@@ -274,35 +209,25 @@ function backoffFor(attempts, retryAfter, now) {
     const step = BACKOFF_MS[Math.min(Math.max(attempts - 1, 0), BACKOFF_MS.length - 1)];
     return new Date(now.getTime() + step);
 }
-/**
- * One pass: seed, claim, and for each pair — renew, fence, encrypt, send,
- * settle by the outcome table. Every settle is conditional on the claim's
- * owner AND generation; a lapsed claim writes nothing.
- */
 export async function pushPass(store, options) {
     const clock = options.clock ?? (() => new Date());
     const owner = options.owner ?? `push-${randomBytes(4).toString("hex")}`;
     const doFetch = options.fetchImpl ?? (async (url, init) => fetch(url, init));
     const report = { seeded: 0, accepted: 0, rescheduled: 0, rejected: 0, retired: 0, credentialProblem: false };
     if (store.isDemo())
-        return report; // a sandbox never pushes
+        return report;
     const keys = loadOrCreateVapidKeys(options.configDir);
-    // Subscriptions are bound to the key they enrolled under (finding 27):
-    // after a regeneration they reject every message — retire them visibly.
     report.retired += store.retirePushSubscriptionsOfOtherKeys(keys.fingerprint, clock());
     report.seeded = store.seedPushPairs(clock());
     const pairs = store.claimPushPairs(owner, PUSH_CLAIM_TTL_MS, 32, clock());
     let sawAccepted = false;
     for (const pair of pairs) {
-        // Renew and re-fence immediately before the network (finding 12).
         if (!store.renewPushClaim(pair.id, owner, pair.claimGeneration, PUSH_CLAIM_TTL_MS, clock()))
             continue;
         const fenced = store.pushSendFence(pair.id, owner, pair.claimGeneration, clock());
         if (fenced === null)
-            continue; // resolved, retired, rotated, or lost — nothing to send
+            continue;
         const subscription = fenced.subscriptionRow;
-        // A release's "ready for your approval" that no longer stands (approved, superseded, put away) is resolved, never
-        // sent; one that stands is sent as `release`, its class and link derived from the plane's state now.
         if (releaseReadyObsolete(store, fenced.notificationRow)) {
             store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE id = ? AND resolved_at IS NULL").run(clock().toISOString(), fenced.notificationRow.id);
             continue;
@@ -316,14 +241,9 @@ export async function pushPass(store, options) {
         }
         let body;
         try {
-            body = encryptPushPayload(subscription.p256dh, subscription.auth, 
-            // The badge count rides every push: the same inbox classifier the
-            // console's own sidebar badge reads, unscoped (a phone has no
-            // project pane), computed at send time.
-            buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count, release));
+            body = encryptPushPayload(subscription.p256dh, subscription.auth, buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count, release));
         }
         catch {
-            // Off-curve or malformed subscriber material: the device, not us.
             store.retirePushSubscription(subscription.id, "invalid-keys", clock());
             report.retired += 1;
             continue;
@@ -348,9 +268,8 @@ export async function pushPass(store, options) {
             retryAfter = answer.headers.get("retry-after");
         }
         catch {
-            status = 0; // network / timeout / redirect refusal
+            status = 0;
         }
-        // The outcome table (finding 18).
         if (status >= 200 && status < 300) {
             if (store.settlePushPair(pair.id, owner, pair.claimGeneration, { kind: "accepted" }, clock()))
                 report.accepted += 1;
@@ -366,8 +285,6 @@ export async function pushPass(store, options) {
             }
         }
         else if (status === 401 || status === 403) {
-            // A CREDENTIAL problem, never a device problem: no retirement, and
-            // one deduped, UNSTAMPED operator episode (finding 27).
             report.credentialProblem = true;
             store.enqueueEpisode(`push-credentials:${keys.fingerprint}`, {
                 source: { installation: true },
@@ -381,7 +298,6 @@ export async function pushPass(store, options) {
             settleRetryOrGiveUp(store, pair.id, owner, pair.claimGeneration, pair.attempts, status === 0 ? "the push service could not be reached" : `push service answered ${status}`, retryAfter, clock(), report);
         }
     }
-    // A working credential closes the episode (finding 27).
     if (sawAccepted)
         store.resolveEpisodes(`push-credentials:${keys.fingerprint}`, clock());
     return report;

package/dist/quick-start.js

@@ -1,13 +1,3 @@
-/**
- * BARE `toolroll` IN A REPOSITORY (docs/plans/agents-cockpit.md B1): the two-action start.
- *
- * Inside a git repository, `toolroll` with nothing else (or only --json) either starts the console for it (`up`), or —
- * when this installation's console is already running and PROVES it is (console-instance.ts: a fresh challenge on the
- * discovery socket and on its HTTP listener, answered with the secret in the database this CLI opened itself) —
- * adds the repository through the ordinary project admission and opens that proved console. Under an agent, or with
- * --json, it starts nothing and changes nothing: it says what it would do. Outside a repository, it scans as before
- * (the scan is also `toolroll scan`).
- */
 import { lstatSync, realpathSync } from "node:fs";
 import { proveLiveConsole } from "./console-instance.js";
 import { underAgent } from "./prompt.js";
@@ -15,12 +5,9 @@ import { envelopeJson } from "./envelope.js";
 import { createRequire } from "node:module";
 import { openStoreReadOnly, readSchemaVersion, SCHEMA_VERSION } from "./store.js";
 const EXIT = { ok: 0, refused: 3 };
-/** Whether argv is a bare `toolroll` (nothing, or only --json). */
 export const isBareInvocation = (argv) => argv.every(one => one === "--json");
-/** The database's schema version by the store's own strict reader, read without changing anything. */
 function schemaOf(file) {
     try {
-        // Loaded only here, as the store loads it: the CLI's other commands never pay for (or warn about) it.
         const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
         const db = new DatabaseSync(file, { readOnly: true });
         try {
@@ -35,7 +22,6 @@ function schemaOf(file) {
         return { ok: false };
     }
 }
-/** Whether the database file is there: "absent" only when the system says so (ENOENT), never for a path it won't show. */
 function databasePresence(file) {
     try {
         lstatSync(file);
@@ -48,12 +34,8 @@ function databasePresence(file) {
 function prove(seams) {
     return proveConsoleReadOnly(seams.databaseFile, seams.build, seams.attach ?? {});
 }
-/** This database's console, proved live without creating, migrating or changing anything (also easy-start.ts's). */
 export async function proveConsoleReadOnly(databaseFile, build, attach = {}) {
     const seams = { databaseFile, build, attach };
-    // Read only, never created or migrated, never cleaned up: proving changes nothing. "None" only when nothing of this
-    // build can be running on it (no database yet, or one older than this build, which `up` brings up to date); a
-    // database that can't be read, is mid-upgrade or is newer than this build can't be checked, so it is refused.
     const none = { ok: false, state: "none", message: "no console is running" };
     const unverifiable = (why) => ({ ok: false, state: "refused", message: `${why}, so a running console can't be checked — run \`toolroll up\` to see what's wrong` });
     const presence = databasePresence(seams.databaseFile);
@@ -81,7 +63,6 @@ export async function proveConsoleReadOnly(databaseFile, build, attach = {}) {
         store.close();
     }
 }
-/** null: not this command (outside a repository) — the caller scans as before. */
 export async function runQuickStart(argv, write, seams) {
     const found = await seams.findRepo(seams.cwd);
     if (found === null)
@@ -90,14 +71,13 @@ export async function runQuickStart(argv, write, seams) {
     try {
         repo = realpathSync(found);
     }
-    catch { /* as found */ }
+    catch { }
     const json = argv.includes("--json");
     const dry = json || (seams.underAgent ?? underAgent(seams.env));
     const proof = await prove(seams);
     const enrolled = await seams.enrolled(repo);
     const would = proof.ok ? (enrolled ? "open" : "add-and-open") : proof.state === "none" ? "start" : "refuse";
     if (dry) {
-        // Nothing starts, nothing is added, nothing opens: what a person would get, in words or one envelope.
         const words = would === "start" ? `Would start Toolroll for ${repo} (toolroll up).`
             : would === "refuse" ? `Would refuse: ${proof.message}.`
                 : `Would ${would === "add-and-open" ? `add ${repo} and ` : ""}open the running console at ${proof.url}.`;
@@ -118,8 +98,6 @@ export async function runQuickStart(argv, write, seams) {
         if (admitted !== 0)
             return admitted;
     }
-    // Whatever happened since the first proof (reading the registry, adding the project), the console is proved again,
-    // on both channels, right before its address is shown or opened — never a listener that took the port meanwhile.
     const again = await prove(seams);
     if (!again.ok || again.url !== proof.url || again.pid !== proof.pid) {
         write(`Toolroll can't attach: ${again.ok ? "the console changed while the project was being added" : again.message} — run \`toolroll up\`.`);

package/dist/read-executor-worker.js

@@ -2,7 +2,6 @@ import { parentPort, workerData } from 'node:worker_threads';
 import { openStoreReadOnly } from './store.js';
 import { workCountsByProject, workIndexPage } from './work-index.js';
 import { projectSummaryOf } from './console-chrome.js';
-/** One read-only, query-only connection per worker (read-executor.ts). Jobs arrive one at a time. */
 let store = null;
 function connection() {
     if (store !== null)

package/dist/read-executor.js

@@ -1,7 +1,6 @@
 import { Worker } from 'node:worker_threads';
 import { availableParallelism } from 'node:os';
 import { WorkIndexCursorError } from './work-index.js';
-/** More queued reads than this fail at once instead of growing without bound. */
 export const READ_QUEUE_MAX = 1_000;
 export class ReadExecutorError extends Error {
     constructor(message) { super(message); this.name = 'ReadExecutorError'; }
@@ -18,7 +17,6 @@ export class ReadExecutor {
         this.#size = Math.max(1, Math.floor(size));
     }
     get size() { return this.#size; }
-    /** workIndexPage(store, now, access, options) on a worker's read-only connection: same rows, same errors. */
     async workIndexPage(now, access, options) {
         try {
             return await this.#run({ kind: 'work-index-page', now: now.toISOString(), access, options });
@@ -29,11 +27,9 @@ export class ReadExecutor {
             throw error;
         }
     }
-    /** workCountsByProject(store, now, access) on a worker: the console's Tasks count and live beat. */
     async workCounts(now, access) {
         return await this.#run({ kind: 'work-counts', now: now.toISOString(), access });
     }
-    /** projectSummaryOf (console-chrome.ts) on a worker: the sidebar's project states for one already-admitted reader. */
     async projectSummary(now, access, actor, projects, evidenceRoot) {
         return await this.#run({ kind: 'project-summary', now: now.toISOString(), access, actor, projects: projects.map(one => ({ path: one.path, name: one.name })), evidenceRoot: evidenceRoot ?? null });
     }
@@ -60,7 +56,6 @@ export class ReadExecutor {
         }
     }
     #spawn() {
-        // The installed server runs the built sibling; tests run the TypeScript source through tsx.
         const worker = import.meta.url.endsWith('.ts')
             ? new Worker(`import('tsx/esm/api').then(tsx => { tsx.register(); return import(${JSON.stringify(new URL('./read-executor-worker.ts', import.meta.url).href)}); });`, { eval: true, workerData: { file: this.#file } })
             : new Worker(new URL('./read-executor-worker.js', import.meta.url), { workerData: { file: this.#file } });
@@ -77,7 +72,6 @@ export class ReadExecutor {
                 pending.reject(Object.assign(new Error(reply.error.message), { name: reply.error.name }));
             this.#pump();
         });
-        // A crashed worker fails only the read it held; the next read starts a fresh one.
         const lost = (error) => {
             const at = this.#slots.indexOf(slot);
             if (at < 0)
@@ -94,7 +88,6 @@ export class ReadExecutor {
         worker.unref();
         return slot;
     }
-    /** Fails every queued and running read once, then stops the workers. */
     async close() {
         if (this.#closed)
             return;
@@ -110,13 +103,10 @@ export class ReadExecutor {
         await Promise.all(slots.map(slot => slot.worker.terminate().catch(() => 0)));
     }
 }
-/** Half the cores, at most eight: the measured 20-engineer load needs over four (docs/server-performance.md),
- * and the rest stay with the event loop and local agents. Workers start only when reads arrive. */
 export function defaultReadWorkers() {
     return Math.max(1, Math.min(8, Math.floor(availableParallelism() / 2)));
 }
 const attached = new WeakMap();
-/** The server attaches its executor to its own Store; a command run on that Store reads through it. */
 export function attachReadExecutor(store, executor) {
     attached.set(store, executor);
     return () => { if (attached.get(store) === executor)

package/dist/read-only-request.js

@@ -1,15 +1,8 @@
-/**
- * A page visit only reads (docs/plans/get-side-effects.md). The server runs every GET and HEAD inside this scope, and
- * the few store reads that used to tidy up as they went (closing an operating mode past its expiry) check it and
- * leave the tidying to the background pass and the paths that act.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 const scope = new AsyncLocalStorage();
-/** Run a GET or HEAD request's work. */
 export function asReadOnlyRequest(work) {
     return scope.run(true, work);
 }
-/** Whether the current work answers a GET or HEAD request. */
 export function inReadOnlyRequest() {
     return scope.getStore() === true;
 }

package/dist/recipe-ui.js

@@ -30,7 +30,6 @@ export function recipeFromForm(body) {
             continue;
         acceptance.push({ id: body.get(`criterion-${i}-id`) || `c${i + 1}`, statement, how: how || null, evidence: body.getAll(`criterion-${i}-evidence`) });
     }
-    // Never silently omit submitted checks beyond the editor's bounded size.
     for (const key of body.keys())
         if (/^criterion-/.test(key) && (!/^criterion-(?:[0-9]|1[01])-(?:statement|how|id|evidence)$/.test(key)))
             throw new RecipeError("A recipe supports at most 12 success checks.");
@@ -55,8 +54,6 @@ export function recipeFromForm(body) {
     return parseRecipe({ format: "standing-orders-recipe", version: inputs.length ? 2 : 1, ...(inputs.length ? { inputs } : {}), name: body.get("name") ?? "", description: body.get("description") ?? "", goal: body.get("goal") ?? "", outOfScope: body.get("not") || null,
         touches: (body.get("touches") ?? "").split(/[\n,]/).map(one => one.trim()).filter(Boolean), acceptance, planning: body.get("planning") ?? "auto", deliverable: body.get("deliverable") ?? "branch", schedule: schedule.schedule, costCeilingUsd: ceiling === "" ? null : Number(ceiling) });
 }
-/** "One-time work" (New flow): the open project's recipes and the starters as rows, each with one "Use this"; then
- * Create a recipe, importing a shared one, and the work recipes made lately. */
 export function recipeRowsHtml(starters, saved, project, projectName, revision, recent) {
     const kind = (recipe) => `${recipe.document.deliverable === "report" ? "Report" : "Code change"} · ${recipe.document.schedule === null ? "runs once as a task" : "repeats on a schedule"}${recipe.document.version === 2 ? ` · ${recipe.document.inputs.length} question${recipe.document.inputs.length === 1 ? "" : "s"}` : ""}`;
     const rowOf = (recipe, reusable) => templateRow({ name: recipe.document.name, promise: recipe.document.description, line: kind(recipe), attrs: html ` data-recipe-card data-recipe="${recipe.id}"`,
@@ -72,7 +69,6 @@ function criterionHtml(index, criterion, values) {
     const selected = values ? values.getAll(prefix + "evidence") : criterion?.evidence ?? ["check"];
     return html `<fieldset class="recipe-criterion"><legend>${criterion || index === 0 ? `Success check ${index + 1}` : "Additional success check (optional)"}</legend>${hidden(prefix + "id", value("id", criterion?.id ?? `c${index + 1}`))}<label>What should be true?<textarea name="${prefix}statement" rows="2" maxlength="300">${value("statement", criterion?.statement ?? "")}</textarea></label><div class="recipe-evidence">${evidence.map(([id, label]) => html `<label><input type="checkbox" name="${prefix}evidence" value="${id}"${selected.includes(id) && html ` checked`}>${label}</label>`)}</div><label>How to check it <span class="meta">optional; command or review instructions</span><input type="text" name="${prefix}how" value="${value("how", criterion?.how ?? "")}" maxlength="500"></label></fieldset>`;
 }
-/** The blank success check the page's script copies, its numbers left for the script to fill in. */
 const criterionTemplate = () => replaceMarkup(criterionHtml(11), /criterion-11-|value="c12"/g, match => match === "criterion-11-" ? html `criterion-INDEX-` : html `value="cNEXT"`);
 export function recipeEditorHtml(recipe, repo, revision, problem = null, values, creator = false) {
     const d = recipe.document;
@@ -86,7 +82,6 @@ export function recipeEditorHtml(recipe, repo, revision, problem = null, values,
     const actions = html `<div class="sticky-actions"><button type="submit" name="purpose" value="${creator ? "recipe" : "workflow"}">${creator ? "Preview recipe →" : "Preview workflow →"}</button>${!creator && html `<button type="submit" name="purpose" value="recipe" class="quiet">Preview recipe to save</button>`}<p class="meta">${creator ? "Save the instructions once. You can use the recipe whenever this work comes up." : "Previewing runs no agents. You’ll see the approval and scheduling steps next."}</p></div>`;
     return html `<a href="/recipes" class="meta">← All recipes</a><div class="recipe-heading"><p class="recipe-kicker">${creator ? "1 · Describe → 2 · Preview → 3 · Save" : "1 · Choose → 2 · Customize → 3 · Preview"}</p><h1>${creator ? "Create a reusable recipe" : "Make this workflow yours"}</h1><p class="hint">${repo.split(/[\\/]/).pop() || repo} · Choose the outcome, boundaries, and proof you want back.</p></div>${problem !== null && html `<p role="alert" class="card recipe-error">${problem}</p>`}${postForm("/recipes/preview", html `${outcome}${recipeQuestionsHtml(d, values)}${success}${running}${actions}`, { attrs: { class: "recipe-editor" }, projectRevision: String(revision), hidden: { repo, source: recipe.id, sourceRevision: String(recipe.revision), sourceFormat: value("sourceFormat", String(d.version)) } })}`;
 }
-/** What a success check's evidence is called, for a reader. */
 const evidenceWords = (kinds) => joinHtml(kinds.map(kind => evidence.find(([id]) => id === kind)?.[1] ?? kind), " · ");
 export function workflowPreviewHtml(preview, revision, now, readiness, auto) {
     const d = preview.document;
@@ -101,7 +96,6 @@ function inputHtml(index, input, values) {
     const value = (field, fallback) => values?.get(`input-${index}-${field}`) ?? fallback;
     return html `<fieldset class="recipe-question"><legend>Question ${index + 1}</legend><div class="recipe-options"><label>Short key<input type="text" name="input-${index}-key" value="${value("key", input?.key ?? "")}" maxlength="32" placeholder="module" pattern="[a-z][a-z0-9_]{0,31}"></label><label>What should we ask?<input type="text" name="input-${index}-label" value="${value("label", input?.label ?? "")}" maxlength="80" placeholder="Which module should we work on?"></label></div><label>Default answer <span class="meta">optional</span><input type="text" name="input-${index}-default" value="${value("default", input?.defaultValue ?? "")}" maxlength="500"></label><p class="meta">Use <code data-question-token>{{${value("key", input?.key ?? "module") || "module"}}}</code> in your instructions or a success check. Clear this row and its placeholders to remove the question.</p><button type="button" data-insert-question hidden>Insert into instructions</button></fieldset>`;
 }
-/** The blank question the page's script copies, its numbers left for the script to fill in (the first "Question 8" only, as before). */
 const questionTemplate = () => {
     let numbered = false;
     return replaceMarkup(inputHtml(7), /input-7-|Question 8/g, match => match === "input-7-" ? html `input-INDEX-` : numbered ? null : (numbered = true, html `Question NEXT`));

package/dist/recipes.js

@@ -1,7 +1,3 @@
-/** Reusable work definitions. Recipes carry scope, never credentials or grants.
- * A preview freezes the exact copy to file; its durable receipt makes a retry
- * after a lost response return the same task or flow, even after a restart.
- * A repeating recipe (v115) makes a scheduled flow whose schedule starts paused. */
 import { createHash, randomBytes } from "node:crypto";
 import { TEMPLATES } from "./templates.js";
 import { hasDisguisedText, hasForbiddenControls } from "./decision.js";
@@ -49,7 +45,6 @@ export class RecipeError extends Error {
 }
 const honest = (text) => !hasForbiddenControls(text) && !hasDisguisedText(text);
 const recipeProject = (repo) => {
-    // A project folder the console's gate holds back (folder-gate.ts) is unavailable, never matched by its spelling.
     try {
         return canonicalProject(repo) ?? resolve(repo);
     }
@@ -59,7 +54,6 @@ const recipeProject = (repo) => {
         throw error;
     }
 };
-/** What a refusal at each top-level field tells the person, after the path-named line. */
 const FIELD_ADVICE = {
     name: "Name, goal, exclusions, and allowed paths must be readable text.", description: "Name, goal, exclusions, and allowed paths must be readable text.",
     goal: "Name, goal, exclusions, and allowed paths must be readable text.", outOfScope: "Name, goal, exclusions, and allowed paths must be readable text.",
@@ -68,7 +62,6 @@ const FIELD_ADVICE = {
     schedule: "Choose a valid schedule.", costCeilingUsd: "The weekly budget must be a positive dollar amount.",
 };
 const FIELDS_MISMATCH = "Recipe fields do not match this version. Recipes contain work definitions, not permissions, credentials, or agent settings.";
-/** The one refusal a recipe structure gets: its first path-named line, with the advice for that field. */
 function structureError(issues) {
     const top = issues.find(one => one.kind === "unknown-key" && one.path === "payload") ?? issues.find(one => one.kind === "required" && !/[.[]/.test(one.path));
     if (top !== undefined)
@@ -89,12 +82,10 @@ function structureError(issues) {
                         : "Questions contain only a key, label, and optional default answer.";
         return new RecipeError(`${first.line}. ${advice}`);
     }
-    // Zod states `positive` as an exclusive minimum ("at least 0"); the advice says it plainly.
     if (field === "costCeilingUsd" && first.kind === "bad-value")
         return new RecipeError(`costCeilingUsd: ${FIELD_ADVICE[field]}`);
     return new RecipeError(`${first.line}. ${FIELD_ADVICE[field] ?? FIELDS_MISMATCH}`);
 }
-/** Reject unknown fields, including approval/provider settings, on import. */
 export function parseRecipe(input) {
     if (typeof input !== "object" || input === null || Array.isArray(input))
         throw new RecipeError("Choose a recipe document.");
@@ -129,7 +120,6 @@ export function parseRecipe(input) {
         throw new RecipeError(parsed.problems.map(one => one.message).join("; ") || "acceptance: Add at least one success check.");
     const fields = { format: RECIPE_FORMAT, name: doc.name.trim(), description: doc.description.trim(), goal: doc.goal.trim(), outOfScope: doc.outOfScope?.trim() || null,
         touches: [...doc.touches], acceptance: parsed.criteria, planning: doc.planning, deliverable: doc.deliverable, schedule: doc.schedule, costCeilingUsd: doc.costCeilingUsd };
-    // Keep v1's canonical key order stable: existing immutable digests must survive.
     const ordered = { format: fields.format, version: doc.version, name: fields.name, description: fields.description, goal: fields.goal,
         outOfScope: fields.outOfScope, touches: fields.touches, acceptance: fields.acceptance, planning: fields.planning, deliverable: fields.deliverable,
         schedule: fields.schedule, costCeilingUsd: fields.costCeilingUsd, ...(doc.version === 2 ? { inputs: parseRecipeInputs(doc.inputs) } : {}) };
@@ -156,7 +146,6 @@ export function importRecipe(text) {
 }
 export const recipeDigest = (document) => createHash("sha256").update(JSON.stringify(document)).digest("hex");
 export const exportRecipe = (document) => JSON.stringify(parseRecipe(document), null, 2) + "\n";
-/** Inputs are literal work text, never a program, path grant, or shell fragment. Their shape is already read. */
 function parseRecipeInputs(inputs) {
     const seen = new Set();
     return inputs.map(({ key, label, defaultValue }, index) => {
@@ -216,7 +205,6 @@ export function resolveRecipe(document, answers) {
     return parseRecipe({ ...fields, version: 1, name: expand(parsed.name), description: expand(parsed.description), goal: expand(parsed.goal), outOfScope: parsed.outOfScope === null ? null : expand(parsed.outOfScope),
         acceptance: parsed.acceptance.map(one => ({ ...one, statement: expand(one.statement) })) });
 }
-/** Only the stored definition supplies scope; form answers cannot replace it. */
 export function prepareRecipeRun(store, actor, repo, id, revision, answers, now) {
     repo = recipeProject(repo);
     return store.transact(() => {
@@ -328,7 +316,6 @@ export function launchWorkflow(store, actor, repo, token, now, operatorFiling) {
         }
         else {
             const slug = d.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "workflow";
-            // A scheduled flow whose schedule starts paused: nothing repeats until a person turns it on.
             const made = createScheduledFlow(store, { repo, name: d.name, stem: `${slug}-${token.slice(0, 8)}`, schedule: d.schedule, by: actor,
                 terms: { goal: d.goal, outOfScope: d.outOfScope, touches: d.touches, requirements: [], acceptance: d.acceptance, budgetPerRunMicrousd: null, costCeilingUsd: d.costCeilingUsd } }, now);
             if (!made.ok)