toolroll 0.9.85 → 0.9.87

package/dist/flow-triggers.js

@@ -49,6 +49,7 @@ import { readFlowSecrets } from "./flow-secrets.js";
 import { prepareUnattendedCandidates, grantSignsScriptOf, scriptProvenanceOf, scriptRanDigestOf } from "./flow-unattended.js";
 import { tmpdir } from "node:os";
 import { envValue } from "./names.js";
+import { recordBranchCheckRun, unprovenNoticeRuns } from "./tidy.js";
 import { linearLabelNames, readFormSubmission, readGithubEvent, readGithubIssue, readGithubIssueEventList, readGithubIssueList, readGithubRun, readGithubRunList, readInboundMail, readLinearAnswer, readLinearEvent, readLinearIssue, readWebhookPayload } from "./contracts/trigger-payloads.js";
 import { isRecord } from "./is-record.js";
 export { FLOW_TRIGGER_KINDS };
@@ -925,6 +926,9 @@ async function checkTrigger(store, trigger, config, now, io) {
         store.updateFlowTrigger(trigger.id, { failures, lastAt: now.toISOString(), lastOutcome: fetched.problem, nextAt: new Date(now.getTime() + BACKOFF_MS[Math.min(failures, BACKOFF_MS.length) - 1]).toISOString() }, now);
         return { ok: false, said: fetched.problem, added: 0 };
     }
+    // Tidy's CI evidence (task-tidy.md): the watched branch's completed runs, green and red, beside the failures it carded.
+    if (config.kind === "github" && config.watch === "checks")
+        await observeBranchRuns(store, trigger, config, io.gh, now);
     const by = config.kind === "github" ? "GitHub" : config.kind === "linear" ? "Linear" : "Email";
     // Known items are left out before the batch is taken (v126): a page of things already received can't keep the unseen
     // ones behind it waiting.
@@ -1206,6 +1210,14 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body.pull_request, "pull")
                 : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body.workflow_run) : null;
         items = found === null ? [] : [found];
+        // A signed workflow run on the watched branch is tidy's CI evidence too (task-tidy.md), green or red: recorded only
+        // inside `written`, which re-proves the trigger is still active with the same config, credential and address.
+        if (config.watch === "checks" && config.branch !== null && event === "workflow_run" && action === "completed") {
+            const branch = config.branch;
+            const recorded = written(() => { recordBranchCheckRun(store, { repo: config.repo, branch }, readGithubRun(body.workflow_run), now); return { status: 200, said: "Recorded." }; });
+            if (recorded.status !== 200)
+                return recorded;
+        }
     }
     else if (config.kind === "linear") {
         const body = readLinearEvent(payload), sent = Number(body.webhookTimestamp);
@@ -1648,3 +1660,46 @@ export function receiveFlowForm(store, token, fields, now) {
     store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: "Someone sent the form." }, now);
     return { status: 200, html: thanks };
 }
+/** Tidy's CI evidence (docs/plans/task-tidy.md): the watched branch's recent completed workflow runs, read through the
+ * person's own gh login. Recorded only while the trigger still watches exactly that repository and branch once GitHub
+ * answered; any failure records nothing (tidy then keeps the notices). */
+async function observeBranchRuns(store, trigger, config, gh, now) {
+    if (config.branch === null)
+        return;
+    const branch = config.branch;
+    let result;
+    try {
+        result = await gh("gh", ["api", "-H", "Accept: application/vnd.github+json", `repos/${config.repo}/actions/runs?branch=${encodeURIComponent(branch)}&status=completed&per_page=50`], { timeoutMs: 20_000 });
+    }
+    catch {
+        return;
+    }
+    if (result.code !== 0)
+        return;
+    let body;
+    try {
+        body = JSON.parse(result.stdout);
+    }
+    catch {
+        return;
+    }
+    const runs = [...readGithubRunList(body).workflow_runs ?? []];
+    // A few older failure cards' own runs, so tidy can tell whether each was a push to this branch (task-tidy.md).
+    for (const id of unprovenNoticeRuns(store, trigger.id, config.repo)) {
+        try {
+            const one = await gh("gh", ["api", "-H", "Accept: application/vnd.github+json", `repos/${config.repo}/actions/runs/${id}`], { timeoutMs: 20_000 });
+            if (one.code === 0)
+                runs.push(readGithubRun(JSON.parse(one.stdout)));
+        }
+        catch { /* read again next time */ }
+    }
+    // Re-proved and recorded in one transaction: a trigger paused or changed meanwhile records nothing.
+    store.transact(() => {
+        const current = store.getFlowTrigger(trigger.id);
+        const still = current === null ? null : triggerConfigOf(current);
+        if (current === null || current.state !== "active" || current.configJson !== trigger.configJson || still === null || still.kind !== "github" || still.watch !== "checks" || still.repo !== config.repo || still.branch !== branch)
+            return;
+        for (const run of runs)
+            recordBranchCheckRun(store, { repo: config.repo, branch }, run, now);
+    });
+}

package/dist/flow-unattended-words.d.ts

@@ -1,6 +1,26 @@
 /** The words a "runs on its own" grant signs (flow-unattended.ts), kept free of server imports so the flow page's
  * signing form says each limit exactly as the signature will. */
 export declare const dollarWords: (micro: number) => string;
+/** The most runs a day a grant may allow. */
+export declare const UNATTENDED_MAX_RUNS = 50;
+/** The largest per-attempt budget a grant may name: $100. */
+export declare const UNATTENDED_MAX_BUDGET_MICROUSD = 100000000;
+/** A per-attempt budget as typed ("5", "$7.50", "" for no cap), the one way the server and the flow page read it. */
+export declare function unattendedBudgetOf(typed: string): {
+    ok: true;
+    value: number | null;
+} | {
+    ok: false;
+    message: string;
+};
+/** Runs a day as typed ("3", "" for no limit), the one way the server and the flow page read it. */
+export declare function unattendedRunsOf(typed: string): {
+    ok: true;
+    value: number | null;
+} | {
+    ok: false;
+    message: string;
+};
 /** "Oct 19": the end's day, where space is short (the exact time goes beside it, on hover). */
 export declare const untilDayWords: (iso: string) => string;
 /** "Oct 19, 14:05 UTC": the expiry as every surface says it. */

package/dist/flow-unattended-words.js

@@ -1,6 +1,30 @@
 /** The words a "runs on its own" grant signs (flow-unattended.ts), kept free of server imports so the flow page's
  * signing form says each limit exactly as the signature will. */
 export const dollarWords = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
+/** The most runs a day a grant may allow. */
+export const UNATTENDED_MAX_RUNS = 50;
+/** The largest per-attempt budget a grant may name: $100. */
+export const UNATTENDED_MAX_BUDGET_MICROUSD = 100_000_000;
+/** A per-attempt budget as typed ("5", "$7.50", "" for no cap), the one way the server and the flow page read it. */
+export function unattendedBudgetOf(typed) {
+    const text = typed.trim().replace(/^\$/, "");
+    if (text === "")
+        return { ok: true, value: null };
+    const value = Number(text);
+    if (!/^\d+(\.\d{1,2})?$/.test(text) || value <= 0 || Math.round(value * 1_000_000) > UNATTENDED_MAX_BUDGET_MICROUSD)
+        return { ok: false, message: `Give the budget in dollars, up to ${dollarWords(UNATTENDED_MAX_BUDGET_MICROUSD)}, or leave it empty.` };
+    return { ok: true, value: Math.round(value * 1_000_000) };
+}
+/** Runs a day as typed ("3", "" for no limit), the one way the server and the flow page read it. */
+export function unattendedRunsOf(typed) {
+    const text = typed.trim();
+    if (text === "")
+        return { ok: true, value: null };
+    const value = Number(text);
+    if (!/^\d+$/.test(text) || !Number.isInteger(value) || value < 1 || value > UNATTENDED_MAX_RUNS)
+        return { ok: false, message: `Give runs a day as 1 to ${UNATTENDED_MAX_RUNS}, or leave it empty.` };
+    return { ok: true, value };
+}
 /** "Oct 19": the end's day, where space is short (the exact time goes beside it, on hover). */
 export const untilDayWords = (iso) => new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso));
 /** "Oct 19, 14:05 UTC": the expiry as every surface says it. */

package/dist/flow-unattended.d.ts

@@ -8,10 +8,8 @@ export declare const FLOW_ACCEPTANCE: {
     report: AcceptanceCriterion[];
     task: AcceptanceCriterion[];
 };
-/** The most runs a day a grant may allow. */
-export declare const UNATTENDED_MAX_RUNS = 50;
-/** The largest per-attempt budget a grant may name: $100. */
-export declare const UNATTENDED_MAX_BUDGET_MICROUSD = 100000000;
+/** The limits a grant may name, and their one parser, live with its words (the flow page validates with them too). */
+export { UNATTENDED_MAX_BUDGET_MICROUSD, UNATTENDED_MAX_RUNS } from "./flow-unattended-words.js";
 /** The code a script schedule runs, as signed: the script's version and content digest, and for one that runs a project
  * file, that file's path and, sorted by path, the digest of its bytes and of every project file it statically imports. */
 export type SignedScript = {
@@ -77,7 +75,7 @@ export type UnattendedGrant = {
  * revision signed, and neither project protected. Shared by every dispatch belt. */
 export declare const grantStandsSql: (digest: string, now: string, repo: string) => string;
 /** Why a grant ended, as its row and ledger line say it. A renewal's ledger line is the new signature's. */
-export type UnattendedEnd = "expired" | "revoked" | "renewed" | "schedule changed" | "script changed" | "project protected" | "access changed";
+export type UnattendedEnd = "expired" | "revoked" | "renewed" | "flow changed" | "schedule changed" | "script changed" | "project protected" | "access changed";
 /**
  * The one road for what ends grants from outside this module (store.ts calls it): a flow's schedule added, paused,
  * resumed or removed; a project's approval rules protecting work; an account's access or standing changing. Every live
@@ -222,6 +220,12 @@ export type UnattendedView = {
         optional: string | null;
     }[];
     schedulesDigest: string;
+    /** No live grant, and the latest one was ended by a change (the flow, a script, a schedule, the project's rules or
+     * the signer's access) before it would have run out: why, and when, so the page says it no longer runs on its own. */
+    ended: {
+        why: string;
+        at: string;
+    } | null;
 };
 export declare function unattendedViewOf(store: Store, flow: FlowRow, viewer: {
     name: string;

package/dist/flow-unattended.js

@@ -31,7 +31,7 @@ import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isProtectedWork } from "./approval-policy.js";
-import { dollarWords as dollars, scheduleWords, UNATTENDED_RULE_WORDS, unattendedCoverWords, unattendedEndWords, unattendedHeadWords, unattendedLimitWords, untilWords } from "./flow-unattended-words.js";
+import { dollarWords as dollars, scheduleWords, unattendedBudgetOf, unattendedRunsOf, UNATTENDED_RULE_WORDS, unattendedCoverWords, unattendedEndWords, unattendedHeadWords, unattendedLimitWords, untilWords } from "./flow-unattended-words.js";
 import { MODE_MAX_DAYS } from "./modes.js";
 import { accountReachesSql } from "./project-access.js";
 import { canonicalJson } from "./canonical-json.js";
@@ -70,10 +70,8 @@ export const FLOW_ACCEPTANCE = {
     report: [{ id: "c1", statement: "The report answers the request, citing where in the repository each point comes from", how: null, evidence: ["manual-review"] }],
     task: [{ id: "c1", statement: "The requested change is made and the project's existing checks still pass", how: null, evidence: ["manual-review"] }],
 };
-/** The most runs a day a grant may allow. */
-export const UNATTENDED_MAX_RUNS = 50;
-/** The largest per-attempt budget a grant may name: $100. */
-export const UNATTENDED_MAX_BUDGET_MICROUSD = 100_000_000;
+/** The limits a grant may name, and their one parser, live with its words (the flow page validates with them too). */
+export { UNATTENDED_MAX_BUDGET_MICROUSD, UNATTENDED_MAX_RUNS } from "./flow-unattended-words.js";
 export const unattendedTermsJson = (terms) => canonicalJson(terms);
 /** sha256 over a domain-separated canonical encoding, 32 hex like the mode digest. */
 export function unattendedDigestOf(terms) {
@@ -213,10 +211,11 @@ function closeGrant(store, row, by, reason, now) {
 export function endUnattendedGrants(store, filter, by, reason, now) {
     const rows = "flow" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE flow = ? AND revoked_at IS NULL").all(filter.flow)
         : "signer" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE signed_by = ? AND revoked_at IS NULL").all(filter.signer)
-            // A script saved or removed: the grants in its project that signed a schedule running it (an unreadable one too, to be safe).
+            // A script saved or removed: the grants in its project that signed a schedule running it, or whose flow has a step
+            // that runs it (pre-authorized work would run the new code unseen); an unreadable one too, to be safe.
             : "script" in filter ? store.handle.prepare("SELECT * FROM flow_unattended_grant WHERE repo = ? AND revoked_at IS NULL").all(filter.script.repo).filter(row => {
                 const terms = unattendedTermsFromJson(String(row["terms_json"]));
-                return terms === null || terms.triggers.some(one => one.script?.name === filter.script.name);
+                return terms === null || terms.triggers.some(one => one.script?.name === filter.script.name) || flowStepRunsScript(store, Number(row["flow"]), filter.script.name);
             })
                 // A project's rules reach the flows in it and the flows whose build zones work in it.
                 : store.handle.prepare(`SELECT ug.* FROM flow_unattended_grant ug JOIN flow f ON f.id = ug.flow WHERE ug.revoked_at IS NULL
@@ -605,22 +604,13 @@ export function parseUnattendedAsk(input) {
     const days = Number(text(input.days));
     if (!Number.isInteger(days) || days < 1 || days > MODE_MAX_DAYS)
         return { ok: false, message: `Choose 1 to ${MODE_MAX_DAYS} days: it always ends.` };
-    const budgetText = text(input.budget).replace(/^\$/, "");
-    let budgetMicrousd = null;
-    if (budgetText !== "") {
-        const value = Number(budgetText);
-        if (!/^\d+(\.\d{1,2})?$/.test(budgetText) || value <= 0 || Math.round(value * 1_000_000) > UNATTENDED_MAX_BUDGET_MICROUSD)
-            return { ok: false, message: `Give the budget in dollars, up to ${dollars(UNATTENDED_MAX_BUDGET_MICROUSD)}, or leave it empty.` };
-        budgetMicrousd = Math.round(value * 1_000_000);
-    }
-    const runsText = text(input.runs);
-    let dailyRunCap = null;
-    if (runsText !== "") {
-        const value = Number(runsText);
-        if (!Number.isInteger(value) || value < 1 || value > UNATTENDED_MAX_RUNS)
-            return { ok: false, message: `Give runs a day as 1 to ${UNATTENDED_MAX_RUNS}, or leave it empty.` };
-        dailyRunCap = value;
-    }
+    const budget = unattendedBudgetOf(text(input.budget));
+    if (!budget.ok)
+        return budget;
+    const runs = unattendedRunsOf(text(input.runs));
+    if (!runs.ok)
+        return runs;
+    const budgetMicrousd = budget.value, dailyRunCap = runs.value;
     const includeText = Array.isArray(input.include) ? input.include.map(text).join(",") : text(input.include);
     const include = includeText === "" ? [] : includeText.split(/[\s,]+/).filter(one => one !== "").map(Number);
     if (include.some(id => !Number.isSafeInteger(id) || id < 1))
@@ -772,5 +762,37 @@ export function unattendedViewOf(store, flow, viewer, now) {
         terms: { head: unattendedHeadWords(viewer.name, FLOW_ACCEPTANCE), rules: [...UNATTENDED_RULE_WORDS] },
         schedules: candidates.map(one => ({ id: one.id, words: one.words, optional: one.optional })),
         schedulesDigest: candidatesDigestOf(candidates),
+        ended: live === null ? unattendedEndedOf(store, flow.id, now) : null,
     };
 }
+/** Why the flow's latest grant ended early, in words, when a change ended it while it would still have run. */
+const ENDED_WORDS = {
+    "flow changed": "the flow changed", "script changed": "a script it runs changed", "schedule changed": "a schedule changed",
+    "project protected": "the project's approval rules changed", "access changed": "its signer's access changed",
+};
+function unattendedEndedOf(store, flowId, now) {
+    const row = store.handle.prepare("SELECT revoked_at, revoke_reason, absolute_expiry FROM flow_unattended_grant WHERE flow = ? ORDER BY id DESC LIMIT 1").get(flowId);
+    if (row === undefined || row["revoked_at"] == null)
+        return null;
+    const why = ENDED_WORDS[String(row["revoke_reason"])];
+    return why === undefined || Date.parse(String(row["absolute_expiry"])) <= now.getTime() ? null : { why, at: String(row["revoked_at"]) };
+}
+/** Whether one of the flow's "Run a script" steps runs this script. A drawing that isn't readable and well formed counts,
+ * to be safe. */
+function flowStepRunsScript(store, flowId, name) {
+    const flow = store.getFlow(flowId);
+    if (flow === null)
+        return false;
+    let drawn;
+    try {
+        drawn = JSON.parse(flow.definitionJson);
+    }
+    catch {
+        return true;
+    }
+    // Anything but a well-formed drawing (an object whose stages are a list of objects) fails closed: the grant ends.
+    const stages = drawn !== null && typeof drawn === "object" && !Array.isArray(drawn) ? drawn.stages : undefined;
+    if (!Array.isArray(stages) || !stages.every(stage => stage !== null && typeof stage === "object" && !Array.isArray(stage)))
+        return true;
+    return stages.some(stage => stage.kind === "check" && stage.script === name);
+}

package/dist/flows-cli.d.ts

@@ -296,6 +296,25 @@ export declare const FLOWS_DESCRIPTORS: readonly [{
         readonly takesValue: true;
         readonly meaning: 'also cover these script or plane-review schedules (trigger ids, like 12,14); plain schedules are covered already';
     }];
+}, {
+    readonly action: 'browser';
+    readonly synopsis: "let a flow's script zones marked browser: true start Chromium in their sandbox (on: a person approves with their own password, previews until --yes; off: any approver revokes)";
+    readonly mutation: 'identity-idempotent';
+    readonly audience: 'operator';
+    readonly positionals: readonly ['flow', 'on|off'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'digest';
+        readonly takesValue: true;
+        readonly meaning: "required with --yes: the approval digest the preview showed; refuses if the flow or its scripts changed since";
+    }];
 }, {
     readonly action: 'archive';
     readonly synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes';

package/dist/flows-cli.js

@@ -19,6 +19,7 @@ import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, swi
 import { addFlowTriggerTo, checkFlowTriggerNow, describeTrigger, removeFlowTrigger, setFlowTriggerOn, triggerConfigOf, validateTriggerConfig, rawTakesDeliveries } from './flow-triggers.js';
 import { deciderOf, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowDigest, flowFromSteps, flowTerms, stepsFor } from './flows.js';
 import { prepareUnattendedCandidates, activeUnattendedGrant, parseUnattendedAsk, revokeUnattended, signUnattended, unattendedViewOf, unattendedWords, untilWords, UNATTENDED_MAX_RUNS } from './flow-unattended.js';
+import { browserApprovalDigest, browserTerms, browserTermsOf, browserViewOf, revokeFlowBrowser, signFlowBrowser } from './flow-browser.js';
 import { MODE_MAX_DAYS } from './modes.js';
 import { verifyApproverByPassword } from './principal.js';
 import { authenticateApprover, proveCredential } from './scope.js';
@@ -71,6 +72,8 @@ export const FLOWS_DESCRIPTORS = [
             { name: 'budget', takesValue: true, meaning: 'optional dollar cap per attempt, like 5 or 2.50' },
             { name: 'runs', takesValue: true, meaning: `optional limit on runs a day (UTC), 1 to ${UNATTENDED_MAX_RUNS}` },
             { name: 'include', takesValue: true, meaning: 'also cover these script or plane-review schedules (trigger ids, like 12,14); plain schedules are covered already' }] },
+    { action: 'browser', synopsis: "let a flow's script zones marked browser: true start Chromium in their sandbox (on: a person approves with their own password, previews until --yes; off: any approver revokes)", mutation: 'identity-idempotent', audience: 'operator', positionals: ['flow', 'on|off'], flags: [...write, yes,
+            { name: 'digest', takesValue: true, meaning: "required with --yes: the approval digest the preview showed; refuses if the flow or its scripts changed since" }] },
     { action: 'archive', synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes', mutation: 'identity-idempotent', positionals: ['flow'], flags: [...write, yes] },
 ];
 /** `--file` is a value here (a path in the project), where elsewhere it is a switch; so are unattended's `--budget`, `--runs` and `--include`. */
@@ -160,10 +163,12 @@ export async function runFlowsCommand(positional, flags, context) {
     const refuse = (project, reason, message, code = EXIT.refused) => { record(project, 'refused', reason); return fail(reason, message, code); };
     // A trigger from anyone widens what comes in (chat-management.md §0a.3): only the person's own proof counts, never a
     // machine credential standing in for them (a remote run's API token, a lead's token), though both pass the check above.
-    const widening = (project) => {
+    // The same proof approves browser use in a flow's script zones (flow-browser.ts): the method is recorded with it.
+    const personMethod = (project) => {
         const proved = authenticateApprover(store, acting.name, acting.token, project);
-        return proved.ok && personProof(proved.method) ? { widening: 'proved' } : {};
+        return proved.ok && personProof(proved.method) ? proved.method : null;
     };
+    const widening = (project) => personMethod(project) === null ? {} : { widening: 'proved' };
     const settle = (project) => { try {
         advanceFlows(store, project, context.clock(), { evidenceRoot: context.evidenceRoot });
     }
@@ -359,8 +364,10 @@ export async function runFlowsCommand(positional, flags, context) {
             return refuse(project, 'unknown-script', `There's no script called ${name} in ${projectName(project)}.`);
         if (script.held === null)
             return ok({ applied: false, repo: project, said: `${script.name} already runs.` }, [`${script.name} already runs.`]);
-        store.approveFlowScript(project, script.name);
-        record(project, 'accepted', `script ${script.name} approved`);
+        // Bound to the version just read: a script swapped under the same name meanwhile is refused, never approved unseen.
+        if (store.approveFlowScript(project, script.name, { version: script.version, digest: script.digest }) !== 'approved')
+            return refuse(project, 'changed', `${script.name} changed while this ran. Read it again (toolroll flows show), then approve it. Nothing was approved.`);
+        record(project, 'accepted', `script ${script.name} v${script.version} approved`);
         settle(project);
         return ok({ applied: true, repo: project, said: `Approved ${script.name}. Zones that run it go on.` }, [`Approved ${script.name}. Zones that run it go on.`]);
     }
@@ -396,6 +403,42 @@ export async function runFlowsCommand(positional, flags, context) {
             `Revoke: toolroll flows unattended ${flow.id} off`,
         ]);
     }
+    if (action === 'browser') {
+        const flow = flowOf(args[0], reachable);
+        if (flow === null)
+            return refuse(null, 'unknown-flow', 'No such flow in your projects. toolroll flows list names them.');
+        const turn = args[1];
+        if (turn !== 'on' && turn !== 'off')
+            return fail('usage', `Use flows browser ${flow.id} on, or flows browser ${flow.id} off.`, EXIT.usage);
+        if (turn === 'off') {
+            // Lowering authority is one step for any approver on the project.
+            if (!revokeFlowBrowser(store, flow.id, who, now))
+                return refuse(flow.repo, 'not-on', `${flow.name} has no approved browser use. Nothing was changed.`);
+            record(flow.repo, 'accepted', `flow #${flow.id} browser off`);
+            return ok({ applied: true, browser: null }, [`${flow.name}'s scripts can no longer start a browser.`]);
+        }
+        if (flowDefinitionOf(flow) === null)
+            return refuse(flow.repo, 'unreadable', 'This flow\'s drawing can\'t be read. Save it again from the editor.');
+        const terms = browserTermsOf(store, flow);
+        if (terms === null || terms.zones.length === 0)
+            return refuse(flow.repo, 'refused', terms === null ? '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). Nothing was changed.'
+                : `No zone in ${flow.name} says it starts a browser. Mark its script zone with browser: true (flows edit), then approve. Nothing was changed.`);
+        const digest = browserApprovalDigest(terms);
+        if (!flags.has('yes'))
+            return preview(flow.repo, `Approve browser use in the ${flow.name} flow`, [...browserTerms(terms.zones), `Approval digest ${digest}: approve exactly this with --yes --digest ${digest}.`], { flowId: flow.id, digest, zones: terms.zones });
+        // A person's own proof only: a lead's or remote run's token passes the approver check above but never approves this.
+        // The digest the person read is required: approving with --yes alone could approve something they never saw.
+        const given = text('digest');
+        if (given === null)
+            return fail('usage', `Approve exactly what you read: flows browser ${flow.id} on --yes --digest <the digest the preview showed>.`, EXIT.usage);
+        const signed = signFlowBrowser(store, { flow: flow.id, signer: who, proof: personMethod(flow.repo), sawDigest: given }, now);
+        if (!signed.ok)
+            return refuse(flow.repo, 'refused', `${signed.message} Nothing was changed.`);
+        record(flow.repo, 'accepted', `flow #${flow.id} browser on`);
+        return ok({ applied: true, browser: { digest: signed.grant.digest, zones: signed.grant.zones, signedBy: signed.grant.signedBy } }, [
+            `${flow.name} may start a browser. Approved by ${who}:`, ...browserTerms(signed.grant.zones).map(line => `  ${line}`), `Revoke: toolroll flows browser ${flow.id} off`,
+        ]);
+    }
     if (action === 'archive') {
         const cards = store.flowCards(flow.id, false).length, triggers = store.flowTriggers(flow.id).filter(one => one.state === 'active').length;
         if (!flags.has('yes'))
@@ -566,6 +609,7 @@ function zoneOf(stage, flow) {
         ...(stage.limit === undefined ? {} : { remindAfterMinutes: stage.limit.minutes, thenMoveTo: stage.limit.to }),
         ...(stage.kind === 'approval' ? { decider: deciderOf(stage, flow) } : {}),
         ...(stage.script === null ? {} : { script: stage.script }),
+        ...(stage.browser === true ? { browser: true } : {}),
         ...(stage.merge === undefined ? {} : { merge: stage.merge }),
         ...(stage.subagent === undefined ? {} : { subagent: stage.subagent }),
         ...(stage.options === undefined ? {} : { options: stage.options.map(one => ({ label: one.label, to: one.to })) }),
@@ -589,6 +633,10 @@ function describeFlow(store, flow, now) {
         }),
         cards: store.flowCards(flow.id, true).slice(0, 10).map(card => cardOf(definition, card)),
         unattended: unattendedJson(store, flow, now),
+        // The latest grant a change ended early (the flow, a script, a schedule): why and when, as the flow page says it.
+        ...(() => { const ended = unattendedViewOf(store, flow, { name: flow.owner, approver: true }, now).ended; return ended === null ? {} : { unattendedEnded: ended }; })(),
+        // Browser use, only for a flow with a zone that starts one: the same status line the flow page shows.
+        ...(() => { const view = browserViewOf(store, flow); return view === null ? {} : { browser: { status: view.status, words: view.words, signedBy: view.signedBy, signedAt: view.signedAt } }; })(),
     };
 }
 /** Whether a flow runs on its own, and until when: null when it doesn't. */
@@ -603,9 +651,10 @@ function showLines(flow) {
     return [
         `#${flow.id} ${flow.name} · ${flow.project} · owner ${flow.owner}`,
         flow.unattended === null
-            ? `Runs on its own: no · turn on: toolroll flows unattended ${flow.id} on --days N`
+            ? `Runs on its own: no${'unattendedEnded' in flow && flow.unattendedEnded !== undefined ? ` (it ended ${untilWords(flow.unattendedEnded.at)}: ${flow.unattendedEnded.why})` : ''} · turn on: toolroll flows unattended ${flow.id} on --days N`
             : `Runs on its own until ${untilWords(flow.unattended.until)} · revoke: toolroll flows unattended ${flow.id} off`,
         ...(flow.unattended === null ? [] : [`  Covers: ${flow.unattended.covers.join('; ')}`]),
+        ...(flow.browser === undefined ? [] : [`${flow.browser.words} · ${flow.browser.status === 'allowed' ? `turn off: toolroll flows browser ${flow.id} off` : `allow: toolroll flows browser ${flow.id} on`}`]),
         '', 'Zones',
         ...flow.zones.flatMap((zone, index) => [
             `  ${index + 1}. ${zone.title} (${zone.id}) — ${zone.does}${zone.id === flow.start ? ' · start' : ''}`,

package/dist/flows-ui.d.ts

@@ -2,12 +2,18 @@ import type { BrowserFlowView } from "./browser-workspace.js";
 import type { FlowRow, Store } from "./store.js";
 import { type FlowFile, type FlowImportPlan } from "./flow-share.js";
 import { type Html } from "./html.js";
-export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:10px 0 0}.flows .flow-import{margin-top:18px;padding-top:14px;border-top:1px solid var(--so-line)}.flows .flow-import h3{font-size:.95rem;margin:0}.flows .flow-terms{list-style:none;padding:0;margin:8px 0 16px;display:grid;gap:10px}.flows .flow-terms li{white-space:pre-line;overflow-wrap:anywhere}.flows .flow-terms pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:.8rem;margin:6px 0 0}.flows .flow-import-preview h2{font-size:1rem;margin:20px 0 4px}.flows .flow-untrusted{font-weight:600}.flows button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}.flows fieldset{border:0;padding:0;margin:0;display:grid;gap:10px;min-width:0}.flows legend{font-weight:600;padding:0;margin-bottom:6px}.flows textarea[hidden]{display:none}.flows button.secondary{background:transparent;color:var(--foreground);border:1px solid var(--border)}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:\"\";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}";
-/** The flows a person can open, with how many cards wait in each, and the new-flow form. */
-export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], canCreate: boolean, problem: string | null): Html;
-/** Reads the chosen flow file into the form (the server reads it again, whole, before anything is made). */
-export declare const FLOW_IMPORT_SCRIPT = "(function(){var form=document.querySelector('[data-flow-import]');if(!form)return;var input=form.querySelector('[data-flow-file]'),text=form.querySelector('[data-flow-document]'),note=form.querySelector('[data-flow-file-note]'),address=form.querySelector('[name=url]');function say(words){note.textContent=words;note.hidden=words==='';}var reading=null;input.addEventListener('change',function(){text.value='';say('');var file=input.files&&input.files[0];if(!file){reading=null;return;}if(file.size>262144){say('That file is too big: a flow file is at most 256 KB.');input.value='';reading=null;return;}reading=file.text().then(function(value){text.value=value;});});form.addEventListener('submit',function(event){if(reading!==null&&text.value===''){event.preventDefault();reading.then(function(){form.requestSubmit();});return;}if(text.value===''&&address.value.trim()===''){event.preventDefault();say('Choose a flow file or give its address.');}});})();";
-/** An import's preview: the plan in plain words, what it asks for, and one Import button after the terms. */
+/** The flow page's fallback rules, plus the Flows list and the import preview (kit pieces; only layout here). */
+export declare const FLOWS_CSS: string;
+/**
+ * Flows: the top bar (a project filter, More, New flow), then each flow as a quiet row under Needs you, Running,
+ * Turned on and Paused. Words come only from what the store knows now: cards waiting on a decision, cards in
+ * progress, and the triggers (on, paused, when they last looked and what they found).
+ */
+export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], canCreate: boolean, problem: string | null, filter?: string | null, now?: Date): Html;
+/** Reads the chosen flow file into the form (the server reads it again, whole, before anything is made), and sends a
+ * filter select's form when it changes. */
+export declare const FLOW_IMPORT_SCRIPT = "(function(){document.querySelectorAll('select[data-k-autosubmit]').forEach(function(s){s.addEventListener('change',function(){if(s.form)s.form.requestSubmit();});});var form=document.querySelector('[data-flow-import]');if(!form)return;var input=form.querySelector('[data-flow-file]'),text=form.querySelector('[data-flow-document]'),note=form.querySelector('[data-flow-file-note]'),named=form.querySelector('[data-flow-file-name]'),address=form.querySelector('[name=url]');function say(words){note.textContent=words;note.hidden=words==='';}var reading=null;input.addEventListener('change',function(){text.value='';say('');var file=input.files&&input.files[0];if(named)named.textContent=file?file.name:'No file chosen';if(!file){reading=null;return;}if(file.size>262144){say('That file is too big: a flow file is at most 256 KB.');input.value='';if(named)named.textContent='No file chosen';reading=null;return;}reading=file.text().then(function(value){text.value=value;});});form.addEventListener('submit',function(event){if(reading!==null&&text.value===''){event.preventDefault();reading.then(function(){form.requestSubmit();});return;}if(text.value===''&&address.value.trim()===''){event.preventDefault();say('Choose a flow file or give its address.');}});})();";
+/** An import's preview, a reading page: the plan in plain words, what it asks for, and one Import button after the terms. */
 export declare function flowImportHtml(input: {
     plan: FlowImportPlan | null;
     file: FlowFile;