toolroll 0.9.62 → 0.9.63

package/dist/flow-triggers.d.ts

@@ -51,11 +51,11 @@ export declare function triggerConfigOf(trigger: FlowTriggerRow): TriggerConfig
 export declare function readTriggerConfig(raw: unknown): ContractResult<TriggerConfig>;
 /** Whether this trigger takes deliveries at a secret address rather than being checked. */
 export declare function takesDeliveries(config: TriggerConfig): boolean;
-/** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). 0600, beside the database, never a column. */
+/** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). In the keychain (or an owner-only file where there's none), never a column. */
 export declare function saveHookSecret(dir: string, trigger: number, secret: string): void;
 export declare function readHookSecret(dir: string, trigger: number): string | null;
 export declare const LINEAR_ENV = "TOOLROLL_LINEAR_KEY";
-/** The Linear API key the worker checks Linear with: the environment, or a 0600 file beside the database. */
+/** The Linear API key the worker checks Linear with: the environment, or kept by Toolroll (the keychain, or an owner-only file beside the database). */
 export declare function readLinearKey(dir: string | null): string | null;
 export declare function saveLinearKey(dir: string, key: string): {
     ok: true;
@@ -96,13 +96,17 @@ export declare function renewFlowHook(store: Store, trigger: FlowTriggerRow, now
  * Pause a trigger, or turn it on again. A schedule that never had a time (a routine moved to a flow while it waited
  * for approval, v115) starts counting from now, as a new schedule does; one that was due while it was off fires once.
  */
-export declare function setFlowTriggerOn(store: Store, trigger: FlowTriggerRow, on: boolean, now: Date): void;
-export declare function removeFlowTrigger(store: Store, trigger: FlowTriggerRow, now: Date, dir: string | null): void;
+export declare function setFlowTriggerOn(store: Store, trigger: FlowTriggerRow, on: boolean, now: Date, by?: string): void;
+export declare function removeFlowTrigger(store: Store, trigger: FlowTriggerRow, now: Date, dir: string | null, by?: string): void;
+/** `onTime`: the clock's own firing of a schedule (never Run now or Check now); only those can run on their own.
+ * `ranScript`: for a script's, what code it ran (scriptRanDigestOf), which must be the code a grant signed. */
 export type Incoming = {
     key: string;
     title: string;
     description: string | null;
     source: FlowCardSource;
+    onTime?: boolean;
+    ranScript?: string | null;
 };
 type Made = "added" | "seen" | "skipped";
 /** One outside thing into one card through a trigger (a chat channel's message, v89): at most once per key. */

package/dist/flow-triggers.js

@@ -31,7 +31,8 @@ import { html, htmlString, postForm, styleElement } from "./html.js";
  * and a card's work is an ordinary task under the usual approvals.
  */
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { SecretStoreError, readHeldSecret, writeHeldSecret } from "./tool-secret-store.js";
 import { join } from "node:path";
 import { scanForSecrets } from "./evidence.js";
 import { flowCardText, flowDefinitionOf } from "./flow-engine.js";
@@ -42,6 +43,7 @@ import { describeSchedule, fileStandingOrder, firstFireAt, nextFireAt, parseSche
 import { takeReply } from "./flow-replies.js";
 import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./mailbox.js";
 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 { linearLabelNames, readFormSubmission, readGithubEvent, readGithubIssue, readGithubIssueEventList, readGithubIssueList, readGithubRun, readGithubRunList, readInboundMail, readLinearAnswer, readLinearEvent, readLinearIssue, readWebhookPayload } from "./contracts/trigger-payloads.js";
@@ -330,26 +332,33 @@ export function takesDeliveries(config) {
 }
 // ------------------------------------------------------ secrets on disk
 const hookHash = (token) => createHash("sha256").update(token).digest("hex");
-const secretFile = (dir, trigger) => join(dir, "flow-hooks", `${trigger}.json`);
-/** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). 0600, beside the database, never a column. */
+/** A webhook's signing secret: kept by Toolroll (tool-secret-store.ts) as `flow-hook.<trigger>`, in a file of that name before. */
+const hookSecret = (trigger) => ({ name: `flow-hook.${trigger}`, file: ["flow-hooks", `${trigger}.json`] });
+/** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). In the keychain (or an owner-only file where there's none), never a column. */
 export function saveHookSecret(dir, trigger, secret) {
-    mkdirSync(join(dir, "flow-hooks"), { recursive: true, mode: 0o700 });
-    writeFileSync(secretFile(dir, trigger), `${JSON.stringify({ secret })}\n`, { mode: 0o600 });
-    chmodSync(secretFile(dir, trigger), 0o600);
+    const held = hookSecret(trigger);
+    writeHeldSecret(dir, held.name, held.file, `${JSON.stringify({ secret })}\n`);
 }
 export function readHookSecret(dir, trigger) {
+    const held = hookSecret(trigger);
     try {
-        const parsed = JSON.parse(readFileSync(secretFile(dir, trigger), "utf8"));
-        return typeof parsed.secret === "string" && parsed.secret !== "" ? parsed.secret : null;
+        const parsed = JSON.parse(readHeldSecret(dir, held.name, held.file) ?? "null");
+        return typeof parsed?.secret === "string" && parsed.secret !== "" ? parsed.secret : null;
     }
     catch {
         return null;
     }
 }
-function dropHookSecret(dir, trigger) { rmSync(secretFile(dir, trigger), { force: true }); }
-const LINEAR_FILE = "linear-key";
+function dropHookSecret(dir, trigger) {
+    const held = hookSecret(trigger);
+    try {
+        writeHeldSecret(dir, held.name, held.file, null);
+    }
+    catch { /* the trigger is gone; an orphan is never read */ }
+}
+const LINEAR = { name: "linear-key", file: ["linear-key"] };
 export const LINEAR_ENV = "TOOLROLL_LINEAR_KEY";
-/** The Linear API key the worker checks Linear with: the environment, or a 0600 file beside the database. */
+/** The Linear API key the worker checks Linear with: the environment, or kept by Toolroll (the keychain, or an owner-only file beside the database). */
 export function readLinearKey(dir) {
     const env = envValue(process.env, "LINEAR_KEY")?.trim();
     if (env)
@@ -357,7 +366,7 @@ export function readLinearKey(dir) {
     if (dir === null)
         return null;
     try {
-        const key = readFileSync(join(dir, LINEAR_FILE), "utf8").trim();
+        const key = (readHeldSecret(dir, LINEAR.name, LINEAR.file) ?? "").trim();
         return key === "" ? null : key;
     }
     catch {
@@ -368,11 +377,15 @@ export function saveLinearKey(dir, key) {
     const clean = key.trim();
     if (!/^lin_(api|oauth)_[A-Za-z0-9]{20,}$/.test(clean))
         return { ok: false, message: "That doesn't look like a Linear API key. Copy it from Linear → Settings → Security & access → Personal API keys." };
-    writeFileSync(join(dir, LINEAR_FILE), `${clean}\n`, { mode: 0o600 });
-    chmodSync(join(dir, LINEAR_FILE), 0o600);
+    try {
+        writeHeldSecret(dir, LINEAR.name, LINEAR.file, `${clean}\n`);
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof SecretStoreError ? error.message : "The key couldn't be saved." };
+    }
     return { ok: true };
 }
-export function removeLinearKey(dir) { rmSync(join(dir, LINEAR_FILE), { force: true }); }
+export function removeLinearKey(dir) { writeHeldSecret(dir, LINEAR.name, LINEAR.file, null); }
 const HOOKS_FILE = "hooks-url";
 /** The public address webhooks reach this console at (a reverse proxy such as Caddy, exposing /hooks/ only). */
 export function readHooksBase(dir) {
@@ -457,13 +470,13 @@ export function renewFlowHook(store, trigger, now, dir) {
  * Pause a trigger, or turn it on again. A schedule that never had a time (a routine moved to a flow while it waited
  * for approval, v115) starts counting from now, as a new schedule does; one that was due while it was off fires once.
  */
-export function setFlowTriggerOn(store, trigger, on, now) {
+export function setFlowTriggerOn(store, trigger, on, now, by) {
     const config = on && trigger.nextAt === null ? triggerConfigOf(trigger) : null;
     const schedule = config !== null && (config.kind === "schedule" || config.kind === "plane-review") ? parseSchedule(config.schedule) : null;
-    store.updateFlowTrigger(trigger.id, { state: on ? "active" : "paused", ...(schedule === null ? {} : { nextAt: firstFireAt(schedule, now) }) }, now);
+    store.updateFlowTrigger(trigger.id, { state: on ? "active" : "paused", ...(schedule === null ? {} : { nextAt: firstFireAt(schedule, now) }) }, now, by);
 }
-export function removeFlowTrigger(store, trigger, now, dir) {
-    store.updateFlowTrigger(trigger.id, { state: "removed", hookHash: null }, now);
+export function removeFlowTrigger(store, trigger, now, dir, by) {
+    store.updateFlowTrigger(trigger.id, { state: "removed", hookHash: null }, now, by);
     if (dir !== null)
         dropHookSecret(dir, trigger.id);
 }
@@ -506,7 +519,7 @@ function makeCard(store, trigger, config, item, by, now) {
             return { made: "skipped", note: `${item.source.label}: ${note}`, card: null };
         }
         const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: startZone(config, definition), by, source: item.source }, now);
-        store.recordFlowTriggerEvent(trigger.id, item.key, card, null, now);
+        store.recordFlowTriggerEvent(trigger.id, item.key, card, null, now, null, item.onTime === true, item.ranScript ?? null);
         return { made: "added", note: null, card };
     });
 }
@@ -587,7 +600,10 @@ export function pressFlowButton(store, trigger, answers, actor, now) {
 /** Every trigger in one project that is due: schedules and other flows here, GitHub, Linear and email by asking them. */
 export async function runFlowTriggers(store, repo, now, io) {
     const pass = { added: 0, checked: 0, problems: [] };
-    for (const trigger of store.activeFlowTriggers(repo)) {
+    const triggers = store.activeFlowTriggers(repo);
+    for (const flow of new Set(triggers.map(one => one.flow)))
+        await prepareUnattendedCandidates(store, flow);
+    for (const trigger of triggers) {
         const config = triggerConfigOf(trigger);
         if (config === null)
             continue;
@@ -655,7 +671,7 @@ function fireSchedule(store, trigger, config, now) {
     const day = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: schedule.kind === "every" ? "UTC" : schedule.timezone ?? "UTC" }).format(new Date(slot));
     const fill = (text) => text.replace(/\{\{\s*date\s*\}\}/g, day);
     const title = /\{\{\s*date\s*\}\}/.test(config.title) ? fill(config.title) : `${config.title} — ${day}`;
-    const item = { key: `slot:${slot}`, title, description: config.description === null ? null : fill(config.description), source: { kind: "schedule", label: "Schedule", url: null } };
+    const item = { key: `slot:${slot}`, title, description: config.description === null ? null : fill(config.description), source: { kind: "schedule", label: "Schedule", url: null }, onTime: true };
     const made = config.order === undefined ? makeCard(store, trigger, config, item, "Schedule", now) : fileOrderCard(store, trigger, config, config.order, item, slot, now);
     store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: made.made === "added" ? made.note ?? "Added a card." : made.note ?? "Nothing new." }, now);
     return made.made === "added" ? 1 : 0;
@@ -713,7 +729,7 @@ export async function firePlaneReview(store, trigger, config, now, scheduled) {
             continue;
         }
         const text = problemCard(problem, dayWords);
-        const made = makeCard(store, trigger, config, { key, title: text.title, description: text.description, source: { kind: "plane-review", label: "Plane review", url: null } }, "Plane review", now);
+        const made = makeCard(store, trigger, config, { key, title: text.title, description: text.description, source: { kind: "plane-review", label: "Plane review", url: null }, onTime: scheduled }, "Plane review", now);
         if (made.made === "added")
             added++;
         else if (made.note !== null)
@@ -768,6 +784,9 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     const { agentFence } = await import("./agent-fence.js");
     const scratch = io.scratch ?? join(io.dir ?? tmpdir(), "flow-scratch");
     const folder = cleanFolder(scratch, `flow-trigger-${trigger.id}`);
+    // Its cards run on their own only if it ran the very code a grant signed: pinned just before and just after the run.
+    const pin = scheduled && grantSignsScriptOf(store, flow.id, trigger.id, now) ? () => scriptProvenanceOf(store, flow.repo, script.name) : null;
+    const before = pin === null ? null : await pin();
     let ran;
     try {
         ran = await runCode({ script, cwd: folder, root: flow.repo, scratch, shell: io.shell ?? io.gh,
@@ -780,9 +799,10 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     }
     if (ran.state === "failed")
         return done(false, ran.said.split("\n")[0]);
+    const ranScript = pin === null ? null : scriptRanDigestOf(before, await pin(), script);
     const items = cardsFromOutput(ran.printed);
     const results = items.slice(0, CARDS_PER_CHECK).map(item => makeCard(store, trigger, config, {
-        key: `script:${item.key}`, title: item.title, description: item.description, source: { kind: "script", label: `The ${script.name} script`, url: null },
+        key: `script:${item.key}`, title: item.title, description: item.description, source: { kind: "script", label: `The ${script.name} script`, url: null }, onTime: scheduled, ranScript,
     }, `The ${script.name} script`, now));
     return done(true, items.length === 0 ? `${script.name} ran and printed nothing to add.` : outcomeWords(results, items.length > CARDS_PER_CHECK), results.filter(one => one.made === "added").length);
 }
@@ -1090,7 +1110,7 @@ export function hookReady(trigger, dir) {
         return false;
     if (config.kind === "webhook")
         return true;
-    return dir !== null && existsSync(secretFile(dir, trigger.id));
+    return dir !== null && readHookSecret(dir, trigger.id) !== null;
 }
 // ------------------------------------------------------ public forms (v84)
 export const FORM_PATH = "/hooks/form/";

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

@@ -0,0 +1,28 @@
+/** 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;
+/** "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. */
+export declare const untilWords: (iso: string) => string;
+/** Who approves, with what permissions and against which criteria. */
+export declare function unattendedHeadWords(owner: string, acceptance: {
+    task: readonly {
+        statement: string;
+    }[];
+    report: readonly {
+        statement: string;
+    }[];
+}): string[];
+/** "daily at 09:00" from a stored schedule ("daily:09:00@Europe/London"), kept here so every surface says it alike. */
+export declare function scheduleWords(stored: string): string;
+/** Which schedules the grant covers, by name and time. */
+export declare const unattendedCoverWords: (triggers: readonly {
+    words: string;
+}[]) => string;
+/** The optional limits. */
+export declare function unattendedLimitWords(budgetMicrousd: number | null, dailyRunCap: number | null): string[];
+/** What it never covers, and what ends it. */
+export declare const UNATTENDED_RULE_WORDS: readonly string[];
+export declare const unattendedEndWords: (expiry: string) => string;
+export declare const unattendedEndAfterWords: (days: number) => string;

package/dist/flow-unattended-words.js

@@ -0,0 +1,50 @@
+/** 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)}`;
+/** "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. */
+export const untilWords = (iso) => `${new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" }).format(new Date(iso))}, ${iso.slice(11, 16)} UTC`;
+/** Who approves, with what permissions and against which criteria. */
+export function unattendedHeadWords(owner, acceptance) {
+    return [
+        `Cards this flow's own schedule adds file their work approved by ${owner}, without waiting in Needs you.`,
+        "Builds use safe permissions: routine project commands and edits proceed; risky acts stop for approval.",
+        `Builds are checked against: “${acceptance.task.map(one => one.statement).join("”; “")}”.`,
+        `Research is checked against: “${acceptance.report.map(one => one.statement).join("”; “")}”.`,
+    ];
+}
+/** "daily at 09:00" from a stored schedule ("daily:09:00@Europe/London"), kept here so every surface says it alike. */
+export function scheduleWords(stored) {
+    const days = ["Sundays", "Mondays", "Tuesdays", "Wednesdays", "Thursdays", "Fridays", "Saturdays"];
+    const [when, zone] = stored.split("@");
+    const parts = (when ?? "").split(":");
+    const tz = zone === undefined ? "" : ` ${zone}`;
+    if (parts[0] === "every") {
+        const n = Number(parts[1]);
+        return n % 1440 === 0 ? `every ${n / 1440} day${n === 1440 ? "" : "s"}` : n % 60 === 0 ? `every ${n / 60} hour${n === 60 ? "" : "s"}` : `every ${n} minutes`;
+    }
+    if (parts[0] === "daily" || parts[0] === "weekdays")
+        return `${parts[0]} at ${parts[1]}:${parts[2]}${tz}`;
+    if (parts[0] === "weekly")
+        return `${days[Number(parts[1])] ?? "weekly"} at ${parts[2]}:${parts[3]}${tz}`;
+    return stored;
+}
+/** Which schedules the grant covers, by name and time. */
+export const unattendedCoverWords = (triggers) => `It covers ${triggers.length === 1 ? "this schedule" : "these schedules"} when ${triggers.length === 1 ? "it fires" : "they fire"} on time: ${triggers.map(one => one.words).join("; ")}. Run now, and schedules added or changed later, wait for you.`;
+/** The optional limits. */
+export function unattendedLimitWords(budgetMicrousd, dailyRunCap) {
+    return [
+        budgetMicrousd === null ? "No dollar cap per attempt." : `Each attempt may spend up to ${dollarWords(budgetMicrousd)}.`,
+        dailyRunCap === null ? "No daily limit on runs." : `At most ${dailyRunCap} run${dailyRunCap === 1 ? "" : "s"} a day (UTC); after that, cards wait for you.`,
+    ];
+}
+/** What it never covers, and what ends it. */
+export const UNATTENDED_RULE_WORDS = [
+    "Plans are approved only when they keep the filed request exactly. Questions and plan changes still wait for you.",
+    "Never covered: Person decides steps, pull request merges, publish or deploy scripts, and anything it sends. Cards people add and other triggers wait as usual.",
+    "Editing the flow, its schedules, a script they run or a project file it imports, changing its owner, the owner losing access, or protecting the project ends this.",
+    "Signing again replaces it: work it approved that hasn't started goes back to waiting for you.",
+];
+export const unattendedEndWords = (expiry) => `Ends ${untilWords(expiry)}. Revoking it earlier is one click.`;
+export const unattendedEndAfterWords = (days) => `Ends ${days} day${days === 1 ? "" : "s"} after you sign. Revoking it earlier is one click.`;

package/dist/flow-unattended.d.ts

@@ -0,0 +1,227 @@
+import type { AcceptanceCriterion } from "./contracts/scope.js";
+import { untilWords } from "./flow-unattended-words.js";
+import type { FlowRow, FlowTriggerRow, Store } from "./store.js";
+/** Grant history, run reservations and the last prepared script snapshots shared by UI/worker processes. Additive only. */
+export declare const FLOW_UNATTENDED_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_script_provenance (\n  repo TEXT NOT NULL, name TEXT NOT NULL, snapshot TEXT, PRIMARY KEY (repo, name)\n);\nCREATE TABLE IF NOT EXISTS flow_unattended_grant (\n  id              INTEGER PRIMARY KEY AUTOINCREMENT,\n  flow            INTEGER NOT NULL,\n  repo            TEXT NOT NULL,\n  flow_revision   INTEGER NOT NULL,\n  terms_json      TEXT NOT NULL,\n  digest          TEXT NOT NULL,\n  signed_by       TEXT NOT NULL,\n  signed_at       TEXT NOT NULL,\n  absolute_expiry TEXT NOT NULL,\n  revoked_at      TEXT,\n  revoked_by      TEXT,\n  revoke_reason   TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS flow_unattended_live ON flow_unattended_grant (flow) WHERE revoked_at IS NULL;\nCREATE INDEX IF NOT EXISTS flow_unattended_digest ON flow_unattended_grant (digest);\nCREATE TABLE IF NOT EXISTS flow_unattended_run (\n  grant_id INTEGER NOT NULL,\n  day      TEXT NOT NULL,\n  task_id  TEXT NOT NULL,\n  at       TEXT NOT NULL,\n  PRIMARY KEY (grant_id, task_id)\n);\nCREATE INDEX IF NOT EXISTS flow_unattended_run_day ON flow_unattended_run (grant_id, day);\n";
+/** The fixed acceptance criteria a flow's work zones file with: the same for every card, so a grant can freeze them. */
+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 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 = {
+    provenance: 2;
+    name: string;
+    version: number;
+    digest: string;
+    file: string | null;
+    files: {
+        path: string;
+        digest: string;
+    }[];
+};
+/** One schedule a grant covers: which trigger, what sort, the digest of its settings when signed, and its name in words.
+ * `script` is there exactly when the kind is "script". */
+export type CoveredTrigger = {
+    id: number;
+    kind: "schedule" | "script" | "plane-review";
+    digest: string;
+    words: string;
+    script?: SignedScript;
+};
+export type UnattendedTerms = {
+    flow: number;
+    /** Saving the flow moves its revision: what was signed was this drawing. */
+    flowRevision: number;
+    repo: string;
+    /** The signer, who must stay the flow's owner. */
+    owner: string;
+    /** The schedules signed for, frozen: any other trigger, or one of these changed, is not covered. */
+    triggers: CoveredTrigger[];
+    /** Always safe: an escalated posture is never covered. */
+    permissions: "safe";
+    acceptance: {
+        report: AcceptanceCriterion[];
+        task: AcceptanceCriterion[];
+    };
+    perAttemptBudgetMicrousd: number | null;
+    /** Filings per UTC day, reserved at filing. */
+    dailyRunCap: number | null;
+    absoluteExpiry: string;
+};
+export declare const unattendedTermsJson: (terms: UnattendedTerms) => string;
+/** sha256 over a domain-separated canonical encoding, 32 hex like the mode digest. */
+export declare function unattendedDigestOf(terms: UnattendedTerms): string;
+/** Strict rehydration: anything unexpected is null, never a guess. */
+export declare function unattendedTermsFromJson(json: string | null): UnattendedTerms | null;
+export { untilWords };
+/** Every term in words: what the ceremony shows and the password signs. */
+export declare function unattendedWords(terms: UnattendedTerms): string[];
+export type UnattendedGrant = {
+    id: number;
+    flow: number;
+    repo: string;
+    terms: UnattendedTerms;
+    digest: string;
+    signedBy: string;
+    signedAt: string;
+    absoluteExpiry: string;
+};
+/** SQL: whether the grant whose digest is `digest` still stands at `now` for work in `repo` — live, unexpired, its
+ * signer an active approver who can still reach the flow's project and this one, still the owner of the very flow
+ * 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";
+/**
+ * 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
+ * grant the filter names ends now, durably, with its ledger line, and its queued approvals are withdrawn. Call inside
+ * the mutation's transaction. Returns how many ended.
+ */
+export declare function endUnattendedGrants(store: Store, filter: {
+    flow: number;
+} | {
+    repo: string;
+} | {
+    signer: string;
+} | {
+    script: {
+        repo: string;
+        name: string;
+    };
+}, by: string, reason: Exclude<UnattendedEnd, "expired" | "revoked" | "renewed">, now: Date): number;
+/** The live grant for a flow, or null. One past its expiry is closed here, durably (like activeMode). A grant whose
+ * signer is no longer an active approver, or whose flow moved on, covers nothing. */
+export declare function activeUnattendedGrant(store: Store, flowId: number, now: Date): UnattendedGrant | null;
+/** sha256 over a trigger's identity and canonical settings: what a grant freezes for each schedule it covers. */
+export declare function triggerDigestOf(trigger: Pick<FlowTriggerRow, "id" | "flow" | "kind" | "configJson">): string | null;
+/** Asynchronous preparation, never called from filing transactions or page rendering. */
+export declare function scriptProvenanceOf(store: Store, repo: string, name: string, fresh?: boolean): Promise<SignedScript | null>;
+export declare function prepareUnattendedCandidates(store: Store, flowId: number): Promise<void>;
+/** What an on-time script firing ran, as its firing records it: a digest of the code pinned just before and just after
+ * the run, when both were the same and were the script row that ran; else null (it can't have run the code signed). */
+export declare function scriptRanDigestOf(before: SignedScript | null, after: SignedScript | null, ran: {
+    version: number;
+    digest: string;
+}): string | null;
+/** Whether `flowId`'s live grant signed `triggerId`'s script: only then does a firing pin the code it runs. */
+export declare function grantSignsScriptOf(store: Store, flowId: number, triggerId: number, now: Date): boolean;
+/** A schedule a grant could cover, and whether it is covered only when the owner picks it (`optional`, with why). */
+export type UnattendedCandidate = CoveredTrigger & {
+    optional: string | null;
+};
+/**
+ * The flow's active schedules a grant could cover. A plain schedule makes its own card from its own words, so it is
+ * covered by default. A script's items and a plane review's problems are outside content (issues, mail, what a run
+ * saw), so they are covered only when the owner picks them. A standing order files under its own signed terms, and a
+ * paused or unreadable schedule, or a script whose code can't be read safely, is never offered.
+ */
+export declare function unattendedCandidates(store: Store, flowId: number): UnattendedCandidate[];
+/** A digest of the schedules the page offered, so a signature never covers one the person didn't read. */
+export declare const candidatesDigestOf: (candidates: readonly UnattendedCandidate[]) => string;
+/** Why `signer` can't let this flow run on its own, or null: what the flow page shows instead of the form. */
+export declare function unattendedSignProblem(store: Store, flow: FlowRow, signer: string): string | null;
+/** `include`: the schedules (trigger ids) the owner picked beyond the plain ones covered by default. */
+export type UnattendedAsk = {
+    days: number;
+    budgetMicrousd: number | null;
+    dailyRunCap: number | null;
+    include?: number[];
+};
+/** Read what a person typed: whole days 1–MODE_MAX_DAYS, an optional dollar budget, an optional runs-a-day cap. */
+export declare function parseUnattendedAsk(input: {
+    days: unknown;
+    budget?: unknown;
+    runs?: unknown;
+    include?: unknown;
+}): {
+    ok: true;
+    ask: UnattendedAsk;
+} | {
+    ok: false;
+    message: string;
+};
+/** The exact terms a signature would cover now, for these schedules. */
+export declare function unattendedTermsFor(flow: FlowRow, owner: string, ask: UnattendedAsk, triggers: readonly CoveredTrigger[], now: Date): UnattendedTerms;
+/** Sign (or renew) the grant. The caller has already checked the signer's password; every predicate is proved again
+ * here against the flow as it now stands: files asynchronously first, then database facts inside the transaction. `sawRevision` and `sawSchedules` (candidatesDigestOf),
+ * when given, are the flow and the schedules the person read. Renewing ends the old grant and withdraws what it sealed. */
+export declare function signUnattended(store: Store, input: {
+    flow: number;
+    signer: string;
+    ask: UnattendedAsk;
+    sawRevision?: number;
+    sawSchedules?: string;
+}, now: Date): Promise<{
+    ok: true;
+    grant: UnattendedGrant;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** One click for any approver on the project: lowering authority needs no password. False when there was none. */
+export declare function revokeUnattended(store: Store, flowId: number, by: string, now: Date): boolean;
+/**
+ * Whether a card came from one of the schedules this grant signed for, fired on time after it was signed: the firing
+ * names the card and was the clock's (never Run now), its trigger is still active with the very settings signed, and no
+ * person has moved the card or sent it back since. Anything else is a person's card, or one the grant never read.
+ * A script schedule's firing must have run the very code signed (scriptRanDigestOf), and it must still be that code;
+ * when it isn't, the grant ends here (unattendedCoverageFor).
+ */
+export declare function cardFromSignedSchedule(store: Store, grant: UnattendedGrant, cardId: number, requireScript?: boolean): boolean;
+/** How many runs a grant has filed on `now`'s UTC day. */
+export declare function unattendedRunsToday(store: Store, grantId: number, now: Date): number;
+/** Whether the grant covers this card's next filing (in `repo`) now; call inside the filing transaction. */
+export declare function unattendedCoverageFor(store: Store, flow: FlowRow, card: {
+    id: number;
+}, repo: string, now: Date): UnattendedGrant | null;
+/** Count one run against the grant's day, in one statement that admits it only under the cap (so two filings racing
+ * on two connections can't both take the last run). False when the day is full; then nothing is sealed. */
+export declare function reserveUnattendedRun(store: Store, grant: UnattendedGrant, taskId: string, now: Date): boolean;
+/** Give back a run reserved for a filing that then couldn't be sealed. */
+export declare function releaseUnattendedRun(store: Store, grant: UnattendedGrant, taskId: string): void;
+/** The grant that sealed (or pre-authorized) a task still stands for it: the same live digest, the flow unchanged and
+ * still owned by the signer, the signer able to approve in the task's project, its scripts' code unchanged (else it
+ * ends here), and the work not protected. */
+export declare function unattendedGrantStands(store: Store, digest: string, signer: string, taskRepo: string | null, touches: readonly string[], now: Date): boolean;
+/** The flow page's and CLI's view of the grant: the live state, and whether (and why not) this viewer can sign. */
+export type UnattendedView = {
+    active: {
+        until: string;
+        untilWords: string;
+        signedBy: string;
+        budgetMicrousd: number | null;
+        dailyRunCap: number | null;
+        runsToday: number;
+        words: string[];
+        covers: string[];
+    } | null;
+    canSign: boolean;
+    problem: string | null;
+    maxDays: number;
+    /** Whether the flow has a schedule, the only thing a grant covers. */
+    scheduled: boolean;
+    /** What a signature covers besides the limits and schedules the form chooses (unattendedLimitWords, unattendedCoverWords,
+     * unattendedEndAfterWords). */
+    terms: {
+        head: string[];
+        rules: string[];
+    };
+    /** The schedules it could cover (optional ones only when picked), and their digest, which the form sends back. */
+    schedules: {
+        id: number;
+        words: string;
+        optional: string | null;
+    }[];
+    schedulesDigest: string;
+};
+export declare function unattendedViewOf(store: Store, flow: FlowRow, viewer: {
+    name: string;
+    approver: boolean;
+}, now: Date): UnattendedView;