toolroll 0.9.62 → 0.9.63

package/dist/store.d.ts

@@ -110,6 +110,10 @@ export declare const LEAD_FOLLOW_MESSAGE = "Automatic crew update: inspect the s
  * nothing set up, such as no `gh` sign-in). `ok_at` and `error`/`error_at` keep the last success and the last
  * failure across checks, so a row can say both. `account` is a display name only, never a credential. */
 export declare const INTEGRATIONS_SCHEMA = "\nCREATE TABLE IF NOT EXISTS integration_check (\n  key         TEXT PRIMARY KEY,\n  outcome     TEXT NOT NULL CHECK (outcome IN ('ok', 'failed', 'absent')),\n  account     TEXT,\n  detail      TEXT,\n  problem     TEXT,\n  checked_at  TEXT NOT NULL,\n  ok_at       TEXT,\n  error       TEXT,\n  error_at    TEXT\n);\n";
+/** Tool secrets (no version bump): which sealing key Toolroll made for the secrets it keeps in the keychain, as a
+ * digest of the key, never the key. A key found beside them that isn't this one was put there by something else and is
+ * refused (tool-secret-store.ts). */
+export declare const TOOL_SECRET_KEY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS tool_secret_key (\n  id      INTEGER PRIMARY KEY CHECK (id = 1),\n  digest  TEXT NOT NULL CHECK (length(digest) = 64),\n  made_at TEXT NOT NULL\n);\n-- Where secrets were kept before Toolroll's folder, decided once at this database's first start (null: none) and never\n-- probed again, so a folder a build makes later under an old name is never migrated in.\nCREATE TABLE IF NOT EXISTS tool_secret_legacy (\n  id         INTEGER PRIMARY KEY CHECK (id = 1),\n  dir        TEXT,\n  decided_at TEXT NOT NULL\n);\n";
 export type BackupSettings = {
     enabled: boolean;
     everyHours: number;
@@ -166,7 +170,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 122;
+export declare const SCHEMA_VERSION = 123;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
 /**
@@ -227,7 +231,8 @@ export declare const V115_DROPPED_TABLES: readonly string[];
  * three nullable task_steer columns (the running build's steering folder), checked the same way. v121 only adds
  * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way. v122 only adds a new
  * table (branch_base_move) and the nullable column in V122_ADDED_COLUMNS (a project's recorded remote), checked the
- * same way.
+ * same way. v123 only adds new tables (unattended flows, tool secrets) and the columns in V123_ADDED_COLUMNS ('mode',
+ * 0 or null), checked the same way.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
@@ -263,6 +268,13 @@ export declare const V122_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record
     definition: string;
     saved: string;
 }>>>>;
+/** v123: the columns it adds, with the value every row saved before it reads: which authority armed a plan's
+ * unchanged-plan approval (saved rows read the operating mode), whether a trigger's firing was the clock's own (saved
+ * firings read not), and what code an on-time script firing a grant signed for ran (saved firings read none). */
+export declare const V123_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
 export type OAuthClientRow = {
@@ -1770,6 +1782,18 @@ export declare class Store {
     /** The database's own file (null in memory): where the agent fence begins. */
     databaseFile(): string | null;
     close(): void;
+    /** The digest of the sealing key Toolroll made for its tool secrets; null before it made one (or in an older database). */
+    toolSecretKeyDigest(): string | null;
+    /**
+     * The folder secrets were kept in before Toolroll's own, as decided at this database's first start of a command that
+     * can start builds (`record`): `probe` runs until then, and its answer (null: none) is kept for every later start.
+     * Other commands never write, so a preview stays read-only and a busy database doesn't stop them.
+     */
+    toolSecretLegacyDir(probe: () => string | null, now: Date, options: {
+        record: boolean;
+    }): string | null;
+    /** Record a new sealing key's digest only if the one recorded is still `expected` (null: none yet). */
+    swapToolSecretKeyDigest(expected: string | null, next: string, now: Date): boolean;
     /**
      * Creating a task also creates its overlay reference, because a task with no
      * `TaskRef` cannot be claimed, held, or scheduled — it would be work the
@@ -2164,7 +2188,7 @@ export declare class Store {
      * exactly what the signed digest was bound to. Returns false when the
      * scope vanished mid-ceremony. */
     sealScopeApproval(taskId: string, by: string, now: Date, mutation?: Mutation, basis?: {
-        kind: "mode" | "chat";
+        kind: "mode" | "chat" | "grant";
         modeDigest: string;
     }, approverKind?: ApproverKind): boolean;
     /** Whether this task's scope carries a LIVE seal: approved, and the
@@ -2219,6 +2243,10 @@ export declare class Store {
      * ceremony. Reconciliation drops mode-basis intents to waiting-human;
      * `firing` rows are untouched — an issued call is one-shot (E1). */
     revokeMode(repo: string, by: string, reason: string, now: Date): boolean;
+    /** A flow's "runs on its own" grant ended (revoked, expired, renewed): the undispatched work it sealed falls back
+     * to a person, as a mode's does, and plans it armed lose their pre-authorization. Running and finished work keeps
+     * its history. */
+    withdrawGrantApprovals(digest: string, now: Date): void;
     /** F2/R-REVOKE: the ONE reconciliation road. newMode null = no live
      * automerge authority (revocation, expiry, or a notify posture):
      * mode-basis pending/claimed intents drop to waiting-human, leases
@@ -4412,6 +4440,10 @@ export declare class Store {
      * other class is observational.
      */
     stampTerminalClass(id: number, authMode: "subscription" | "api-key", terminalClass: TerminalClass): void;
+    /** A launch refused before any model turn (an installed CLI too old for a
+     * build's flags): the start stamp goes, its version and evidence stay. Only
+     * while the run is open, so a settled run's account never changes. */
+    withdrawProviderStart(id: number): void;
     /** The race-refusal stamp (Phase 3 C5): the version that was REFUSED,
      * recorded without provider_started_at — no provider process started. */
     stampProviderVersion(id: number, providerVersion: string): void;
@@ -5684,7 +5716,7 @@ export declare class Store {
     }, now: Date): number;
     /** A person approves a held script (one an imported flow brought): from now on it runs. False when it wasn't held. */
     approveFlowScript(repo: string, name: string): boolean;
-    removeFlowScript(repo: string, name: string): boolean;
+    removeFlowScript(repo: string, name: string, by?: string, now?: Date): boolean;
     /** Claim a card's visit to a step zone. False when another pass holds it or it already finished. */
     claimFlowStep(step: {
         card: number;
@@ -5764,7 +5796,7 @@ export declare class Store {
         lastOutcome?: string;
         failures?: number;
         hookHash?: string | null;
-    }, now: Date): void;
+    }, now: Date, by?: string): void;
     /** Whether a trigger already handled this outside thing (an issue, a run, a schedule slot). */
     flowTriggerSaw(trigger: number, key: string): boolean;
     /** The card one outside thing made (v89: a chat message, so replies in its thread find it). */
@@ -5775,7 +5807,7 @@ export declare class Store {
      * Record what a trigger did with one outside thing: the card it made, or why it made none, and (a standing order's
      * firing) the task it filed. False when it was already recorded.
      */
-    recordFlowTriggerEvent(trigger: number, key: string, card: number | null, note: string | null, now: Date, task?: string | null): boolean;
+    recordFlowTriggerEvent(trigger: number, key: string, card: number | null, note: string | null, now: Date, task?: string | null, onTime?: boolean, ranScript?: string | null): boolean;
     /** The last card a trigger made, if any. */
     lastFlowTriggerCard(trigger: number): number | null;
     /**

package/dist/store.js

@@ -74,9 +74,10 @@ import { isProviderId } from "./provider.js";
 import { authenticate as runnerAuthenticate } from "./runner.js";
 import { stampNewProjectLevel } from "./check-levels.js";
 import { parseCheckProgressSnapshot } from "./check-progress.js";
-import { normalizeProjectAccess, projectAccessAllows, readProjectAccess } from "./project-access.js";
+import { accountReachesSql, normalizeProjectAccess, projectAccessAllows, readProjectAccess } from "./project-access.js";
 import { LEDGER_COLUMNS, LEDGER_SCHEMA, LEDGER_TABLE, LEDGER_V99_TABLE, installLedgerTriggers } from "./action-ledger.js";
 import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
+import { endUnattendedGrants, FLOW_UNATTENDED_SCHEMA, grantStandsSql } from "./flow-unattended.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
 import { PROVIDER_AUTH_SCHEMA } from "./provider-auth.js";
@@ -475,6 +476,23 @@ CREATE TABLE IF NOT EXISTS integration_check (
   error_at    TEXT
 );
 `;
+/** Tool secrets (no version bump): which sealing key Toolroll made for the secrets it keeps in the keychain, as a
+ * digest of the key, never the key. A key found beside them that isn't this one was put there by something else and is
+ * refused (tool-secret-store.ts). */
+export const TOOL_SECRET_KEY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS tool_secret_key (
+  id      INTEGER PRIMARY KEY CHECK (id = 1),
+  digest  TEXT NOT NULL CHECK (length(digest) = 64),
+  made_at TEXT NOT NULL
+);
+-- Where secrets were kept before Toolroll's folder, decided once at this database's first start (null: none) and never
+-- probed again, so a folder a build makes later under an old name is never migrated in.
+CREATE TABLE IF NOT EXISTS tool_secret_legacy (
+  id         INTEGER PRIMARY KEY CHECK (id = 1),
+  dir        TEXT,
+  decided_at TEXT NOT NULL
+);
+`;
 /** Sprint 8: database backups. One settings row (off, or every so many hours, keeping the newest N in a folder; no
  * folder means `backups` beside the database), every backup's outcome, and a lease the console's backup loop holds
  * and renews while it runs: one process backs up at a time, and a restore sees that the console is running. */
@@ -624,7 +642,10 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v122 adds, and changes no saved row: the remote URL an owner's project add recorded (project.remote_url), the only
 // remote whose main automatic completion trusts (remote-main.ts; saved projects read none until it is recorded), and
 // fresh base's record of a task branch moved to current main before an attempt (branch_base_move).
-export const SCHEMA_VERSION = 122;
+// v123 adds, and changes no saved row: flows that run on their own (flow_script_provenance, flow_unattended_grant,
+// flow_unattended_run, plan_authorization.basis, flow_trigger_event.on_time and ran_script) and the tool-secret
+// sealing key's record (tool_secret_key, tool_secret_legacy).
+export const SCHEMA_VERSION = 123;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export const V118_MERGED_TABLES = Object.freeze({ api_token: "person", coordinator_credential: "coordinator", lead_credential: "lead" });
 /** The foreign keys that named a merged table, exactly as their DDL wrote them; each names `credential(id)` instead. */
@@ -751,9 +772,10 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * three nullable task_steer columns (the running build's steering folder), checked the same way. v121 only adds
  * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way. v122 only adds a new
  * table (branch_base_move) and the nullable column in V122_ADDED_COLUMNS (a project's recorded remote), checked the
- * same way.
+ * same way. v123 only adds new tables (unattended flows, tool secrets) and the columns in V123_ADDED_COLUMNS ('mode',
+ * 0 or null), checked the same way.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123]);
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
 export const V119_ADDED_COLUMNS = Object.freeze({
     task_ref: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
@@ -804,6 +826,16 @@ export const V121_ADDED_COLUMNS = Object.freeze({
 export const V122_ADDED_COLUMNS = Object.freeze({
     project: { remote_url: { definition: "TEXT", saved: "NULL" } },
 });
+/** v123: the columns it adds, with the value every row saved before it reads: which authority armed a plan's
+ * unchanged-plan approval (saved rows read the operating mode), whether a trigger's firing was the clock's own (saved
+ * firings read not), and what code an on-time script firing a grant signed for ran (saved firings read none). */
+export const V123_ADDED_COLUMNS = Object.freeze({
+    plan_authorization: { basis: { definition: "TEXT NOT NULL DEFAULT 'mode' CHECK (basis IN ('mode', 'grant'))", saved: "'mode'" } },
+    flow_trigger_event: {
+        on_time: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" },
+        ran_script: { definition: "TEXT", saved: "NULL" },
+    },
+});
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export function updateSafeSchema(version) {
     if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
@@ -3527,6 +3559,8 @@ function initializeStore(db, file) {
     db.exec(LEDGER_CHAIN_SCHEMA);
     db.exec(MONITORING_SCHEMA);
     db.exec(INTEGRATIONS_SCHEMA);
+    // v123: the tool-secret sealing key's record and where secrets were kept before (tool-secret-store.ts): new tables.
+    db.exec(TOOL_SECRET_KEY_SCHEMA);
     db.exec(LEAD_ASK_SCHEMA);
     // Decisions in the chat app (no version bump: additive only): result, plan and merge buttons, and Request changes.
     db.exec(CHAT_DECIDE_SCHEMA);
@@ -3613,6 +3647,16 @@ function initializeStore(db, file) {
     // v115: the task each standing-order firing filed, kept on the firing itself (a card's task changes as it moves).
     addColumn(db, "flow_trigger_event", "task", "TEXT");
     db.exec(PLAN_AUTO_SCHEMA);
+    // v123: a flow that runs on its own (flow-unattended.ts): its grants and daily runs (new tables), and which authority
+    // armed a plan's unchanged-plan approval (plan_authorization.basis, V123_ADDED_COLUMNS: saved rows read the mode).
+    db.exec(FLOW_UNATTENDED_SCHEMA);
+    // v123: whether a trigger's firing was the clock's own (flow_trigger_event.on_time, V123_ADDED_COLUMNS: a schedule
+    // due, not Run now; only those can run on their own), and what code an on-time script firing a grant signed for ran
+    // (flow_trigger_event.ran_script, V123_ADDED_COLUMNS: flow-unattended.ts scriptRanDigestOf; older firings read null).
+    for (const [table, columns] of Object.entries(V123_ADDED_COLUMNS)) {
+        for (const [column, { definition }] of Object.entries(columns))
+            addColumn(db, table, column, definition);
+    }
     // v119: planning generations, and why a question closed unanswered (additive only; saved rows read the defaults).
     for (const [table, columns] of Object.entries(V119_ADDED_COLUMNS)) {
         for (const [column, { definition }] of Object.entries(columns))
@@ -4818,6 +4862,36 @@ export class Store {
     close() {
         this.db.close();
     }
+    /** The digest of the sealing key Toolroll made for its tool secrets; null before it made one (or in an older database). */
+    toolSecretKeyDigest() {
+        if (!tableExists(this.db, "tool_secret_key"))
+            return null;
+        const row = this.db.prepare("SELECT digest FROM tool_secret_key WHERE id = 1").get();
+        return row === undefined ? null : String(row["digest"]);
+    }
+    /**
+     * The folder secrets were kept in before Toolroll's own, as decided at this database's first start of a command that
+     * can start builds (`record`): `probe` runs until then, and its answer (null: none) is kept for every later start.
+     * Other commands never write, so a preview stays read-only and a busy database doesn't stop them.
+     */
+    toolSecretLegacyDir(probe, now, options) {
+        const read = () => tableExists(this.db, "tool_secret_legacy") ? this.db.prepare("SELECT dir FROM tool_secret_legacy WHERE id = 1").get() : undefined;
+        let row = read();
+        if (row === undefined) {
+            if (!options.record)
+                return probe();
+            this.db.prepare("INSERT OR IGNORE INTO tool_secret_legacy (id, dir, decided_at) VALUES (1, ?, ?)").run(probe(), now.toISOString());
+            row = read();
+        }
+        return row?.["dir"] === null || row?.["dir"] === undefined ? null : String(row["dir"]);
+    }
+    /** Record a new sealing key's digest only if the one recorded is still `expected` (null: none yet). */
+    swapToolSecretKeyDigest(expected, next, now) {
+        const changed = expected === null
+            ? this.db.prepare("INSERT OR IGNORE INTO tool_secret_key (id, digest, made_at) VALUES (1, ?, ?)").run(next, now.toISOString()).changes
+            : this.db.prepare("UPDATE tool_secret_key SET digest = ?, made_at = ? WHERE id = 1 AND digest = ?").run(next, now.toISOString(), expected).changes;
+        return Number(changed) === 1;
+    }
     // ---- the built-in task store -------------------------------------------
     /**
      * Creating a task also creates its overlay reference, because a task with no
@@ -6344,7 +6418,9 @@ export class Store {
                                 ? `Approved by ${currentActor()?.lead === true ? "the lead" : lifecycleWords(by, 40)}. A connected worker can take it next.`
                                 : basis.kind === "chat"
                                     ? `Approved by ${lifecycleWords(by, 40)} in chat. A connected worker can take it next.`
-                                    : "Approved automatically under the operating mode. A connected worker can take it next.",
+                                    : basis.kind === "grant"
+                                        ? "Approved automatically: its flow runs on its own. A connected worker can take it next."
+                                        : "Approved automatically under the operating mode. A connected worker can take it next.",
                             link: chatControlHref("task", taskId),
                         }, now);
                     }
@@ -6375,16 +6451,19 @@ export class Store {
      * scopes answer true: this belt only ever REMOVES mode authority.
      */
     modeApprovalLive(taskRef, now) {
+        // A flow's "runs on its own" grant (flow-unattended.ts) is held to the same belt.
         const dead = this.db
             .prepare(`SELECT 1 AS dead FROM task_scope
           JOIN task_ref ON task_ref.id = ? AND task_ref.backend = 'built-in' AND task_scope.task_id = task_ref.external_id
-         WHERE task_scope.approval_basis = 'mode' AND task_scope.approved_at IS NOT NULL
+         WHERE task_scope.approved_at IS NOT NULL
+           AND ((task_scope.approval_basis = 'mode'
            AND NOT EXISTS (SELECT 1 FROM operating_mode om
                             JOIN approver signer ON signer.name = om.signed_by
                            WHERE om.repo = task_ref.repo AND om.revoked_at IS NULL
                              AND om.absolute_expiry > ? AND om.digest = task_scope.mode_digest
-                             AND signer.revoked_at IS NULL AND signer.role = 'approver')`)
-            .get(taskRef, now.toISOString());
+                             AND signer.revoked_at IS NULL AND signer.role = 'approver' AND ${accountReachesSql("signer", "task_ref.repo")}))
+             OR (task_scope.approval_basis = 'grant' AND NOT ${grantStandsSql("task_scope.mode_digest", "?", "task_ref.repo")}))`)
+            .get(taskRef, now.toISOString(), now.toISOString());
         return dead === undefined;
     }
     // ---- approvers ----------------------------------------------------------
@@ -6511,6 +6590,29 @@ export class Store {
             return true;
         });
     }
+    /** A flow's "runs on its own" grant ended (revoked, expired, renewed): the undispatched work it sealed falls back
+     * to a person, as a mode's does, and plans it armed lose their pre-authorization. Running and finished work keeps
+     * its history. */
+    withdrawGrantApprovals(digest, now) {
+        const demotable = `WHERE approval_basis = 'grant' AND approved_at IS NOT NULL AND mode_digest = ?
+            AND EXISTS (SELECT 1 FROM task_ref JOIN task ON task.id = task_ref.external_id
+                         WHERE task_ref.backend = 'built-in' AND task_ref.external_id = task_scope.task_id AND task.state = 'queued')
+            AND NOT EXISTS (SELECT 1 FROM claim JOIN task_ref tr ON tr.id = claim.task_ref
+                             WHERE tr.backend = 'built-in' AND tr.external_id = task_scope.task_id
+                               AND claim.released_at IS NULL AND claim.expires_at > ?)`;
+        const demoted = this.db.prepare(`SELECT task_id FROM task_scope ${demotable}`).all(digest, now.toISOString()).map(row => String(row["task_id"]));
+        this.db
+            .prepare(`UPDATE task_scope SET approved_at = NULL, approved_by = NULL, approved_digest = NULL,
+                approved_profile_json = NULL, approval_basis = 'password', mode_digest = NULL ${demotable}`)
+            .run(digest, now.toISOString());
+        this.db.prepare("DELETE FROM plan_authorization WHERE basis = 'grant' AND mode_digest = ?").run(digest);
+        for (const taskId of demoted) {
+            const ref = this.lookupRef(taskId);
+            if (ref === null)
+                continue;
+            this.noteLifecycle({ taskRef: ref.id, kind: "approval-withdrawn", identity: `t${ref.id}`, subject: "Approval needs renewing", body: "Its flow no longer runs on its own. Approve it before it runs.", link: chatControlHref("approval", taskId) }, now);
+        }
+    }
     /** F2/R-REVOKE: the ONE reconciliation road. newMode null = no live
      * automerge authority (revocation, expiry, or a notify posture):
      * mode-basis pending/claimed intents drop to waiting-human, leases
@@ -6735,6 +6837,7 @@ export class Store {
             for (const row of this.db.prepare("SELECT repo FROM operating_mode WHERE signed_by = ? AND revoked_at IS NULL").all(name)) {
                 this.revokeMode(String(row["repo"]), by, "operator", now);
             }
+            endUnattendedGrants(this, { signer: name }, by, "access changed", now);
             this.revokeDerivedAuthority(name, by, now);
             for (const repo of [...new Set([...(account.projects ?? []), ...(access ?? [])])]) {
                 this.recordAction({ at: now.toISOString(), actor: by, repo, taskId: null, runId: null,
@@ -6762,6 +6865,10 @@ export class Store {
         ON CONFLICT(repo) DO UPDATE SET not_requester = excluded.not_requester, protect_project = excluded.protect_project, protected_paths = excluded.protected_paths, updated_by = excluded.updated_by, updated_at = excluded.updated_at`)
                 .run(repo, next.notRequester ? 1 : 0, next.protectProject ? 1 : 0, JSON.stringify(next.protectedPaths), by, now.toISOString());
             this.recordPolicy(by, repo, "approval rules changed", rulesWords(before), rulesWords(next), now);
+            // Protected work is always a person's: a flow here (or building here) stops running on its own, and its queued
+            // approvals are withdrawn (flow-unattended.ts). The dispatch belts check the rules again for any race.
+            if (isProtectedWork(next, []))
+                endUnattendedGrants(this, { repo }, by, "project protected", now);
         });
     }
     /** Who filed a task, when anyone knows. */
@@ -12325,6 +12432,12 @@ export class Store {
             .prepare("UPDATE run SET auth_mode = COALESCE(auth_mode, ?), terminal_class = ? WHERE id = ? AND terminal_class IS NULL")
             .run(authMode, terminalClass, id);
     }
+    /** A launch refused before any model turn (an installed CLI too old for a
+     * build's flags): the start stamp goes, its version and evidence stay. Only
+     * while the run is open, so a settled run's account never changes. */
+    withdrawProviderStart(id) {
+        this.db.prepare("UPDATE run SET provider_started_at = NULL WHERE id = ? AND outcome IS NULL").run(id);
+    }
     /** The race-refusal stamp (Phase 3 C5): the version that was REFUSED,
      * recorded without provider_started_at — no provider process started. */
     stampProviderVersion(id, providerVersion) {
@@ -14928,6 +15041,8 @@ export class Store {
             const version = (current?.version ?? Number(this.db.prepare("SELECT COALESCE(MAX(version), 0) AS v FROM flow_script WHERE repo = ? AND name = ?").get(script.repo, script.name)?.["v"] ?? 0)) + 1;
             if (current !== null)
                 this.db.prepare("UPDATE flow_script SET state = 'removed' WHERE id = ?").run(current.id);
+            // A "runs on its own" grant signed this script's code: a new version ends it (flow-unattended.ts).
+            endUnattendedGrants(this, { script: { repo: script.repo, name: script.name } }, script.by, "script changed", now);
             this.db.prepare(`INSERT INTO flow_script (repo, name, about, body, timeout_minutes, version, digest, saved_by, saved_at, state, language, file, held)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)`).run(script.repo, script.name, script.about, script.body, script.timeoutMinutes, version, script.digest, script.by, now.toISOString(), script.language ?? "shell", script.file ?? null, script.held ?? null);
             return version;
@@ -14938,9 +15053,14 @@ export class Store {
         const { changes } = this.db.prepare("UPDATE flow_script SET held = NULL WHERE repo = ? AND name = ? AND state = 'active' AND held IS NOT NULL").run(repo, name);
         return Number(changes) === 1;
     }
-    removeFlowScript(repo, name) {
-        const { changes } = this.db.prepare("UPDATE flow_script SET state = 'removed' WHERE repo = ? AND name = ? AND state = 'active'").run(repo, name);
-        return Number(changes) === 1;
+    removeFlowScript(repo, name, by = "flow", now = new Date()) {
+        return this.transact(() => {
+            const { changes } = this.db.prepare("UPDATE flow_script SET state = 'removed' WHERE repo = ? AND name = ? AND state = 'active'").run(repo, name);
+            // A grant that signed this script's code covers nothing without it: it ends (flow-unattended.ts).
+            if (Number(changes) === 1)
+                endUnattendedGrants(this, { script: { repo, name } }, by, "script changed", now);
+            return Number(changes) === 1;
+        });
     }
     /** Claim a card's visit to a step zone. False when another pass holds it or it already finished. */
     claimFlowStep(step, now) {
@@ -15029,6 +15149,13 @@ export class Store {
     // ---- flow triggers (v82) -----------------------------------------------------
     addFlowTrigger(trigger, now) {
         const stamp = now.toISOString();
+        // A new schedule is one the flow's "runs on its own" grant never read: it ends (flow-unattended.ts).
+        if (trigger.kind === "schedule")
+            return this.transact(() => {
+                endUnattendedGrants(this, { flow: trigger.flow }, trigger.by, "schedule changed", now);
+                return Number(this.db.prepare("INSERT INTO flow_trigger (flow, kind, config_json, state, hook_hash, cursor, next_at, created_by, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)")
+                    .run(trigger.flow, trigger.kind, trigger.configJson, trigger.hookHash, trigger.cursor, trigger.nextAt, trigger.by, stamp, stamp).lastInsertRowid);
+            });
         return Number(this.db.prepare("INSERT INTO flow_trigger (flow, kind, config_json, state, hook_hash, cursor, next_at, created_by, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)")
             .run(trigger.flow, trigger.kind, trigger.configJson, trigger.hookHash, trigger.cursor, trigger.nextAt, trigger.by, stamp, stamp).lastInsertRowid);
     }
@@ -15049,11 +15176,17 @@ export class Store {
         const row = this.db.prepare("SELECT t.* FROM flow_trigger t JOIN flow f ON f.id = t.flow WHERE t.hook_hash = ? AND t.state = 'active' AND f.state = 'active'").get(hash);
         return row === undefined ? null : readFlowTriggerRow(row);
     }
-    updateFlowTrigger(id, change, now) {
+    updateFlowTrigger(id, change, now, by = "a person") {
         const trigger = this.getFlowTrigger(id);
         if (trigger === null)
             return;
-        this.db.prepare("UPDATE flow_trigger SET state = ?, cursor = ?, next_at = ?, last_at = ?, last_outcome = ?, failures = ?, hook_hash = ?, updated_at = ? WHERE id = ?").run(change.state ?? trigger.state, change.cursor === undefined ? trigger.cursor : change.cursor, change.nextAt === undefined ? trigger.nextAt : change.nextAt, change.lastAt ?? trigger.lastAt, change.lastOutcome ?? trigger.lastOutcome, change.failures ?? trigger.failures, change.hookHash === undefined ? trigger.hookHash : change.hookHash, now.toISOString(), id);
+        // Pausing, resuming or removing a schedule ends the flow's "runs on its own" grant (flow-unattended.ts).
+        const write = () => this.db.prepare("UPDATE flow_trigger SET state = ?, cursor = ?, next_at = ?, last_at = ?, last_outcome = ?, failures = ?, hook_hash = ?, updated_at = ? WHERE id = ?").run(change.state ?? trigger.state, change.cursor === undefined ? trigger.cursor : change.cursor, change.nextAt === undefined ? trigger.nextAt : change.nextAt, change.lastAt ?? trigger.lastAt, change.lastOutcome ?? trigger.lastOutcome, change.failures ?? trigger.failures, change.hookHash === undefined ? trigger.hookHash : change.hookHash, now.toISOString(), id);
+        if (trigger.kind !== "schedule" || change.state === undefined || change.state === trigger.state) {
+            write();
+            return;
+        }
+        this.transact(() => { endUnattendedGrants(this, { flow: trigger.flow }, by, "schedule changed", now); write(); });
     }
     /** Whether a trigger already handled this outside thing (an issue, a run, a schedule slot). */
     flowTriggerSaw(trigger, key) {
@@ -15074,8 +15207,8 @@ export class Store {
      * Record what a trigger did with one outside thing: the card it made, or why it made none, and (a standing order's
      * firing) the task it filed. False when it was already recorded.
      */
-    recordFlowTriggerEvent(trigger, key, card, note, now, task = null) {
-        const { changes } = this.db.prepare("INSERT OR IGNORE INTO flow_trigger_event (trigger, key, card, note, at, task) VALUES (?, ?, ?, ?, ?, ?)").run(trigger, key, card, note, now.toISOString(), task);
+    recordFlowTriggerEvent(trigger, key, card, note, now, task = null, onTime = false, ranScript = null) {
+        const { changes } = this.db.prepare("INSERT OR IGNORE INTO flow_trigger_event (trigger, key, card, note, at, task, on_time, ran_script) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(trigger, key, card, note, now.toISOString(), task, onTime ? 1 : 0, ranScript);
         return Number(changes) === 1;
     }
     /** The last card a trigger made, if any. */

package/dist/subagent-tools.d.ts

@@ -12,7 +12,7 @@ export type ToolLister = (spec: ToolSpec, values: Record<string, string>) => Pro
 export type ToolIo = {
     callTool?: ToolCaller;
     listTools?: ToolLister;
-    toolHome?: string;
+    toolHome?: string | undefined;
 };
 /** Actions whose names say they only read start as "do it"; everything else asks first until its manager says otherwise. */
 export declare const READ_VERB: RegExp;

package/dist/surface.js

@@ -116,8 +116,9 @@ const GUIDE_ROWS = [
     ...KNOWLEDGE_DESCRIPTORS.map(spec => ({ invocation: `knowledge ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text or source file for impact" }] } : {}) })),
     ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
     // Flow writes carry an approver's credential: an agent runs them only as the person asked, after showing the preview.
-    ...FLOWS_DESCRIPTORS.map(spec => ({ invocation: `flows ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags,
-        ...("positionals" in spec ? { positionals: spec.positionals.map(name => ({ name, required: true, meaning: name === "flow" ? "a flow id from flows list" : name === "card" ? "a card id from flows show" : "a trigger id from flows show, or for trigger add its settings as JSON, a JSON file, or -" })) } : {}) })),
+    // Letting a flow run on its own raises authority: the owner's own password ceremony, never an agent's act.
+    ...FLOWS_DESCRIPTORS.map(spec => ({ invocation: `flows ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags,
+        ...("positionals" in spec ? { positionals: spec.positionals.map(name => ({ name, required: true, meaning: name === "flow" ? "a flow id from flows list" : name === "card" ? "a card id from flows show" : name === "on|off" ? "on signs the grant, off revokes it" : "a trigger id from flows show, or for trigger add its settings as JSON, a JSON file, or -" })) } : {}) })),
     ...MODELS_DESCRIPTORS.map(spec => ({ invocation: `models ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "target", required: true, meaning: "the CLI to update, or on/off" }] } : {}) })),
     // ---- the queue (agent surface) ----
     { invocation: "status", synopsis: "running work, queued reasons, results to review, the latest release check and plan windows", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
@@ -411,6 +412,7 @@ const GUIDE_ROWS = [
     operator("up", "console + worker + browser, one command"),
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
+    { ...operatorRead("doctor", "check that Toolroll's service holds no key, token or password a build could read; names what it finds and the steps to fix it, never a value, and changes nothing"), flags: [jsonFlag] },
 ];
 /**
  * Whether each row may run on a central server for a person signed in with their own API token (`runOperateAs` in
@@ -429,7 +431,7 @@ const REMOTE_NO = [
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "worker release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
-    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
+    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "doctor", "bridge", "setup show", "setup clear",
     // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
     // Publication and release.
@@ -443,7 +445,7 @@ const REMOTE_NO = [
 ];
 const REMOTE_STEP_UP = [
     "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "knowledge apply", "memory apply",
-    "flows card approve", "flows card send-back", "flows script approve",
+    "flows card approve", "flows card send-back", "flows script approve", "flows unattended",
     "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
     // A person's own API tokens: a password step-up on the server's machine, or the console. Never with a token.
     "tokens create", "tokens list", "tokens revoke", "tokens rotate",

package/dist/teardown-git.d.ts

@@ -0,0 +1,14 @@
+import { type ExecResult } from "./exec.js";
+import { type Runner } from "./worktree.js";
+export type Git = (cwd: string, args: readonly string[]) => Promise<ExecResult>;
+/** Fixed on every teardown command, ahead of its own arguments. */
+export declare const TEARDOWN_FLAGS: readonly string[];
+/** Exit code of a refused command (git's own fatal code, so no caller reads it as "not found" or "no"). */
+export declare const REFUSED_CODE = 128;
+/** The command-running setting a `git config --list --show-scope -z` listing sets, or null. Only local and worktree
+ * scope count: teardown commands never read system or global config. */
+export declare function commandSetting(listing: string): string | null;
+/** Why a teardown command was refused, or null when `result` isn't a refusal. */
+export declare function refusal(result: ExecResult): string | null;
+/** The one way teardown runs git, including the target checkout immediately before removal. */
+export declare function teardownGit(runner?: Runner): Git;

package/dist/teardown-git.js

@@ -0,0 +1,119 @@
+/**
+ * Git for teardown (landed-cleanup.ts and the checkout removal it drives in worktree.ts), run by Toolroll's own
+ * process inside the shared repository a build can write to. A build can plant hooks in .git/hooks and settings in
+ * .git/config (or a worktree's config.worktree), so every teardown command runs hardened: an allowlisted environment
+ * with no system or global config (remote-main.ts's), no hooks, no fsmonitor, no ext transport, no prompts and no
+ * automatic maintenance.
+ *
+ * Settings that name a command, and includes (which could bring them in from a file nobody looked at), are not
+ * overridden but refused: before each command the repository's own config is read with includes off, and if it sets
+ * any of them the command never runs. The refusal is a failed git result, so every caller's existing doubt applies and
+ * nothing is removed.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { run } from "./exec.js";
+import { ENV, ENV_ALLOWLIST } from "./remote-main.js";
+import { WORKTREE_TIMEOUT_MS } from "./worktree.js";
+/** Fixed on every teardown command, ahead of its own arguments. */
+export const TEARDOWN_FLAGS = [
+    "--no-optional-locks", "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "protocol.ext.allow=never",
+    "-c", "credential.helper=", "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "submodule.recurse=false",
+];
+/** Exit code of a refused command (git's own fatal code, so no caller reads it as "not found" or "no"). */
+export const REFUSED_CODE = 128;
+const REFUSED_PREFIX = "Toolroll won't run git here: ";
+/** Config keys that run a command, bring in unread config, or redirect inspection away from the checked path.
+ * `*` is one subsection, any name. */
+const COMMAND_KEYS = [
+    "core.sshcommand", "core.gitproxy", "core.askpass", "core.pager", "core.editor", "core.alternaterefscommand",
+    "core.worktree", "gpg.ssh.defaultkeycommand", "trailer.*.command", "trailer.*.cmd", "submodule.*.update", "sequence.editor", "diff.external", "credential.helper", "credential.*.helper", "filter.*.clean", "filter.*.smudge", "filter.*.process",
+    "diff.*.command", "diff.*.textconv", "merge.*.driver", "gpg.program", "gpg.*.program", "uploadpack.packobjectshook",
+    "remote.*.uploadpack", "remote.*.receivepack", "remote.*.vcs", "pager.*", "include.path", "includeif.*.path",
+].map(key => new RegExp(`^${key.replace(/\./g, "\\.").replace(/\*/g, ".+")}$`));
+/** core.fsmonitor as a boolean is git's own daemon; anything else is a command to run. */
+const BOOLEAN = /^(|true|false|yes|no|on|off|-?\d+)$/i;
+/** The command-running setting a `git config --list --show-scope -z` listing sets, or null. Only local and worktree
+ * scope count: teardown commands never read system or global config. */
+export function commandSetting(listing) {
+    const fields = listing.split("\0");
+    for (let at = 0; at + 1 < fields.length; at += 2) {
+        const scope = fields[at];
+        const entry = fields[at + 1];
+        if (scope !== "local" && scope !== "worktree")
+            continue;
+        const newline = entry.indexOf("\n");
+        const key = (newline < 0 ? entry : entry.slice(0, newline)).toLowerCase();
+        const value = newline < 0 ? "" : entry.slice(newline + 1);
+        if (key === "core.fsmonitor" ? !BOOLEAN.test(value.trim()) : COMMAND_KEYS.some(pattern => pattern.test(key)))
+            return key;
+    }
+    return null;
+}
+/** Why a teardown command was refused, or null when `result` isn't a refusal. */
+export function refusal(result) {
+    return result.code === REFUSED_CODE && result.stderr.startsWith(REFUSED_PREFIX) ? result.stderr.slice(REFUSED_PREFIX.length).trim() : null;
+}
+const refused = (why) => ({ code: REFUSED_CODE, stdout: "", stderr: `${REFUSED_PREFIX}${why}\n`, timedOut: false, notFound: false });
+/** Refuse nested repositories without asking Git to enter them or evaluate their config.
+ * Includes ignored/untracked repositories and bare repositories; never follows symlinks. */
+function nestedRepository(path) {
+    const pending = [path];
+    while (pending.length > 0) {
+        const dir = pending.pop();
+        const entries = readdirSync(dir, { withFileTypes: true });
+        if (dir !== path && (entries.some(entry => entry.name === ".git") ||
+            ["HEAD", "objects", "config"].every(name => entries.some(entry => entry.name === name))))
+            return true;
+        for (const entry of entries)
+            if (entry.isDirectory() && entry.name !== ".git")
+                pending.push(join(dir, entry.name));
+    }
+    return false;
+}
+/** The one way teardown runs git, including the target checkout immediately before removal. */
+export function teardownGit(runner = run) {
+    const options = (cwd) => ({ cwd, envAllowlist: ENV_ALLOWLIST, env: ENV, timeoutMs: WORKTREE_TIMEOUT_MS, maxBuffer: 512 * 1024 * 1024 });
+    const configProblem = async (cwd) => {
+        const config = await runner("git", ["--no-optional-locks", "config", "--list", "--no-includes", "--show-scope", "-z"], options(cwd));
+        if (config.code !== 0)
+            return refused("its config couldn't be read");
+        const key = commandSetting(config.stdout);
+        return key === null ? null : refused(`the project's git config sets ${key}, which can run a command`);
+    };
+    return async (cwd, args) => {
+        const problem = await configProblem(cwd);
+        if (problem !== null)
+            return problem;
+        const removal = args[0] === "worktree" && args[1] === "remove";
+        const inspection = args.includes("status") || args.includes("diff");
+        const target = removal ? resolve(cwd, args.at(-1)) : cwd;
+        if (removal) {
+            const targetProblem = await configProblem(target);
+            if (targetProblem !== null)
+                return targetProblem;
+        }
+        if (removal || inspection || args.includes("checkout") || args.includes("clean")) {
+            try {
+                if (existsSync(target) && nestedRepository(target))
+                    return refused("the checkout contains a nested repository");
+            }
+            catch {
+                return refused("the checkout couldn't be inspected for nested repositories");
+            }
+            // ls-files reads index entries only; it cannot run submodule filters. Even an uninitialized
+            // gitlink is kept, so worktree remove's internal status can never traverse it.
+            const index = await runner("git", [...TEARDOWN_FLAGS, "ls-files", "--stage", "-z"], options(target));
+            if (index.code !== 0)
+                return refused("the checkout's index couldn't be read");
+            if (index.stdout.split("\0").some(entry => entry.startsWith("160000 ")))
+                return refused("the checkout contains a gitlink");
+        }
+        const safeArgs = [...args];
+        if (inspection && !safeArgs.includes("--ignore-submodules=all")) {
+            const command = safeArgs.findIndex(arg => arg === "status" || arg === "diff");
+            safeArgs.splice(command + 1, 0, "--ignore-submodules=all");
+        }
+        return runner("git", [...TEARDOWN_FLAGS, ...safeArgs], options(cwd));
+    };
+}