toolroll 0.5.0

package/dist/recipes.d.ts

@@ -0,0 +1,81 @@
+import type { Store } from "./store.js";
+import { type AcceptanceCriterion } from "./scope.js";
+export declare const RECIPE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS workflow_recipe (\n  id TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),\n  repo TEXT NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL,\n  author TEXT NOT NULL, created_at TEXT NOT NULL,\n  PRIMARY KEY(id, revision)\n);\nCREATE INDEX IF NOT EXISTS workflow_recipe_project ON workflow_recipe(repo, id, revision DESC);\nCREATE TRIGGER IF NOT EXISTS workflow_recipe_no_update BEFORE UPDATE ON workflow_recipe\nBEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;\nCREATE TRIGGER IF NOT EXISTS workflow_recipe_no_delete BEFORE DELETE ON workflow_recipe\nBEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;\nCREATE TABLE IF NOT EXISTS workflow_preview (\n  token TEXT PRIMARY KEY, actor TEXT NOT NULL, repo TEXT NOT NULL,\n  document TEXT NOT NULL, digest TEXT NOT NULL, source TEXT NOT NULL,\n  created_at TEXT NOT NULL, expires_at TEXT NOT NULL,\n  task_id TEXT REFERENCES task(id), routine_id INTEGER REFERENCES routine(id),\n  saved_id TEXT, saved_revision INTEGER,\n  CHECK(task_id IS NULL OR routine_id IS NULL),\n  FOREIGN KEY(saved_id, saved_revision) REFERENCES workflow_recipe(id, revision)\n);\nCREATE INDEX IF NOT EXISTS workflow_preview_project ON workflow_preview(repo, created_at DESC);\nCREATE INDEX IF NOT EXISTS workflow_preview_source ON workflow_preview(repo, source, created_at DESC)\nWHERE task_id IS NOT NULL OR routine_id IS NOT NULL;\n";
+type RecipeFields = {
+    format: "standing-orders-recipe";
+    name: string;
+    description: string;
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: AcceptanceCriterion[];
+    planning: "auto" | "required" | "skip";
+    deliverable: "branch" | "report";
+    schedule: string | null;
+    costCeilingUsd: number | null;
+};
+export type RecipeInput = {
+    key: string;
+    label: string;
+    defaultValue: string | null;
+};
+export type RecipeDocument = RecipeFields & ({
+    version: 1;
+    inputs?: never;
+} | {
+    version: 2;
+    inputs: RecipeInput[];
+});
+export declare const RECIPE_INPUT_LIMIT = 8;
+export type RecipeAnswers = ReadonlyMap<string, string>;
+export type Recipe = {
+    id: string;
+    revision: number;
+    repo: string | null;
+    document: RecipeDocument;
+    digest: string;
+    author: string;
+};
+export type WorkflowPreview = {
+    token: string;
+    actor: string;
+    repo: string;
+    document: RecipeDocument;
+    digest: string;
+    source: string;
+    expiresAt: string;
+    taskId: string | null;
+    routineId: number | null;
+    savedId: string | null;
+    savedRevision: number | null;
+};
+export declare class RecipeError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** Reject unknown fields, including approval/provider settings, on import. */
+export declare function parseRecipe(input: unknown): RecipeDocument;
+export declare function importRecipe(text: string): RecipeDocument;
+export declare const recipeDigest: (document: RecipeDocument) => string;
+export declare const exportRecipe: (document: RecipeDocument) => string;
+export declare function resolveRecipe(document: RecipeDocument, answers: RecipeAnswers): RecipeDocument & {
+    version: 1;
+};
+/** Only the stored definition supplies scope; form answers cannot replace it. */
+export declare function prepareRecipeRun(store: Store, actor: string, repo: string, id: string, revision: number, answers: RecipeAnswers, now: Date): WorkflowPreview;
+export declare function starterRecipes(): Recipe[];
+export declare function savedRecipes(store: Store, actor: string, repo: string): Recipe[];
+export declare function findRecipe(store: Store, actor: string, repo: string | null, id: string, revision?: number): Recipe | null;
+export declare function createWorkflowPreview(store: Store, actor: string, repo: string, document: RecipeDocument, source: string, now: Date): WorkflowPreview;
+export declare function workflowPreview(store: Store, actor: string, repo: string, token: string): WorkflowPreview | null;
+export declare function launchWorkflow(store: Store, actor: string, repo: string, token: string, now: Date, operatorFiling: boolean): {
+    taskId: string | null;
+    routineId: number | null;
+};
+export declare function saveWorkflowRecipe(store: Store, actor: string, repo: string, token: string, now: Date): Recipe;
+export declare function workflowSteps(document: RecipeDocument): {
+    title: string;
+    detail: string;
+}[];
+export declare function recipeScheduleWords(document: RecipeDocument, now: Date): string;
+export {};

package/dist/recipes.js

@@ -0,0 +1,332 @@
+/** 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/routine, even after a restart. */
+import { createHash, randomBytes } from "node:crypto";
+import { TEMPLATES } from "./templates.js";
+import { hasDisguisedText, hasForbiddenControls } from "./decision.js";
+import { parseAcceptanceCriteria } from "./scope.js";
+import { validateTaskText, fileTaskProposal, fileRoutineProposal } from "./proposal.js";
+import { parseSchedule, firstFireAt, describeSchedule, validateRoutineTerms } from "./routine.js";
+import { applyModeToNewFiling } from "./plan-auto.js";
+import { canonicalProject } from "./project.js";
+import { resolve } from "node:path";
+export const RECIPE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS workflow_recipe (
+  id TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),
+  repo TEXT NOT NULL, document TEXT NOT NULL, digest TEXT NOT NULL,
+  author TEXT NOT NULL, created_at TEXT NOT NULL,
+  PRIMARY KEY(id, revision)
+);
+CREATE INDEX IF NOT EXISTS workflow_recipe_project ON workflow_recipe(repo, id, revision DESC);
+CREATE TRIGGER IF NOT EXISTS workflow_recipe_no_update BEFORE UPDATE ON workflow_recipe
+BEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS workflow_recipe_no_delete BEFORE DELETE ON workflow_recipe
+BEGIN SELECT RAISE(ABORT, 'recipe revisions are immutable'); END;
+CREATE TABLE IF NOT EXISTS workflow_preview (
+  token TEXT PRIMARY KEY, actor TEXT NOT NULL, repo TEXT NOT NULL,
+  document TEXT NOT NULL, digest TEXT NOT NULL, source TEXT NOT NULL,
+  created_at TEXT NOT NULL, expires_at TEXT NOT NULL,
+  task_id TEXT REFERENCES task(id), routine_id INTEGER REFERENCES routine(id),
+  saved_id TEXT, saved_revision INTEGER,
+  CHECK(task_id IS NULL OR routine_id IS NULL),
+  FOREIGN KEY(saved_id, saved_revision) REFERENCES workflow_recipe(id, revision)
+);
+CREATE INDEX IF NOT EXISTS workflow_preview_project ON workflow_preview(repo, created_at DESC);
+CREATE INDEX IF NOT EXISTS workflow_preview_source ON workflow_preview(repo, source, created_at DESC)
+WHERE task_id IS NOT NULL OR routine_id IS NOT NULL;
+`;
+export const RECIPE_INPUT_LIMIT = 8;
+export class RecipeError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+const keys = ["format", "version", "name", "description", "goal", "outOfScope", "touches", "acceptance", "planning", "deliverable", "schedule", "costCeilingUsd"];
+const honest = (text) => !hasForbiddenControls(text) && !hasDisguisedText(text);
+const recipeProject = (repo) => canonicalProject(repo) ?? resolve(repo);
+/** 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.");
+    if (Buffer.byteLength(JSON.stringify(input), "utf8") > 32_768)
+        throw new RecipeError("A recipe must be at most 32 KB.");
+    const raw = input;
+    if (raw.format !== "standing-orders-recipe" || (raw.version !== 1 && raw.version !== 2))
+        throw new RecipeError("This recipe format/version is not supported.");
+    const expected = raw.version === 2 ? [...keys, "inputs"] : keys;
+    if (Object.keys(raw).some(key => !expected.includes(key)) || expected.some(key => !Object.hasOwn(raw, key)))
+        throw new RecipeError("Recipe fields do not match this version. Recipes contain work definitions, not permissions, credentials, or agent settings.");
+    if (typeof raw.name !== "string" || typeof raw.description !== "string" || typeof raw.goal !== "string" || (raw.outOfScope !== null && typeof raw.outOfScope !== "string") || !Array.isArray(raw.touches) || raw.touches.some(path => typeof path !== "string"))
+        throw new RecipeError("Name, goal, exclusions, and allowed paths must be readable text.");
+    if (raw.description.length > 400 || !honest(raw.description))
+        throw new RecipeError("Keep the description within 400 characters, without hidden text.");
+    const bad = validateTaskText({ title: raw.name, goal: raw.goal, outOfScope: raw.outOfScope, touches: raw.touches });
+    if (bad !== null)
+        throw new RecipeError(bad.message);
+    if (!["auto", "required", "skip"].includes(String(raw.planning)) || !["branch", "report"].includes(String(raw.deliverable)))
+        throw new RecipeError("Choose a supported planning and result type.");
+    if (raw.schedule !== null && (typeof raw.schedule !== "string" || parseSchedule(raw.schedule) === null))
+        throw new RecipeError("Choose a valid schedule.");
+    if (raw.costCeilingUsd !== null && (typeof raw.costCeilingUsd !== "number" || !Number.isFinite(raw.costCeilingUsd) || raw.costCeilingUsd <= 0))
+        throw new RecipeError("The weekly budget must be a positive dollar amount.");
+    if (raw.schedule === null && raw.costCeilingUsd !== null)
+        throw new RecipeError("A weekly budget applies to a repeating workflow. One-time work uses the project's task budget.");
+    if (raw.deliverable === "report" && raw.schedule !== null)
+        throw new RecipeError("Report recipes run once. Repeating workflows currently produce code changes.");
+    if (raw.schedule !== null && raw.planning === "required")
+        throw new RecipeError("Plan-first recipes run once. Repeating workflows reuse their approved scope; choose direct execution or run once.");
+    if (!Array.isArray(raw.acceptance) || raw.acceptance.some(one => typeof one !== "object" || one === null || Object.keys(one).some(key => !["id", "statement", "how", "evidence"].includes(key))))
+        throw new RecipeError("Success checks have unsupported fields.");
+    const parsed = parseAcceptanceCriteria(raw.acceptance);
+    if (parsed.problems.length > 0 || parsed.criteria.length === 0)
+        throw new RecipeError(parsed.problems.map(one => one.message).join("; ") || "Add at least one success check.");
+    const fields = { format: "standing-orders-recipe", name: raw.name.trim(), description: raw.description.trim(), goal: raw.goal.trim(), outOfScope: raw.outOfScope?.trim() || null,
+        touches: [...raw.touches], acceptance: parsed.criteria, planning: raw.planning, deliverable: raw.deliverable, schedule: raw.schedule, costCeilingUsd: raw.costCeilingUsd };
+    const document = raw.version === 1 ? { ...fields, version: 1 } : { ...fields, version: 2, inputs: parseRecipeInputs(raw.inputs) };
+    // Keep v1's canonical key order stable: existing immutable digests must survive.
+    const ordered = { format: document.format, version: document.version, name: document.name, description: document.description, goal: document.goal,
+        outOfScope: document.outOfScope, touches: document.touches, acceptance: document.acceptance, planning: document.planning, deliverable: document.deliverable,
+        schedule: document.schedule, costCeilingUsd: document.costCeilingUsd, ...(document.version === 2 ? { inputs: document.inputs } : {}) };
+    if (ordered.version === 2)
+        validateInputReferences(ordered);
+    if (document.schedule !== null) {
+        const problems = validateRoutineTerms({ repo: "/recipe-preview", ...document, requirements: [], schedule: document.schedule, singleFlight: true });
+        if (problems.length)
+            throw new RecipeError(problems.map(one => `${one.field}: ${one.problem}`).join("; "));
+    }
+    return ordered;
+}
+export function importRecipe(text) {
+    if (Buffer.byteLength(text, "utf8") > 32_768)
+        throw new RecipeError("A recipe must be at most 32 KB.");
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new RecipeError("That is not valid recipe JSON.");
+    }
+    return parseRecipe(value);
+}
+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. */
+function parseRecipeInputs(raw) {
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > RECIPE_INPUT_LIMIT)
+        throw new RecipeError("Add between 1 and 8 questions, or remove the empty questions to save a fixed recipe.");
+    const seen = new Set();
+    return raw.map(input => {
+        if (input === null || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some(key => !["key", "label", "defaultValue"].includes(key)))
+            throw new RecipeError("Questions contain only a key, label, and optional default answer.");
+        const { key, label, defaultValue } = input;
+        if (typeof key !== "string" || !/^[a-z][a-z0-9_]{0,31}$/.test(key) || ["constructor", "prototype"].includes(key) || seen.has(key))
+            throw new RecipeError("Give each question a unique key: lowercase letters, numbers, or underscores, starting with a letter (up to 32 characters).");
+        if (typeof label !== "string" || !label.trim() || label.length > 80 || !honest(label))
+            throw new RecipeError("Give each question a readable label of up to 80 characters.");
+        if (defaultValue !== null && (typeof defaultValue !== "string" || defaultValue.length > 500 || !honest(defaultValue) || /\{\{|\}\}/.test(defaultValue)))
+            throw new RecipeError("Default answers must be plain text up to 500 characters, without input placeholders.");
+        seen.add(key);
+        return { key, label: label.trim(), defaultValue: typeof defaultValue === "string" ? defaultValue.trim() || null : null };
+    });
+}
+const inputToken = /\{\{\s*([a-z][a-z0-9_]{0,31})\s*\}\}/g;
+function workTexts(document) {
+    return [document.name, document.description, document.goal, document.outOfScope ?? "", ...document.acceptance.map(one => one.statement)];
+}
+function validateInputReferences(document) {
+    const keys = new Set(document.inputs.map(input => input.key)), used = new Set();
+    for (const text of workTexts(document)) {
+        const rest = text.replace(inputToken, (_, key) => {
+            if (!keys.has(key))
+                throw new RecipeError(`Add a question for {{${key}}}, or remove that placeholder.`);
+            used.add(key);
+            return "";
+        });
+        if (/\{\{|\}\}/.test(rest))
+            throw new RecipeError("Use placeholders like {{module}}, matching a question key.");
+    }
+    if ([...document.touches, ...document.acceptance.map(one => one.how ?? "")].some(text => /\{\{|\}\}/.test(text)))
+        throw new RecipeError("Use inputs in instructions and success checks. Allowed paths and check commands must stay fixed.");
+    for (const key of keys)
+        if (!used.has(key))
+            throw new RecipeError(`Use {{${key}}} in your instructions or success checks so its answer affects the work.`);
+}
+export function resolveRecipe(document, answers) {
+    const parsed = parseRecipe(document);
+    const inputs = parsed.version === 2 ? parsed.inputs : [];
+    const known = new Set(inputs.map(input => input.key));
+    for (const key of answers.keys())
+        if (!known.has(key))
+            throw new RecipeError("This recipe does not ask for that input. Reload it before continuing.");
+    const values = new Map();
+    for (const input of inputs) {
+        const value = (answers.has(input.key) ? answers.get(input.key) : input.defaultValue ?? "").trim();
+        if (!value)
+            throw new RecipeError(`Answer “${input.label}” before previewing the work.`);
+        if (value.length > 500 || !honest(value) || /\{\{|\}\}/.test(value))
+            throw new RecipeError(`“${input.label}” must be plain text up to 500 characters, without input placeholders.`);
+        values.set(input.key, value);
+    }
+    if (parsed.version === 1)
+        return parsed;
+    const expand = (text) => text.replace(inputToken, (_, key) => values.get(key));
+    const { inputs: _inputs, ...fields } = parsed;
+    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(() => {
+        access(store, actor, repo, true);
+        const recipe = findRecipe(store, actor, repo, id, revision);
+        if (recipe === null || recipe.repo === null)
+            throw new RecipeError("This recipe is not available in this project.", 404);
+        return createWorkflowPreview(store, actor, repo, resolveRecipe(recipe.document, answers), recipe.id, now);
+    });
+}
+const titles = { "nightly-deps": "Keep dependencies current", "test-coverage": "Test one overlooked module", "docs-drift": "Keep documentation accurate", "lint-sweep": "Clean up lint and types" };
+export function starterRecipes() {
+    const recipes = TEMPLATES.filter(one => one.kind !== "recipe").map(one => {
+        const document = parseRecipe({ format: "standing-orders-recipe", version: 1, name: titles[one.name] ?? one.name, description: one.purpose, goal: one.goal, outOfScope: one.outOfScope, touches: one.touches, acceptance: one.acceptance,
+            planning: "skip", deliverable: "branch", schedule: one.kind === "routine" ? one.schedule : null, costCeilingUsd: null });
+        return { id: one.name, revision: 1, repo: null, document, digest: recipeDigest(document), author: "Toolroll" };
+    });
+    for (const [id, document] of [
+        ["small-feature", { name: "Ship a small feature", description: "Turn one clear outcome into a plan, a reviewed change, and evidence.", goal: "Implement one small feature. Describe the desired behavior here, including who uses it and what success looks like.", outOfScope: "No unrelated refactoring, dependency upgrades, deployment, or changes to existing public behavior.", planning: "required", deliverable: "branch", acceptance: [{ id: "c1", statement: "The requested behavior works and relevant regression tests pass.", how: null, evidence: ["check", "changed-path"] }] }],
+        ["project-tour", { name: "Understand this project", description: "A useful first run: get a source-backed report before changing anything.", goal: "Map the project's entry points, major components, build and test commands, and one bounded improvement worth doing next. Cite the source paths behind each claim and distinguish confirmed facts from unknowns.", outOfScope: "No code or configuration changes, dependency installation, or publication.", planning: "skip", deliverable: "report", acceptance: [{ id: "c1", statement: "The report explains the entry points, components, build/test commands, and next improvement with source references and explicit unknowns.", how: null, evidence: ["manual-review"] }] }],
+    ]) {
+        const parsed = parseRecipe({ format: "standing-orders-recipe", version: 1, ...document, touches: [], schedule: null, costCeilingUsd: null });
+        recipes.unshift({ id, revision: 1, repo: null, document: parsed, digest: recipeDigest(parsed), author: "Toolroll" });
+    }
+    return recipes;
+}
+function access(store, actor, repo, write = false) {
+    if (!store.accountCanAccess(actor, repo) || (write && store.accountOf(actor)?.role !== "approver"))
+        throw new RecipeError("This project is outside your current access.", 403);
+}
+function readRecipe(row) {
+    const document = importRecipe(String(row.document));
+    if (recipeDigest(document) !== row.digest)
+        throw new RecipeError("The saved recipe does not match its recorded version.", 409);
+    return { id: String(row.id), revision: Number(row.revision), repo: String(row.repo), document, digest: String(row.digest), author: String(row.author) };
+}
+export function savedRecipes(store, actor, repo) {
+    repo = recipeProject(repo);
+    access(store, actor, repo);
+    return store.handle.prepare(`SELECT r.* FROM workflow_recipe r WHERE repo=? AND revision=(SELECT MAX(revision) FROM workflow_recipe WHERE id=r.id) ORDER BY (SELECT MAX(p.created_at) FROM workflow_preview p WHERE p.repo=r.repo AND p.source=r.id AND (p.task_id IS NOT NULL OR p.routine_id IS NOT NULL)) DESC, created_at DESC, id LIMIT 100`).all(repo).map(readRecipe);
+}
+export function findRecipe(store, actor, repo, id, revision) {
+    const starter = starterRecipes().find(one => one.id === id);
+    if (starter !== undefined)
+        return revision === undefined || revision === starter.revision ? starter : null;
+    if (repo === null)
+        return null;
+    repo = recipeProject(repo);
+    access(store, actor, repo);
+    const row = revision === undefined ? store.handle.prepare("SELECT * FROM workflow_recipe WHERE repo=? AND id=? ORDER BY revision DESC LIMIT 1").get(repo, id)
+        : store.handle.prepare("SELECT * FROM workflow_recipe WHERE repo=? AND id=? AND revision=?").get(repo, id, revision);
+    return row === undefined ? null : readRecipe(row);
+}
+export function createWorkflowPreview(store, actor, repo, document, source, now) {
+    repo = recipeProject(repo);
+    const parsed = parseRecipe(document);
+    if (!/^[a-z0-9-]{1,48}$/.test(source))
+        throw new RecipeError("Unknown recipe source.");
+    return store.transact(() => {
+        access(store, actor, repo, true);
+        store.handle.prepare("DELETE FROM workflow_preview WHERE actor=? AND expires_at<? AND task_id IS NULL AND routine_id IS NULL AND saved_id IS NULL").run(actor, now.toISOString());
+        const count = store.handle.prepare("SELECT COUNT(*) n FROM workflow_preview WHERE actor=? AND expires_at>? AND task_id IS NULL AND routine_id IS NULL AND saved_id IS NULL").get(actor, now.toISOString());
+        if (Number(count?.n) >= 30)
+            throw new RecipeError("You have 30 open previews. Use one or let it expire before making another.", 429);
+        const token = randomBytes(16).toString("hex");
+        store.handle.prepare("INSERT INTO workflow_preview(token,actor,repo,document,digest,source,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?)")
+            .run(token, actor, repo, JSON.stringify(parsed), recipeDigest(parsed), source, now.toISOString(), new Date(now.getTime() + 30 * 60_000).toISOString());
+        return workflowPreview(store, actor, repo, token);
+    });
+}
+export function workflowPreview(store, actor, repo, token) {
+    repo = recipeProject(repo);
+    access(store, actor, repo);
+    const row = store.handle.prepare("SELECT * FROM workflow_preview WHERE token=? AND actor=? AND repo=?").get(token, actor, repo);
+    if (row === undefined)
+        return null;
+    const document = importRecipe(String(row.document));
+    if (recipeDigest(document) !== row.digest)
+        throw new RecipeError("This preview has changed. Make a fresh preview.", 409);
+    return { token, actor, repo, document, digest: String(row.digest), source: String(row.source), expiresAt: String(row.expires_at), taskId: row.task_id, routineId: row.routine_id, savedId: row.saved_id, savedRevision: row.saved_revision };
+}
+function currentPreview(store, actor, repo, token) {
+    access(store, actor, repo, true);
+    const preview = workflowPreview(store, actor, repo, token);
+    if (preview === null)
+        throw new RecipeError("No preview in this project. Preview the workflow again.", 404);
+    return preview;
+}
+export function launchWorkflow(store, actor, repo, token, now, operatorFiling) {
+    repo = recipeProject(repo);
+    return store.transact(() => {
+        const preview = currentPreview(store, actor, repo, token);
+        if (preview.taskId !== null || preview.routineId !== null)
+            return { taskId: preview.taskId, routineId: preview.routineId };
+        if (preview.expiresAt <= now.toISOString())
+            throw new RecipeError("This preview expired. Preview it again before creating work.", 409);
+        const d = preview.document;
+        if (d.version === 2)
+            throw new RecipeError("Answer the recipe questions and preview the filled-in work before creating it.", 409);
+        const provenance = `recipe:${preview.savedId ?? preview.source}`;
+        let taskId = null, routineId = null;
+        if (d.schedule === null) {
+            const made = fileTaskProposal(store, { id: `workflow-${token}`, title: d.name, repo, goal: d.goal, outOfScope: d.outOfScope, touches: d.touches, acceptance: d.acceptance, planning: d.planning, deliverable: d.deliverable, filedVia: provenance, filedBy: { name: actor, kind: "person" }, admittedRepos: [repo] }, now);
+            if (!made.ok)
+                throw new RecipeError(made.message, made.reason === "backlog-full" ? 429 : 400);
+            taskId = made.id;
+            if (operatorFiling)
+                applyModeToNewFiling(store, taskId, actor, now);
+        }
+        else {
+            const slug = d.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "workflow";
+            const made = fileRoutineProposal(store, { name: `${slug}-${token.slice(0, 8)}`, repo, goal: d.goal, outOfScope: d.outOfScope, touches: d.touches, acceptance: d.acceptance, requirements: [], schedule: d.schedule, costCeilingUsd: d.costCeilingUsd, filedVia: provenance, createdBy: actor, admittedRepos: [repo] }, now);
+            if (!made.ok)
+                throw new RecipeError(made.message);
+            routineId = made.id;
+        }
+        store.handle.prepare("UPDATE workflow_preview SET task_id=?,routine_id=? WHERE token=?").run(taskId, routineId, token);
+        store.recordAction({ at: now.toISOString(), actor, repo, taskId, runId: null, action: "workflow created", outcome: routineId === null ? "task" : "routine", source: "work" });
+        return { taskId, routineId };
+    });
+}
+export function saveWorkflowRecipe(store, actor, repo, token, now) {
+    repo = recipeProject(repo);
+    return store.transact(() => {
+        const preview = currentPreview(store, actor, repo, token);
+        if (preview.savedId !== null)
+            return findRecipe(store, actor, repo, preview.savedId, preview.savedRevision);
+        if (preview.expiresAt <= now.toISOString())
+            throw new RecipeError("This preview expired. Preview it again before saving.", 409);
+        const id = randomBytes(12).toString("hex");
+        store.handle.prepare("INSERT INTO workflow_recipe(id,revision,repo,document,digest,author,created_at) VALUES (?,1,?,?,?,?,?)").run(id, repo, JSON.stringify(preview.document), preview.digest, actor, now.toISOString());
+        store.handle.prepare("UPDATE workflow_preview SET saved_id=?,saved_revision=1 WHERE token=?").run(id, token);
+        store.recordAction({ at: now.toISOString(), actor, repo, taskId: null, runId: null, action: "recipe saved", outcome: "saved", source: "work" });
+        return findRecipe(store, actor, repo, id, 1);
+    });
+}
+export function workflowSteps(document) {
+    return [
+        { title: "Authorize", detail: document.schedule === null ? "Your project policy applies. Without a matching policy, review and approve the scope first." : "Approve the repeating scope and exact agents once. New recipes start inactive." },
+        ...(document.deliverable === "report" ? [{ title: "Investigate", detail: "Inspect the project and return a source-backed report." }] : [
+            ...(document.schedule === null && document.planning !== "skip" ? [{ title: "Plan", detail: document.planning === "required" ? "Inspect the repository and plan before building." : "Plan first when the scope calls for repository discovery." }] : []),
+            { title: "Build", detail: "Work in an isolated branch within the agreed scope." },
+            { title: "Verify", detail: "Check each success criterion and retain its evidence." },
+        ]),
+        { title: "Open result", detail: "See the report or change, its checks, and unresolved questions. Agent review follows your project policy; publishing requires separate authority." },
+    ];
+}
+export function recipeScheduleWords(document, now) {
+    if (document.schedule === null)
+        return "Once, after its approval and readiness gates pass";
+    const schedule = parseSchedule(document.schedule);
+    return `${describeSchedule(schedule)}. If approved now, first due ${firstFireAt(schedule, now)}. Missed slots run once; unfinished work prevents overlap.`;
+}

package/dist/remote.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The half of "in flight" that is not on this machine.
+ *
+ * Branches come off the local filesystem in milliseconds. Pull requests and
+ * issues are a network round trip per repository, and that difference is the
+ * whole reason this is a separate module with a budget attached rather than
+ * three more lines inside discovery.
+ *
+ * An earlier draft kept these behind their own command precisely because of
+ * the cost, and the milestone still asks for one command that shows every
+ * branch, pull request, and issue in flight. Both concerns are real, so this
+ * follows the rule the rest of the tool already uses for expensive reads:
+ * price it, bound it, and **say what you withheld**. Twenty-four repositories
+ * on hotel wifi will not hang; they will come back with what fitted in the
+ * budget and a line naming what did not.
+ *
+ * The budget is for the whole phase, not per repository. A per-call timeout
+ * bounds the worst case at repos × timeout, which for a machine full of work
+ * is not a bound anybody would recognise as one.
+ */
+import { type Pull } from "./pulls.js";
+import { type BackendTask, type Runner } from "./backend.js";
+export type RemoteState = {
+    pulls: Pull[];
+    issues: BackendTask[];
+    /**
+     * Whether each read actually succeeded.
+     *
+     * An empty list means nothing without these. A repository with issues
+     * switched off, one whose token expired, and one that genuinely has no open
+     * issues all produce `issues: []`, and only the first two are a reason to
+     * stop trusting the number above it.
+     */
+    pullsRead: boolean;
+    issuesRead: boolean;
+    /** What could not be read, in words. */
+    problems: string[];
+    /** True when the budget ran out before this repository was asked. */
+    skipped: boolean;
+};
+export type RemoteOptions = {
+    runner?: Runner;
+    /** Total wall clock for the whole phase, not per repository. */
+    budgetMs?: number;
+    concurrency?: number;
+    now?: () => number;
+    issueLimit?: number;
+};
+/**
+ * Long enough for a dozen repositories on an ordinary connection, short enough
+ * that somebody who typed a command still feels like it answered.
+ */
+export declare const DEFAULT_BUDGET_MS = 15000;
+/** GitHub is the bottleneck here, not the local machine. */
+export declare const DEFAULT_REMOTE_CONCURRENCY = 6;
+export declare const EMPTY: RemoteState;
+/**
+ * Read pull requests and issues for each repository, within one budget.
+ *
+ * Only repositories that look like they are on a remote are asked; a local-only
+ * repo has no pull requests by definition, and spending part of a shared budget
+ * to be told so would come out of the repositories that do.
+ */
+export declare function readRemote(repos: readonly {
+    path: string;
+    remoteUrl: string | null;
+}[], options?: RemoteOptions): Promise<Map<string, RemoteState>>;

package/dist/remote.js

@@ -0,0 +1,122 @@
+/**
+ * The half of "in flight" that is not on this machine.
+ *
+ * Branches come off the local filesystem in milliseconds. Pull requests and
+ * issues are a network round trip per repository, and that difference is the
+ * whole reason this is a separate module with a budget attached rather than
+ * three more lines inside discovery.
+ *
+ * An earlier draft kept these behind their own command precisely because of
+ * the cost, and the milestone still asks for one command that shows every
+ * branch, pull request, and issue in flight. Both concerns are real, so this
+ * follows the rule the rest of the tool already uses for expensive reads:
+ * price it, bound it, and **say what you withheld**. Twenty-four repositories
+ * on hotel wifi will not hang; they will come back with what fitted in the
+ * budget and a line naming what did not.
+ *
+ * The budget is for the whole phase, not per repository. A per-call timeout
+ * bounds the worst case at repos × timeout, which for a machine full of work
+ * is not a bound anybody would recognise as one.
+ */
+import { readPulls } from "./pulls.js";
+import { githubIssues } from "./issues.js";
+import {} from "./backend.js";
+/**
+ * Long enough for a dozen repositories on an ordinary connection, short enough
+ * that somebody who typed a command still feels like it answered.
+ */
+export const DEFAULT_BUDGET_MS = 15_000;
+/** GitHub is the bottleneck here, not the local machine. */
+export const DEFAULT_REMOTE_CONCURRENCY = 6;
+export const EMPTY = {
+    pulls: [],
+    issues: [],
+    pullsRead: false,
+    issuesRead: false,
+    problems: [],
+    skipped: false,
+};
+/**
+ * Read pull requests and issues for each repository, within one budget.
+ *
+ * Only repositories that look like they are on a remote are asked; a local-only
+ * repo has no pull requests by definition, and spending part of a shared budget
+ * to be told so would come out of the repositories that do.
+ */
+export async function readRemote(repos, options = {}) {
+    const { runner, budgetMs = DEFAULT_BUDGET_MS, concurrency = DEFAULT_REMOTE_CONCURRENCY, now = () => Date.now(), issueLimit, } = options;
+    const state = new Map();
+    const wanted = repos.filter(repo => repo.remoteUrl !== null);
+    for (const repo of repos)
+        state.set(repo.path, { ...EMPTY });
+    if (wanted.length === 0)
+        return state;
+    const deadline = now() + budgetMs;
+    let next = 0;
+    const consume = async () => {
+        while (next < wanted.length) {
+            const repo = wanted[next++];
+            if (repo === undefined)
+                return;
+            // Checked before each repository rather than after: once the budget is
+            // spent, every remaining repository is marked and none of them waits.
+            const remaining = deadline - now();
+            if (remaining <= 0) {
+                state.set(repo.path, { ...EMPTY, skipped: true });
+                continue;
+            }
+            try {
+                // The per-call timeout is clamped to what is left of the budget. A
+                // deadline checked only before starting is not a bound: with six lanes
+                // and a twenty-second call timeout, six repositories begun a moment
+                // before the budget expires run twenty seconds past it. Handing each
+                // call the remaining time makes the budget mean what it says.
+                state.set(repo.path, await readOne(repo.path, runner, issueLimit, remaining));
+            }
+            catch (error) {
+                // A runner that throws rather than returning a failure must not end a
+                // report covering everything else — the same rule discovery follows.
+                state.set(repo.path, {
+                    ...EMPTY,
+                    problems: [`could not read ${repo.path}: ${describe(error)}`],
+                });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, wanted.length)) }, consume));
+    return state;
+}
+async function readOne(path, runner, issueLimit, timeoutMs) {
+    const issues = githubIssues({
+        repo: path,
+        timeoutMs,
+        ...(runner === undefined ? {} : { runner }),
+        ...(issueLimit === undefined ? {} : { limit: issueLimit }),
+    });
+    // Both round trips at once: they are independent, and doing them in sequence
+    // would double the time this repository costs the shared budget.
+    const [pulls, listed] = await Promise.all([
+        readPulls(path, { timeoutMs, ...(runner === undefined ? {} : { runner }) }),
+        issues.listReady(),
+    ]);
+    const problems = [...pulls.problems];
+    // Every failed read is said out loud. An earlier version swallowed the
+    // `unreachable` ones as though they meant "issues are switched off here",
+    // but that bucket also holds an expired token, a rate limit, and a dropped
+    // connection — and reporting any of those as `issues: []` turns "we could
+    // not look" into "there is nothing there", which is the one thing this
+    // report must never do.
+    if (!listed.ok)
+        problems.push(`could not read issues: ${listed.message}`);
+    return {
+        pulls: pulls.pulls,
+        issues: listed.ok ? listed.value : [],
+        pullsRead: pulls.problems.length === 0,
+        issuesRead: listed.ok,
+        problems,
+        skipped: false,
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}