toolroll 0.9.84 → 0.9.86

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-cadence.d.ts

@@ -13,26 +13,32 @@ import { type TriggerIo, type TriggerPass } from "./flow-triggers.js";
 import { type ReplyWatch, type ReplyWatchIo } from "./flow-replies.js";
 import { type StepIo, type StepPass } from "./flow-steps.js";
 import type { Store } from "./store.js";
+import { type Git } from "./landed-cleanup.js";
+import { type YouiyouxPass } from "./youiyoux-intake.js";
 /** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
 export declare const FLOW_EVERY_MS = 15000;
 /** One pass of a kind for a project at a time in this process: a second one asked for while it runs is skipped
  * (`idle`), and the next cadence takes up whatever it would have done. Cards are also claimed in the database,
  * so passes in other processes can't act twice either. */
 export declare function alone<T>(kind: string, project: string, idle: T, run: () => Promise<T>): Promise<T>;
+/** `youiyouxGit`: the hardened git an options request's result is read with (the plane's own runner; gitOf by default). */
 export type FlowIo = {
     triggers: TriggerIo;
     replies: ReplyWatchIo;
     steps: StepIo;
     evidenceRoot?: string;
+    youiyouxGit?: Git;
 };
 export type FlowHousekeeping = {
     triggers: TriggerPass;
+    youiyoux: YouiyouxPass;
     replies: ReplyWatch;
     steps: StepPass;
     flows: FlowAdvance;
 };
-/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
- * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+/** One project's flow pass: triggers (which may start cards), youiyoux requests (which file tasks that wait for a
+ * person, and move an options request's options to youiyoux's hub and a decision there back), replies (which move waiting cards), steps, then moves. `halted` (a stop or paused admission) skips
+ * everything that reaches outside; moves still run. */
 export declare function flowHousekeeping(store: Store, repo: string, clock: () => Date, io: FlowIo, halted: () => boolean): Promise<FlowHousekeeping>;
 /** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
  * card's visit in its own transaction, so a pass in another process can't move a card twice. */

package/dist/flow-cadence.js

@@ -12,6 +12,8 @@ import { advanceFlows } from "./flow-engine.js";
 import { runFlowTriggers } from "./flow-triggers.js";
 import { watchFlowReplies } from "./flow-replies.js";
 import { runFlowSteps } from "./flow-steps.js";
+import { gitOf } from "./landed-cleanup.js";
+import { NO_YOUIYOUX_PASS, runYouiyoux } from "./youiyoux-intake.js";
 /** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
 export const FLOW_EVERY_MS = 15_000;
 const running = new Set();
@@ -30,11 +32,22 @@ export async function alone(kind, project, idle, run) {
         running.delete(key);
     }
 }
-/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
- * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+const NO_REQUESTS = NO_YOUIYOUX_PASS;
+/** One project's flow pass: triggers (which may start cards), youiyoux requests (which file tasks that wait for a
+ * person, and move an options request's options to youiyoux's hub and a decision there back), replies (which move waiting cards), steps, then moves. `halted` (a stop or paused admission) skips
+ * everything that reaches outside; moves still run. */
 export async function flowHousekeeping(store, repo, clock, io, halted) {
     const triggers = halted() ? { added: 0, checked: 0, problems: [] }
         : await alone("triggers", repo, { added: 0, checked: 0, problems: [] }, () => runFlowTriggers(store, repo, clock(), io.triggers));
+    const youiyoux = halted() ? NO_REQUESTS
+        : await alone("youiyoux", repo, NO_REQUESTS, async () => {
+            try {
+                return await runYouiyoux(store, repo, clock(), { dir: io.triggers.dir, env: process.env, git: io.youiyouxGit ?? gitOf(), evidenceRoot: io.evidenceRoot ?? null });
+            }
+            catch (error) {
+                return { ...NO_REQUESTS, problems: [`youiyoux: ${error instanceof Error ? error.message : "could not read requests"}`] };
+            }
+        });
     // One mailbox serves every project, so its reads are one at a time across them all.
     const replies = halted() ? { read: 0, taken: 0, problem: null }
         : await alone("replies", "*", { read: 0, taken: 0, problem: null }, () => watchFlowReplies(store, clock(), io.replies));
@@ -42,7 +55,7 @@ export async function flowHousekeeping(store, repo, clock, io, halted) {
         : await alone("steps", repo, { ran: 0, problems: [] }, () => runFlowSteps(store, repo, clock(), io.steps));
     // Last, so a step that just finished, or a card a trigger just added, moves now.
     const flows = moveCards(store, repo, clock(), io.evidenceRoot);
-    return { triggers, replies, steps, flows };
+    return { triggers, youiyoux, replies, steps, flows };
 }
 /** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
  * card's visit in its own transaction, so a pass in another process can't move a card twice. */

package/dist/flow-card-task.d.ts

@@ -1,2 +1,11 @@
 import type { Store } from "./store.js";
+import { type TaskStatus } from "./task-status.js";
+/** A task's status as its page reads it, from the store alone (no evidence files); null when it can't be read. */
+/** `root`: where results' saved evidence is. Without it the receipt is read without its saved checks, so a completion
+ * (bound to the receipt read with them) doesn't read as one: a status that must say Complete passes it. */
+export declare function storedTaskStatus(store: Store, taskId: string, repo: string, now: Date, root?: string): {
+    status: TaskStatus;
+    activeTaskId: string;
+    live: ReturnType<Store["getRun"]>;
+} | null;
 export declare function flowCardTaskLine(store: Store, taskId: string, repo: string, now: Date, secrets?: readonly string[]): string;

package/dist/flow-card-task.js

@@ -19,14 +19,17 @@ function cardReason(text, fallback, secrets) {
         return fallback;
     return clean.length > 100 ? `${clean.slice(0, 99).trimEnd()}…` : clean;
 }
-export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
+/** A task's status as its page reads it, from the store alone (no evidence files); null when it can't be read. */
+/** `root`: where results' saved evidence is. Without it the receipt is read without its saved checks, so a completion
+ * (bound to the receipt read with them) doesn't read as one: a status that must say Complete passes it. */
+export function storedTaskStatus(store, taskId, repo, now, root) {
     const access = { principal: "operator", repos: [repo], dependencyRepos: [repo] };
-    const assignment = assignmentOf(store, taskId, now, access);
+    const assignment = assignmentOf(store, taskId, now, access, root);
     if (assignment === null)
-        return "Task unavailable";
+        return null;
     const work = taskWorkSummaryOf(store, assignment.activeTaskId, now, access);
     if (work === null)
-        return "Task unavailable";
+        return null;
     const live = work.liveRunId === null ? null : store.getRun(work.liveRunId);
     const facts = assignmentStatusFacts(assignment, { work: work.status, planning: live?.role === "planner" });
     // The canvas reads no evidence files. Keep the machine's recorded check visible
@@ -35,7 +38,13 @@ export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
     // With neither, nothing about the check was read here: the line says nothing about it, never a pass and never an ask.
     if (facts.checks?.status === "unavailable")
         facts.checks = check === null ? null : { ...facts.checks, status: check.status, exitCode: check.exitCode };
-    const status = taskStatusOf(facts);
+    return { status: taskStatusOf(facts), activeTaskId: assignment.activeTaskId, live };
+}
+export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
+    const read = storedTaskStatus(store, taskId, repo, now);
+    if (read === null)
+        return "Task unavailable";
+    const { status, live } = read;
     if (status.headline === "Needs you") {
         const fallback = status.need?.action.label ?? "Open the task";
         // The question itself is useful; routine approvals are clearer as the short action.
@@ -44,7 +53,7 @@ export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
         return `Waiting on you: ${what}`;
     }
     if (status.headline === "Building" && live !== null) {
-        const ref = store.lookupRef(assignment.activeTaskId);
+        const ref = store.lookupRef(read.activeTaskId);
         const checkpoint = store.latestCheckpointForRun(live.id);
         const progress = buildProgressOf(checkpoint?.taskRef !== ref?.id ? null : checkpoint?.snapshot.milestones.map(one => ({ description: null, state: one.state, note: one.note })));
         if (progress?.stuck != null)

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-live.js

@@ -16,6 +16,7 @@
  * can't keep one open falls back to reading every few seconds. With nothing
  * written, an open flow costs no reads; a 30-second check heals a miss.
  */
+import { browserViewOf } from "./flow-browser.js";
 import { createHash } from "node:crypto";
 import { createLiveRooms } from "./live-bus.js";
 // Statements belong to their database, without keeping closed Stores alive.
@@ -90,7 +91,14 @@ export function flowFingerprint(store, flow, now = new Date()) {
     // including a build in another project. The page read admits the viewer;
     // this stream only carries a hash. No evidence files or logs are read.
     const row = fingerprintStatement(store).get({ $flow: flow, $now: now.toISOString() });
-    return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
+    if (row === undefined)
+        return null;
+    // Browser use (flow-browser.ts): an approval, a revocation, a changed covered script or a signer who lost standing
+    // changes what the page says, so it is part of what open pages are nudged on.
+    const saved = store.getFlow(flow);
+    const browser = saved === null ? null : browserViewOf(store, saved);
+    const browserKey = browser === null ? "" : `${browser.status}:${browser.digest ?? ""}:${browser.signedAt ?? ""}:${browser.problem === null ? "" : "x"}`;
+    return createHash("sha256").update([...Object.values(row).map(String), browserKey].join("|")).digest("hex").slice(0, 16);
 }
 /** Rooms keyed by flow. With a bus, a write reaches every open page at once; without one, only the safety net. */
 export function createFlowRooms(fingerprint, options = {}) {

package/dist/flow-pull-request.js

@@ -19,6 +19,7 @@ import { adoptPublishedPullRequest } from "./publish.js";
 import { failingCheckOf, mergePullRequest, owePullRequest, pullRequestBlocker, pullRequestFollowOf } from "./pull-request-flow.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
+import { cardTaskArchived } from "./task-archive.js";
 /** Whether a person approved this card at a "Person decides" zone since it was last built; their name when so.
  * The MOST RECENT decision governs (approval policy §1.7): it must be a person's recorded decision, after the card's
  * last build by the current definition AND after the exact build being merged finished (`builtAt`), so editing the
@@ -41,19 +42,23 @@ export function approvedSinceBuild(store, definition, card, builtAt = null) {
 /** One pass of a Pull request zone for one card. Returns whether it changed anything. */
 export async function pullRequestStep(store, flow, definition, stage, card, now, io) {
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
-    const waiting = (said) => {
+    // Every write after GitHub answers re-proves, in its own transaction, that the card's work wasn't put away meanwhile
+    // (v145): a put away that committed first leaves the card where it is, saying nothing to anyone.
+    const unlessHeld = (write) => store.transact(() => cardTaskArchived(store, card.id) ? false : write());
+    const waiting = (said) => unlessHeld(() => {
         if (card.waiting === said)
             return false;
         store.updateFlowCard(card.id, { waiting: said }, now);
         return true;
-    };
-    const passed = (said, output) => {
+    });
+    const passed = (said, output) => unlessHeld(() => {
         store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: output }, waiting: null }, now);
         if (stage.next === null)
             return waiting(`${said} Move the card on when you're ready.`);
         return store.moveFlowCard(card.id, { to: stage.next, outcome: "ok", actor: "flow", historyNote: said, expectEntry: card.entry }, now);
-    };
-    const failed = (said, revision = null) => {
+    });
+    const failed = (said, revision = null) => unlessHeld(() => failedNow(said, revision));
+    const failedNow = (said, revision = null) => {
         store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: said } }, now);
         if (stage.onFail === null) {
             if (!waiting(`${said} Fix it, then move the card to try again.`))
@@ -68,13 +73,13 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
     };
     // Publishing that can't proceed is not the build's fault: rebuilding wouldn't change it, so the card waits here,
     // saying what to do, and the people on it hear once. It carries on by itself once the cause is fixed.
-    const stuck = (said) => {
+    const stuck = (said) => unlessHeld(() => {
         if (!waiting(said))
             return false;
         const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
         notifyPeople(store, card, people, null, { key: `pr-stuck:${card.entry}`, subject: `${stage.title} is waiting on you for “${card.title}”`, attention: true, body: said }, now);
         return true;
-    };
+    });
     // With no failure path, a card that didn't pass waits for a person to move it (a move is a fresh visit).
     if (stage.onFail === null && card.waiting !== null && card.waiting.endsWith(" Fix it, then move the card to try again."))
         return false;
@@ -128,6 +133,9 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
         // Back to a Build zone: a revision of the same work, carrying the failure (fenced as untrusted CI output).
         let revision = null;
         const target = definition.stages.find(one => one.id === stage.onFail);
+        // No revision of work put away while GitHub answered (v145).
+        if (cardTaskArchived(store, card.id))
+            return false;
         if (target?.kind === "task" && io.evidenceRoot !== undefined) {
             const runTask = store.externalIdFor(store.getRun(runId)?.taskRef ?? -1);
             const revised = runTask === null ? null : requestResultChanges(store, io.evidenceRoot, {

package/dist/flow-share.js

@@ -54,6 +54,8 @@ function stepOf(stage, ask) {
             step["runIn"] = stage.runIn;
         if (stage.secrets !== undefined)
             step["secrets"] = stage.secrets;
+        if (stage.browser === true)
+            step["browser"] = true;
     }
     if (stage.routes !== undefined)
         step["routes"] = stage.routes.map(one => ({ answer: one.answer, goesTo: one.to }));
@@ -299,7 +301,7 @@ function stageInputOf(step, index, find) {
         ...(toOwner ? { toOwner: true } : { approver: anyone ? null : decider }),
         message: step["message"], close: step["close"], script: step["script"], runIn: step["runIn"],
         routes: list("routes")?.map((one, n) => ({ answer: one["answer"], to: find(one["goesTo"], `${at}.routes[${n}].goesTo`) })),
-        secrets: step["secrets"],
+        secrets: step["secrets"], browser: step["browser"],
         ...(kind === "sort" ? { sort: { question: step["question"], answers: (list("answers") ?? []).map((one, n) => ({ answer: one["answer"], means: one["means"], to: find(one["goesTo"], `${at}.answers[${n}].goesTo`) })),
                 sureAt: typeof sureAt === "number" && sureAt > 1 ? sureAt / 100 : sureAt, notes: list("alsoNote") ?? [] } } : {}),
         ...(kind === "request" ? { request: { method: step["method"], url: step["url"], headers: object("headers") ?? {}, body: step["body"] } } : {}),

package/dist/flow-steps.d.ts

@@ -1,7 +1,7 @@
 import type { Runner } from "./backend.js";
 import { type DraftRunner } from "./flow-draft.js";
 import { type MailSender, type ToolCaller } from "./flow-actions.js";
-import type { Store } from "./store.js";
+import type { FlowCardRow, FlowStepKind, Store } from "./store.js";
 import type { TurnRunner } from "./subagents.js";
 import type { ToolLister } from "./subagent-tools.js";
 export type StepIo = {
@@ -42,3 +42,11 @@ export type StepPass = {
 };
 /** Run every due check and update in one project, then move each card on. */
 export declare function runFlowSteps(store: Store, repo: string, now: Date, io: StepIo): Promise<StepPass>;
+/** Claim this card's visit to its step zone, only while the card is still there on that visit: a pass that read the card
+ * before another pass (or a person) moved it never runs the step for a visit that's over. */
+export declare function claimStep(store: Store, card: FlowCardRow, step: {
+    stage: string;
+    kind: FlowStepKind;
+    script: string | null;
+    scriptVersion: number | null;
+}, now: Date): boolean;