toolroll 0.9.85 → 0.9.87

package/dist/flow-browser.d.ts

@@ -0,0 +1,103 @@
+import { type FlowDefinition } from "./flows.js";
+import type { FlowRow, FlowScriptRow, Store } from "./store.js";
+/** v144: each approval of browser use, live or ended. `digest` is browserApprovalDigest of what was approved. Additive only. */
+export declare const FLOW_BROWSER_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_browser_grant (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  flow          INTEGER NOT NULL,\n  repo          TEXT NOT NULL,\n  flow_revision INTEGER NOT NULL,\n  flow_digest   TEXT NOT NULL,\n  digest        TEXT NOT NULL,\n  zones_json    TEXT NOT NULL,\n  signed_by     TEXT NOT NULL,\n  signed_at     TEXT NOT NULL,\n  proof         TEXT NOT NULL,\n  revoked_at    TEXT,\n  revoked_by    TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS flow_browser_live ON flow_browser_grant (flow) WHERE revoked_at IS NULL;\n";
+/** One zone an approval covers: the zone, and the script it runs (name, version and content digest). */
+export type BrowserZone = {
+    zone: string;
+    script: string;
+    version: number;
+    digest: string;
+};
+/** Everything an approval is about: the flow, its project, the drawing (revision and digest) and every browser zone. */
+export type BrowserTerms = {
+    flow: number;
+    repo: string;
+    revision: number;
+    flowDigest: string;
+    zones: BrowserZone[];
+};
+export type FlowBrowserGrant = BrowserTerms & {
+    id: number;
+    digest: string;
+    signedBy: string;
+    signedAt: string;
+    proof: string;
+};
+/** The approval's digest: domain-separated over the whole of its terms, so a changed flow, drawing, revision or any
+ * covered script (a restored one is a new version) is a different approval. */
+export declare function browserApprovalDigest(terms: BrowserTerms): string;
+/** The flow's script zones that say they start a browser, each with the script it runs now; null when one's script is
+ * missing, waiting for approval, or runs a project file (an approval seals the script's own text, never a file the
+ * project can change). */
+export declare function browserZonesOf(store: Store, flow: FlowRow, definition: FlowDefinition): BrowserZone[] | null;
+/** What an approval of this flow would be about now, read from the store; null when it can't be approved. */
+export declare function browserTermsOf(store: Store, flow: FlowRow): BrowserTerms | null;
+/** The flow's live approval, as recorded (whether it still stands is browserStanding's question). */
+export declare function liveBrowserGrant(store: Store, flowId: number): FlowBrowserGrant | null;
+/**
+ * Whether `zone` of this flow may start a browser now. `run`, when given, is what the caller is about to run — the
+ * drawing it read and the very script object it hands the launch — and the answer is about exactly that. The live
+ * approval stands only when its digest is the approval this flow would be now (same flow, project, drawing revision and
+ * digest, and every browser zone's script name, version and digest), it was a person's, and its signer is still an
+ * approver who reaches the project; `run`'s drawing must be that drawing and its script that zone's script. Anything
+ * unreadable, changed or mismatched is a no, with the plain words a card waits with.
+ */
+export declare function browserStanding(store: Store, flowId: number, zone: string, run?: {
+    definition: FlowDefinition;
+    script: FlowScriptRow;
+}): {
+    allowed: true;
+} | {
+    allowed: false;
+    said: string;
+};
+/** What approving means, in words the person reads before they give their password. */
+export declare function browserTerms(zones: readonly BrowserZone[]): string[];
+/**
+ * Approve browser use for the flow as it stands. `proof` is the signer's credential method, proved by the caller just
+ * now; only a person's counts (a lead's or remote run's token is refused), from an approver who reaches the project.
+ * Re-reads the flow, its zones and scripts in the one transaction that writes; `sawDigest` (required) is the approval
+ * (browserApprovalDigest: drawing and scripts) the person read, and anything else is refused. Replaces any live one.
+ */
+export declare function signFlowBrowser(store: Store, input: {
+    flow: number;
+    signer: string;
+    proof: string | null;
+    sawDigest: string;
+    /** The console and chat: the signer's account must still be this generation (the session that proved it) and reach every project. */
+    console?: {
+        generation: number;
+    };
+}, now: Date): {
+    ok: true;
+    grant: FlowBrowserGrant;
+} | {
+    ok: false;
+    message: string;
+};
+/** Any approver on the project ends it, with no password: lowering authority. False when there was none. */
+export declare function revokeFlowBrowser(store: Store, flowId: number, by: string, now: Date): boolean;
+/** What the flow page, `flows show` and chat say about browser use: null when no zone says it starts a browser. */
+export type BrowserView = {
+    /** allowed: the approval stands now; ended: there is one, but it no longer stands; none: no one has approved. */
+    status: "allowed" | "ended" | "none";
+    /** The one line every surface shows. */
+    words: string;
+    signedBy: string | null;
+    signedAt: string | null;
+    /** The browser zones as they stand now, each with its title. Empty while one can't be approved (see `problem`). */
+    zones: (BrowserZone & {
+        title: string;
+    })[];
+    /** What approving means (browserTerms), and the approval digest the step-up must carry back. */
+    terms: string[];
+    digest: string | null;
+    /** Why it can't be approved as it stands, or null. */
+    problem: string | null;
+};
+/**
+ * Browser use for one flow, read from the store (no writes: page visits call it). Whether it is allowed is exactly
+ * browserStanding's answer for the flow's browser zones; the rest only says why in plain words.
+ */
+export declare function browserViewOf(store: Store, flow: FlowRow): BrowserView | null;

package/dist/flow-browser.js

@@ -0,0 +1,204 @@
+/**
+ * Browser use in a flow's script zone: a per-flow approval a person gives with their own proof, so that zone's launch
+ * gets the one sandbox rule a project check gets for Chromium (sandbox-runtime.ts SEATBELT_CHROMIUM) and nothing more.
+ *
+ * Two halves, both needed. The flow's drawing says which "Run a script" zones start a browser (`browser: true`, part of
+ * the flow's digest and said when the flow is confirmed); anyone who may change the flow can say it. Then a person, with
+ * their password or sign-in (never a lead's or remote run's token: person-proof.ts), approves browser use for the flow
+ * as it stands. The approval seals the flow's digest and, for each browser zone, its script's name and content digest.
+ * At launch (flow-steps.ts) the zone gets the rule only while all of that still holds: the same drawing, the same
+ * scripts, a person's proof, a signer who still reaches the project. Anything else gets nothing, and the card waits with
+ * a plain line naming the missing approval instead of Chromium crashing in the sandbox. Builds, checks, tool servers and
+ * every other flow launch (setup, triggers, zones that don't say browser) are untouched.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonical-json.js";
+import { personProof } from "./person-proof.js";
+import { flowDigest, validateFlowDefinition } from "./flows.js";
+/** v144: each approval of browser use, live or ended. `digest` is browserApprovalDigest of what was approved. Additive only. */
+export const FLOW_BROWSER_SCHEMA = `
+CREATE TABLE IF NOT EXISTS flow_browser_grant (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  flow          INTEGER NOT NULL,
+  repo          TEXT NOT NULL,
+  flow_revision INTEGER NOT NULL,
+  flow_digest   TEXT NOT NULL,
+  digest        TEXT NOT NULL,
+  zones_json    TEXT NOT NULL,
+  signed_by     TEXT NOT NULL,
+  signed_at     TEXT NOT NULL,
+  proof         TEXT NOT NULL,
+  revoked_at    TEXT,
+  revoked_by    TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS flow_browser_live ON flow_browser_grant (flow) WHERE revoked_at IS NULL;
+`;
+function definitionOf(flow) {
+    try {
+        return validateFlowDefinition(JSON.parse(flow.definitionJson), { stored: true });
+    }
+    catch {
+        return null;
+    }
+}
+/** The approval's digest: domain-separated over the whole of its terms, so a changed flow, drawing, revision or any
+ * covered script (a restored one is a new version) is a different approval. */
+export function browserApprovalDigest(terms) {
+    return createHash("sha256").update(`toolroll:flow-browser:${canonicalJson(terms)}`, "utf8").digest("hex").slice(0, 32);
+}
+/** The flow's script zones that say they start a browser, each with the script it runs now; null when one's script is
+ * missing, waiting for approval, or runs a project file (an approval seals the script's own text, never a file the
+ * project can change). */
+export function browserZonesOf(store, flow, definition) {
+    const out = [];
+    for (const stage of definition.stages) {
+        if (stage.kind !== "check" || stage.browser !== true)
+            continue;
+        const script = stage.script === null ? null : store.flowScript(flow.repo, stage.script);
+        if (script === null || script.held !== null || script.file !== null)
+            return null;
+        out.push({ zone: stage.id, script: script.name, version: script.version, digest: script.digest });
+    }
+    return out;
+}
+/** What an approval of this flow would be about now, read from the store; null when it can't be approved. */
+export function browserTermsOf(store, flow) {
+    const definition = definitionOf(flow);
+    const zones = definition === null ? null : browserZonesOf(store, flow, definition);
+    return definition === null || zones === null ? null : { flow: flow.id, repo: flow.repo, revision: flow.revision, flowDigest: flowDigest(definition), zones };
+}
+function readGrant(row) {
+    if (row === undefined)
+        return null;
+    let zones;
+    try {
+        zones = JSON.parse(String(row["zones_json"]));
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(zones) || !zones.every(one => one !== null && typeof one === "object" && typeof one.zone === "string" && typeof one.script === "string" && Number.isInteger(one.version) && typeof one.digest === "string"))
+        return null;
+    return { id: Number(row["id"]), flow: Number(row["flow"]), repo: String(row["repo"]), revision: Number(row["flow_revision"]), flowDigest: String(row["flow_digest"]), digest: String(row["digest"]),
+        zones: zones, signedBy: String(row["signed_by"]), signedAt: String(row["signed_at"]), proof: String(row["proof"]) };
+}
+/** The flow's live approval, as recorded (whether it still stands is browserStanding's question). */
+export function liveBrowserGrant(store, flowId) {
+    return readGrant(store.handle.prepare("SELECT * FROM flow_browser_grant WHERE flow = ? AND revoked_at IS NULL").get(flowId));
+}
+/** Whether `name` may approve on `repo` now: a live approver account that reaches the project. */
+function approverNow(store, name, repo) {
+    const account = store.accountOf(name);
+    return account !== null && account.revokedAt === null && account.role === "approver" && store.accountCanAccess(name, repo);
+}
+/**
+ * Whether `zone` of this flow may start a browser now. `run`, when given, is what the caller is about to run — the
+ * drawing it read and the very script object it hands the launch — and the answer is about exactly that. The live
+ * approval stands only when its digest is the approval this flow would be now (same flow, project, drawing revision and
+ * digest, and every browser zone's script name, version and digest), it was a person's, and its signer is still an
+ * approver who reaches the project; `run`'s drawing must be that drawing and its script that zone's script. Anything
+ * unreadable, changed or mismatched is a no, with the plain words a card waits with.
+ */
+export function browserStanding(store, flowId, zone, run) {
+    const flow = store.getFlow(flowId);
+    const definition = flow === null ? null : definitionOf(flow);
+    const stage = definition?.stages.find(one => one.id === zone);
+    if (flow === null || definition === null || stage === undefined || stage.kind !== "check" || stage.browser !== true)
+        return { allowed: false, said: "This zone doesn't say it starts a browser." };
+    const approve = `Approve it with: toolroll flows browser ${flow.id} on`;
+    const grant = liveBrowserGrant(store, flow.id);
+    if (grant === null)
+        return { allowed: false, said: `${stage.title} starts a browser, and no one has approved browser use for the ${flow.name} flow, so it didn't run. ${approve}` };
+    const terms = browserTermsOf(store, flow);
+    const now = terms?.zones.find(one => one.zone === zone);
+    const runStage = run?.definition.stages.find(one => one.id === zone);
+    const runs = run === undefined || (terms !== null && now !== undefined && flowDigest(run.definition) === terms.flowDigest && runStage?.kind === "check" && runStage.browser === true
+        && runStage.script === run.script.name && run.script.repo === flow.repo && run.script.held === null && run.script.file === null
+        && run.script.name === now.script && run.script.version === now.version && run.script.digest === now.digest);
+    const stands = runs && terms !== null && now !== undefined && flow.state === "active" && grant.digest === browserApprovalDigest(terms)
+        && browserApprovalDigest({ flow: grant.flow, repo: grant.repo, revision: grant.revision, flowDigest: grant.flowDigest, zones: grant.zones }) === grant.digest
+        && personProof(grant.proof) && approverNow(store, grant.signedBy, flow.repo);
+    return stands ? { allowed: true } : { allowed: false, said: `${stage.title} starts a browser, but browser use was approved for an earlier version of the ${flow.name} flow or its scripts, so it didn't run. ${approve}` };
+}
+/** What approving means, in words the person reads before they give their password. */
+export function browserTerms(zones) {
+    return [
+        `Lets ${zones.map(one => `the ${one.script} script (zone ${one.zone})`).join(", ")} start Playwright's Chromium headless shell inside the flow's sandbox: the same one macOS service a project check gets for it, and nothing else.`,
+        "Changing the flow or one of these scripts (even back to how it was) ends it; nothing else gets it.",
+    ];
+}
+/**
+ * Approve browser use for the flow as it stands. `proof` is the signer's credential method, proved by the caller just
+ * now; only a person's counts (a lead's or remote run's token is refused), from an approver who reaches the project.
+ * Re-reads the flow, its zones and scripts in the one transaction that writes; `sawDigest` (required) is the approval
+ * (browserApprovalDigest: drawing and scripts) the person read, and anything else is refused. Replaces any live one.
+ */
+export function signFlowBrowser(store, input, now) {
+    if (!personProof(input.proof))
+        return { ok: false, message: "Browser use needs a person's own approval: sign in with your password (a lead's or remote run's token can't give it)." };
+    return store.transact(() => {
+        const flow = store.getFlow(input.flow);
+        if (flow === null || flow.state !== "active")
+            return { ok: false, message: "No such flow." };
+        if (!approverNow(store, input.signer, flow.repo))
+            return { ok: false, message: "Only an approver on this flow's project can approve browser use." };
+        if (input.console !== undefined) {
+            const account = store.accountOf(input.signer);
+            if (account === null || account.generation !== input.console.generation)
+                return { ok: false, message: "Your access changed. Sign in again." };
+            if (account.projects !== null)
+                return { ok: false, message: "Allowing browser use needs an account with access to every project." };
+        }
+        if (definitionOf(flow) === null)
+            return { ok: false, message: "This flow's drawing can't be read." };
+        const terms = browserTermsOf(store, flow);
+        if (terms === null)
+            return { ok: false, message: "A zone that starts a browser has no script it can approve: missing, waiting for approval, or one that runs a project file (write the script on the zone instead)." };
+        if (terms.zones.length === 0)
+            return { ok: false, message: `No zone in ${flow.name} says it starts a browser. Mark the script zone first (browser: true), then approve.` };
+        const digest = browserApprovalDigest(terms);
+        if (input.sawDigest !== digest)
+            return { ok: false, message: "This flow or its scripts changed while you were reading. Read the terms again." };
+        store.handle.prepare("UPDATE flow_browser_grant SET revoked_at = ?, revoked_by = ? WHERE flow = ? AND revoked_at IS NULL").run(now.toISOString(), input.signer, flow.id);
+        const id = Number(store.handle.prepare("INSERT INTO flow_browser_grant (flow, repo, flow_revision, flow_digest, digest, zones_json, signed_by, signed_at, proof) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(flow.id, flow.repo, terms.revision, terms.flowDigest, digest, JSON.stringify(terms.zones), input.signer, now.toISOString(), input.proof).lastInsertRowid);
+        store.recordAction({ at: now.toISOString(), actor: input.signer, repo: flow.repo, taskId: null, runId: null, source: "policy", action: "flow browser use: approved", outcome: "signed",
+            detail: `${flow.name} (flow #${flow.id}) · ${terms.zones.map(one => `${one.zone}: ${one.script} v${one.version}`).join(", ")}` });
+        return { ok: true, grant: { ...terms, id, digest, signedBy: input.signer, signedAt: now.toISOString(), proof: input.proof } };
+    });
+}
+/** Any approver on the project ends it, with no password: lowering authority. False when there was none. */
+export function revokeFlowBrowser(store, flowId, by, now) {
+    return store.transact(() => {
+        const flow = store.getFlow(flowId);
+        const ended = store.handle.prepare("UPDATE flow_browser_grant SET revoked_at = ?, revoked_by = ? WHERE flow = ? AND revoked_at IS NULL").run(now.toISOString(), by, flowId).changes > 0;
+        if (ended)
+            store.recordAction({ at: now.toISOString(), actor: by, repo: flow?.repo ?? null, taskId: null, runId: null, source: "policy", action: "flow browser use: revoked", outcome: "revoked", detail: `flow #${flowId}` });
+        return ended;
+    });
+}
+const dayWords = (at) => new Date(at).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+/**
+ * Browser use for one flow, read from the store (no writes: page visits call it). Whether it is allowed is exactly
+ * browserStanding's answer for the flow's browser zones; the rest only says why in plain words.
+ */
+export function browserViewOf(store, flow) {
+    const definition = definitionOf(flow);
+    const stages = definition?.stages.filter(stage => stage.kind === "check" && stage.browser === true) ?? [];
+    if (definition === null || stages.length === 0)
+        return null;
+    const terms = browserTermsOf(store, flow);
+    const grant = liveBrowserGrant(store, flow.id);
+    const allowed = grant !== null && stages.every(stage => browserStanding(store, flow.id, stage.id).allowed);
+    const zones = (terms?.zones ?? []).map(zone => ({ ...zone, title: definition.stages.find(one => one.id === zone.zone)?.title ?? zone.zone }));
+    const problem = terms === null ? "A zone that starts a browser has no script that can be approved: it's missing, waiting for approval, or runs a project file (write the script on the zone instead)." : null;
+    const why = grant === null ? "" : terms === null || canonicalJson(grant.zones) !== canonicalJson(terms.zones) ? "the script changed"
+        : grant.flowDigest !== terms.flowDigest || grant.revision !== terms.revision ? "the flow changed"
+            : !approverNow(store, grant.signedBy, flow.repo) ? `${grant.signedBy} can no longer approve on this project` : "it no longer matches this flow";
+    return {
+        status: allowed ? "allowed" : grant === null ? "none" : "ended",
+        words: allowed ? `Browser: allowed by ${grant.signedBy}, ${dayWords(grant.signedAt)}` : grant === null ? "Browser: not allowed — runs will wait" : `Browser approval ended: ${why}`,
+        signedBy: grant?.signedBy ?? null, signedAt: grant?.signedAt ?? null,
+        zones, terms: terms === null ? [] : browserTerms(terms.zones), digest: terms === null ? null : browserApprovalDigest(terms), problem,
+    };
+}

package/dist/flow-changed.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from "./store.js";
+export type FlowChange = {
+    flow: number;
+} | {
+    script: {
+        repo: string;
+        name: string;
+    };
+};
+/**
+ * Run `write` (the change itself) and end what it ends, all in one transaction. `write` answers whether it changed
+ * anything; when it didn't, nothing else happens. Returns what `write` returned.
+ */
+export declare function flowChanged<T>(store: Store, change: FlowChange, by: string, now: Date, write: () => T, changed?: (result: T) => boolean): T;

package/dist/flow-changed.js

@@ -0,0 +1,53 @@
+/**
+ * The one road for a change to what a flow runs: its drawing saved, or a script one of its zones runs saved or removed.
+ * Every approval a person gave for the flow as it was ends here, in the same transaction as the write, with its ledger
+ * line, so the flow page, `flows show` and chat all say it ended and why:
+ *  - "Runs on its own" (flow-unattended.ts): its grants end ("flow changed" / "script changed"), and the work they
+ *    pre-authorized falls back to a person.
+ *  - Browser use (flow-browser.ts): its approval seals the drawing and each browser zone's script, so the change itself
+ *    stops it standing (browserStanding re-proves at every launch). Here it is said once in the ledger, for each
+ *    flow whose approval stood before the write and doesn't after; the page shows it as expired with the reason.
+ * Nothing here widens anything: it only ends approvals.
+ */
+import { browserViewOf } from "./flow-browser.js";
+import { endUnattendedGrants } from "./flow-unattended.js";
+/** The flows a change reaches: the flow itself, or every flow in the script's project with a zone that runs it. */
+function flowsOf(store, change) {
+    if ("flow" in change) {
+        const flow = store.getFlow(change.flow);
+        return flow === null ? [] : [flow];
+    }
+    return store.listFlows([change.script.repo]).filter(flow => {
+        try {
+            const drawn = JSON.parse(flow.definitionJson);
+            return (drawn.stages ?? []).some(stage => stage.kind === "check" && stage.script === change.script.name);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Run `write` (the change itself) and end what it ends, all in one transaction. `write` answers whether it changed
+ * anything; when it didn't, nothing else happens. Returns what `write` returned.
+ */
+export function flowChanged(store, change, by, now, write, changed = result => result === true) {
+    return store.transact(() => {
+        const before = new Map(flowsOf(store, change).map(flow => [flow.id, browserViewOf(store, flow)?.status === "allowed"]));
+        const result = write();
+        if (!changed(result))
+            return result;
+        if ("flow" in change)
+            endUnattendedGrants(store, { flow: change.flow }, by, "flow changed", now);
+        else
+            endUnattendedGrants(store, { script: change.script }, by, "script changed", now);
+        for (const [id, stood] of before) {
+            const flow = store.getFlow(id);
+            if (!stood || flow === null || browserViewOf(store, flow)?.status === "allowed")
+                continue;
+            store.recordAction({ at: now.toISOString(), actor: by, repo: flow.repo, taskId: null, runId: null, source: "policy", action: "flow browser use: ended", outcome: "ended",
+                detail: `${flow.name} (flow #${flow.id}) · ${"flow" in change ? "the flow changed" : `the ${change.script.name} script changed`}` });
+        }
+        return result;
+    });
+}

package/dist/flow-code.d.ts

@@ -9,6 +9,8 @@ export { LANGUAGE_WORDS, SCRIPT_LANGUAGES, type ScriptLanguage } from "./flows.j
 export declare const CODE_OUTPUT_CHARS: 12000;
 export type CodeRun = {
     script: FlowScriptRow;
+    /** Asked right before every spawn attempt (retries too); false refuses it. A browser zone's approval rides here. */
+    beforeSpawn?: () => boolean;
     /** Where it runs, and the project folder a file script is found in. */
     cwd: string;
     root: string;
@@ -58,7 +60,8 @@ export declare function cardsFromOutput(stdout: string): {
  * of its own for its input, an inline script and its temp files; writes as the project's writes setting allows (its
  * folder, the copy's Git data, its project's caches); the scratch pool denied around its own folder; and its network
  * open, as flows' scripts have always had it (they reach the services their secrets are for; no approval seals a
- * network for them). The fence is required: where this machine can't confine it, it runs only when an instance operator
+ * network for them). `browser` (flow-browser.ts browserStanding, proved by the caller at launch) adds Chromium's one
+ * service, as a project check has it; nothing else asks for it. The fence is required: where this machine can't confine it, it runs only when an instance operator
  * allowed unconfined agents, and otherwise nothing runs and the card says why.
  */
 export type FlowLaunch = {
@@ -75,6 +78,7 @@ export declare function flowLaunch(store: Store, options: {
     available?: () => boolean;
     policy?: FencePolicy;
     home?: string;
+    browser?: true;
 }): FlowLaunch | null | {
     problem: string;
 };

package/dist/flow-code.js

@@ -79,6 +79,7 @@ export async function runCode(run) {
         const ran = await run.shell("/bin/sh", ["-c", 'exec "$@" < "$FLOW_INPUT"', "flow-script", runtime.file, ...runtime.args], {
             cwd: run.cwd, timeoutMs: script.timeoutMinutes * 60_000, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
             env: { ...run.env, ...run.secrets, ...(run.launch?.env ?? {}), FLOW_INPUT: inputFile }, ...(run.launch?.fence ?? {}),
+            ...(run.beforeSpawn === undefined ? {} : { beforeSpawn: run.beforeSpawn }),
         });
         const printed = codeOutput(ran.stdout, run.secrets);
         const all = scrubSecrets(ran.stdout.slice(0, 1_000_000), run.secrets);
@@ -192,7 +193,9 @@ export function flowLaunch(store, options) {
         // The project's read denies apply to flows as to builds (read live: a flow seals no list, and these only narrow).
         const readDeny = store.projectSandbox(options.repo).readDeny.map(one => readDenyPath(one, home));
         const fence = fenceFor("flow", { databaseFile, worktree: options.folder, home, boundary, readDeny, policy: options.policy ?? 1, scratchRoots: [options.scratch], binding, runFolders: runFolders(own), poolRoots, extra: allowed?.deny ?? [],
-            writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, network: { mode: "open" } });
+            writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, network: { mode: "open" },
+            // Chromium's one service, only for a script zone whose browser use a person approved, proved by the caller now.
+            ...(options.browser === true ? { browser: true } : {}) });
         return { folder: own, env: { ...env, ...(allowed === null ? {} : buildCacheEnv(cache)) }, fence, dispose };
     }
     catch {

package/dist/flow-engine.js

@@ -23,6 +23,7 @@ import { cardFollowers, notifyPeople } from "./flow-people.js";
 import { DRAFT_CHARS, keptDraft } from "./flow-draft.js";
 import { chooseStep, flowPersonOf, sendStep } from "./flow-send.js";
 import { parseSoul, subagentLabel } from "./subagents.js";
+import { cardTaskArchived, taskArchived } from "./task-archive.js";
 import { withStageHandoff } from "./contracts/stage-output.js";
 /** The flow's drawing, or null when it can't be read (the card then says so and waits). */
 export function flowDefinitionOf(flow) {
@@ -90,6 +91,14 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
         return;
     }
     const stage = definition.stages.find(one => one.id === card.stage);
+    // A put-away task (v145, task-tidy.md) holds its card where it is, whatever the zone: nothing moves on, files, sends
+    // or notifies until the task is restored.
+    if (cardTaskArchived(store, card.id)) {
+        const waiting = "Its task is put away. Restore the task to continue.";
+        if (card.waiting !== waiting)
+            store.updateFlowCard(card.id, { waiting }, now);
+        return;
+    }
     if (stage === undefined) {
         // The zone was removed while the card sat in it: back to the start.
         if (store.moveFlowCard(card.id, { to: definition.start, outcome: "moved", actor: "flow", note: null, expectEntry: card.entry }, now))
@@ -311,6 +320,13 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         store.updateFlowCard(card.id, { waiting: "Its task is gone. Move the card to try again." }, now);
         return;
     }
+    // A put-away task (v145, task-tidy.md) holds its card where it is: nothing moves on, files or sends until it's restored.
+    if (taskArchived(store, current) || taskArchived(store, card.task)) {
+        const waiting = "Its task is put away. Restore the task to continue.";
+        if (card.waiting !== waiting)
+            store.updateFlowCard(card.id, { waiting }, now);
+        return;
+    }
     if (task.state === "done") {
         // A build whose project checks failed is done but not good: it takes the failure path, like a failed build.
         if (stage.kind === "task") {

package/dist/flow-gallery-ui.d.ts

@@ -1,13 +1,23 @@
 import { type GalleryAnswers, type GalleryPreview, type GalleryTemplate, type GalleryTool } from "./flow-gallery.js";
 import { type FlowDefinition, type FlowStage } from "./flows.js";
-import { type Html } from "./html.js";
+import { type Html, type HtmlValue } from "./html.js";
 export declare const GALLERY_CSS: string;
 /** A flow's main path, as a person reads it: from the start, each step's first way on (a sort's first answer, a choose's
  * first option that goes somewhere, else next; a check's failure when passing just ends), never back to a step shown. */
 export declare function mainPath(definition: FlowDefinition): FlowStage[];
-/** A flow's steps in order, joined by arrows; a person's decisions carry the accent. */
+/** A flow's steps in order, joined by arrows. */
 export declare function stepStrip(definition: FlowDefinition): Html;
-/** The gallery: every template, grouped, each with one "Use this". `repo` carries a chosen project to the template's page. */
+/** One row of New flow: name · promise · one line · one outline action (the same shape for templates, kits, recipes and starters). */
+export declare function templateRow(options: {
+    name: string;
+    promise: string;
+    line?: HtmlValue;
+    action?: HtmlValue;
+    attrs?: Html;
+}): Html;
+/** The groups New flow filters by: the template groups, then kits, recipes and starter flows. */
+export declare const NEW_FLOW_GROUPS: ReadonlyArray<readonly [key: string, label: string]>;
+/** The templates as rows, grouped (or one group): each with one "Use this". `repo` carries a chosen project to the template's page. */
 export declare function galleryHtml(input: {
     repo: string | null;
     canUse: boolean;
@@ -15,8 +25,35 @@ export declare function galleryHtml(input: {
         id: string;
         state: "connected" | "open" | "taken";
     }[] | null;
+    group?: string;
+}): Html;
+/**
+ * New flow: describe it (the shared composer; the words go to the lead as a chat draft, the project on its bar), then
+ * start from a template, filtered by group. Kits, recipes and starter flows arrive as their own rows.
+ */
+export declare function newFlowHtml(input: {
+    repo: string | null;
+    projects: readonly {
+        path: string;
+        name: string;
+    }[];
+    canUse: boolean;
+    group: string;
+    connections: readonly {
+        id: string;
+        state: "connected" | "open" | "taken";
+    }[] | null;
+    ask: {
+        value: string;
+        error: string | null;
+    };
+    kits: Html;
+    recipes: Html;
+    starters: Html;
+    said: string | null;
+    problem: string | null;
 }): Html;
-/** A template's page: its questions, then what it will do and never do, then Create. */
+/** A template's page, a reading page: its steps and tools, its questions, what it will do and never do, then Create. */
 export declare function galleryUseHtml(input: {
     template: GalleryTemplate;
     projects: readonly {