toolroll 0.7.0 → 0.8.0

package/dist/browser-shell.js

@@ -54,7 +54,9 @@ export function browserWorkspaceDocument(html, workspace, nonce, functionalScrip
     const settleFades = `(function(){function s(e){var f=e.viewTransition;if(f)[f.finished,f.ready,f.updateCallbackDone].forEach(function(p){if(p)p.catch(function(){})})}addEventListener('pageswap',s);addEventListener('pagereveal',s)})();`;
     return html
         // A page showing a password keeps to its one script (the sensitivity contract), so it goes without.
-        .replace('</head>', `<link rel="stylesheet" href="/assets/workspace.css">${workspace.sensitive ? "" : `<script nonce="${nonce}">${settleFades}</script>`}</head>`)
-        .replace('<body>', '<body><div id="standing-orders-workspace">')
-        .replace('</body>', `</div><script type="application/json" id="standing-orders-workspace-data" nonce="${nonce}">${serializeBrowserWorkspace(workspace)}</script><script nonce="${nonce}">${initialize}</script><script type="module" src="/assets/workspace.js" nonce="${nonce}"></script></body>`);
+        // Replacer functions, never strings: a `$\`` or `$'` in the page's data (an issue title, a TODO) would
+        // otherwise paste part of the page into the data block and close it early.
+        .replace('</head>', () => `<link rel="stylesheet" href="/assets/workspace.css">${workspace.sensitive ? "" : `<script nonce="${nonce}">${settleFades}</script>`}</head>`)
+        .replace('<body>', () => '<body><div id="standing-orders-workspace">')
+        .replace('</body>', () => `</div><script type="application/json" id="standing-orders-workspace-data" nonce="${nonce}">${serializeBrowserWorkspace(workspace)}</script><script nonce="${nonce}">${initialize}</script><script type="module" src="/assets/workspace.js" nonce="${nonce}"></script></body>`);
 }

package/dist/browser-workspace.d.ts

@@ -8,6 +8,7 @@ import type { Store } from './store.js';
 import type { WorkSummaryAccess } from './work-summary.js';
 import type { StatusTone } from './workspace-ui.js';
 import type { AssignmentCard } from './assignment-ui.js';
+import type { FirstRunStep, FirstTaskSuggestion } from './first-run.js';
 export type BrowserProject = {
     name: string;
     path: string;
@@ -241,6 +242,8 @@ export type BrowserSettingsView = {
             redirect: string | null;
         };
     } | null;
+    /** The installation's first Ready result, in words ("first result in 7 min"); null before it arrives. */
+    firstResult?: string | null;
     /** Settings → Updates: this version, the latest known one and its notes, how to update, the daily-check switch, and each worker's version. */
     updates?: BrowserUpdates | null;
 };
@@ -783,6 +786,14 @@ export type BrowserWorkspace = {
     signIn?: BrowserSignIn[];
     /** A newer Toolroll exists: a quiet notice for an operator, until they dismiss this version. */
     update?: BrowserUpdateNotice;
+    /** Chat's first run, until the first Ready result: the three steps and first tasks to try. */
+    firstRun?: BrowserFirstRun;
+};
+/** `sandbox`: the demo command, offered beside the sign-in command while no agent is signed in. */
+export type BrowserFirstRun = {
+    steps: FirstRunStep[];
+    suggestions: FirstTaskSuggestion[];
+    sandbox: string | null;
 };
 /** The console's update notice: neutral, never the accent — an update does not need a person. */
 export type BrowserUpdateNotice = {

package/dist/cli.d.ts

@@ -13,6 +13,7 @@
 import { previewGithubRepo, cloneGithubRepo } from "./onboard.js";
 import { type SessionCliOptions } from "./session-cli.js";
 import { type TeamCliOptions } from "./team-cli.js";
+import { type UpdateCliDeps } from "./toolroll-update-cli.js";
 import { type OperateOptions } from "./operate.js";
 export type CliOptions = {
     roots: string[];
@@ -38,7 +39,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with
@@ -60,6 +61,7 @@ export type MainOptions = {
         preview?: typeof previewGithubRepo;
         clone?: typeof cloneGithubRepo;
     };
+    update?: UpdateCliDeps;
 };
 /**
  * Strip `-o <file>` / `--output <file>` before dispatch. The flag belongs to

package/dist/cli.js

@@ -28,6 +28,7 @@ import { readPulls } from "./pulls.js";
 import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } from "./graph.js";
 import { openStore, openStoreReadOnly, databasePath } from "./store.js";
 import { PACKAGE_VERSION } from "./version.js";
+import { runUpdateCommand } from "./toolroll-update-cli.js";
 import { runOperate, OPERATE_HELP } from "./operate.js";
 import { renderReport, renderPulls, renderGraph } from "./render.js";
 import { readRemote } from "./remote.js";
@@ -47,6 +48,8 @@ Usage
                                    preview, then clone and connect (--yes)
   toolroll link             put \`toolroll\` on your PATH
   toolroll unlink           take it off again
+  toolroll update           update to the latest release: verified, drained, undoable
+                                   (preview first; --yes, --now, --at HH:MM, --rollback)
   toolroll contract         the machine contract: envelope version + capabilities
                                    (--commands dumps the declared command guide)
   toolroll skills install --claude-code [--dir <path>]
@@ -56,6 +59,7 @@ Usage
   toolroll skills get <name>  print one guide (version-matched, never stale)
   toolroll demo             a seeded throwaway sandbox — see it working in 90 seconds
   toolroll up               app + builder for every saved project — the normal start
+  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes)
   toolroll status           running, queued, ready results, release check and plan windows
   toolroll session          native coding sessions through the running service
   toolroll connect          save a private connection to your central service
@@ -179,12 +183,13 @@ export function parseArgs(argv) {
  * which answers as `scan`. */
 export const TOP_LEVEL_COMMANDS = [
     "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github",
-    "link", "unlink", "contract", "skills list", "skills get", "skills install", "demo",
+    "link", "unlink", "update", "contract", "skills list", "skills get", "skills install", "demo",
     ...SESSION_CLI_ACTIONS.map(action => `session ${action}`),
     ...TEAM_CLI_ACTIONS,
 ];
 export const OPERATE_COMMANDS = new Set([
     "up",
+    "onboard",
     "status",
     "ready",
     "task",
@@ -368,6 +373,8 @@ async function dispatch(argv, write, mainOptions) {
     if (first === "link" || first === "unlink") {
         return runLinkCommand(first, rest, write, mainOptions.binSource);
     }
+    if (first === "update")
+        return runUpdateCommand(rest, write, mainOptions.update);
     if (first === "contract")
         return runContractCommand(rest, write);
     if (first === "session")

package/dist/control-setup.d.ts

@@ -6,13 +6,13 @@ export type SetupInputs = {
     seconds: string;
 };
 export declare function previewSetup(store: Store, repo: string, inputs: SetupInputs): {
-    provider?: never;
-    model?: never;
     ok: false;
     message: string;
     fingerprint?: never;
     command?: never;
     seconds?: never;
+    provider?: never;
+    model?: never;
 } | {
     message?: never;
     ok: true;
@@ -23,13 +23,13 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     model: string;
 };
 export declare function approveSetup(store: Store, repo: string, inputs: SetupInputs, fingerprint: string, by: string, token: string, now: Date): {
-    provider?: never;
-    model?: never;
     ok: false;
     message: string;
     fingerprint?: never;
     command?: never;
     seconds?: never;
+    provider?: never;
+    model?: never;
 } | {
     ok: true;
 };

package/dist/daemon.d.ts

@@ -94,6 +94,7 @@ export declare function launchdPlist(args: {
     associatedBundleId?: string;
     keepAlive?: boolean;
     startInterval?: number;
+    runAtLoad?: boolean;
 }): string;
 /**
  * Everything `install` would do, computed without doing it — the unit text,
@@ -144,6 +145,9 @@ export type ServiceStart = {
  * healthy service to prove it can.
  */
 export declare function installLaunchdService(definition: ServiceDefinition, run: SupervisorRunner): Promise<ServiceStart>;
+/** Replace a file whole: a flushed temporary beside it, renamed over it, and the directory flushed, so a crash
+ * leaves the old text or the new, never a torn one. */
+export declare function writeFileDurably(file: string, content: string | Uint8Array, mode?: number): void;
 /** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. */
 export declare function stopLaunchdService(definition: ServiceDefinition, run: SupervisorRunner): Promise<{
     ok: true;

package/dist/daemon.js

@@ -35,8 +35,8 @@
  * injectable — the tests read the generated unit and script `launchctl`,
  * and never touch the machine's real supervision.
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -157,7 +157,7 @@ ${escaped}
 ${environment}
   </dict>
   <key>RunAtLoad</key>
-  <true/>
+  <${args.runAtLoad === false ? "false" : "true"}/>
   <key>KeepAlive</key>
   <${args.keepAlive === false ? "false" : "true"}/>${args.startInterval === undefined ? "" : `\n  <key>StartInterval</key>\n  <integer>${args.startInterval}</integer>`}
   <key>ThrottleInterval</key>
@@ -343,7 +343,7 @@ export async function installLaunchdService(definition, run) {
     let changed = before !== definition.unitContent;
     mkdirSync(join(definition.logPath, ".."), { recursive: true });
     mkdirSync(join(definition.unitPath, ".."), { recursive: true });
-    writeFileSync(definition.unitPath, definition.unitContent, { mode: 0o644 });
+    writeFileDurably(definition.unitPath, definition.unitContent, 0o644);
     const status = await run("launchctl", ["print", service]);
     const loaded = status.code === 0;
     if (loaded)
@@ -382,6 +382,30 @@ export async function installLaunchdService(definition, run) {
         return { ok: true, changed, action: loaded ? "reloaded" : "bootstrapped" };
     return { ok: false, message: `launchctl refused the unit: ${firstLine(modern.stderr) || firstLine(legacy.stderr) || `exit ${legacy.code}`}` };
 }
+/** Replace a file whole: a flushed temporary beside it, renamed over it, and the directory flushed, so a crash
+ * leaves the old text or the new, never a torn one. */
+export function writeFileDurably(file, content, mode = 0o600) {
+    const temp = join(dirname(file), `.${file.slice(dirname(file).length + 1)}.${randomUUID().slice(0, 8)}.tmp`);
+    const fd = openSync(temp, "wx", mode);
+    try {
+        writeFileSync(fd, content);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    chmodSync(temp, mode);
+    renameSync(temp, file);
+    if (process.platform !== "win32") {
+        const directory = openSync(dirname(file), "r");
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+    }
+}
 /** Explicit stop: unload AND disable, so nothing relaunches it until a person installs again. */
 export async function stopLaunchdService(definition, run) {
     const service = `gui/${launchdUid()}/${definition.label}`;

package/dist/desktop-host.js

@@ -6,7 +6,7 @@ import { homedir, hostname } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createHmac } from "node:crypto";
 import { openStore, openStoreNoMigrate, databasePath, readSchemaVersion, SCHEMA_VERSION } from "./store.js";
-import { DatabaseSync } from "node:sqlite";
+import { createRequire } from "node:module";
 import { authenticateApprover, hashPassword } from "./scope.js";
 import { runOperate, writeLoginFileDurably } from "./operate.js";
 import { daemonStatus, installLaunchdService, planDesktopService, stopLaunchdService } from "./daemon.js";
@@ -117,7 +117,7 @@ export function desktopDatabaseStatus(file) {
     const result = (ready, message) => ({ ready, message, expectedSchema: SCHEMA_VERSION });
     try {
         // Read-only open: a missing/unreadable file must never become a new queue.
-        db = new DatabaseSync(file, { readOnly: true });
+        db = new createRequire(import.meta.url)("node:sqlite").DatabaseSync(file, { readOnly: true });
         db.exec("PRAGMA busy_timeout = 1000");
         const schema = readSchemaVersion(db);
         if (!schema.ok)

package/dist/desktop-update.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseSync } from "node:sqlite";
+import type { DatabaseSync } from "node:sqlite";
 import { type DesktopBundle } from "./desktop-bundle.js";
 type Phase = "prepared" | "draining" | "backing-up" | "stopping" | "installing" | "verifying" | "rolling-back" | "releasing" | "complete" | "restored" | "cancelled" | "needs-attention";
 export type UpdateJournal = {
@@ -48,6 +48,7 @@ export declare const updateTerminal: (phase: string) => boolean;
 /** Durable receipts are private and independent of the app being replaced. */
 export declare function durableJson(file: string, value: unknown): void;
 export declare function readUpdateJournal(stateDir: string, retainedReceipt?: string): UpdateJournal | null;
+export declare function lingeringWork(db: DatabaseSync): string | null;
 export declare function previewDesktopUpdate(stateDir: string, installed: string, candidate: string, label: string, hooks?: UpdateHooks): Promise<{
     old: DesktopBundle;
     next: DesktopBundle;
@@ -65,7 +66,6 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -79,6 +79,7 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {
@@ -104,6 +105,11 @@ export declare function requestUpdateStop(stateDir: string): void;
 export declare function requestUpdateRestore(stateDir: string): void;
 export declare function launchDesktopUpdate(stateDir: string, retry?: boolean): Promise<void>;
 export declare function pauseUpdateRecovery(stateDir: string, id: string, detail: string): void;
+/** A private, verified copy of the task database, made under a write
+ * reservation so no writer slips in between the snapshot and the copy. The
+ * copy drops the update's own admission pause. `inside` runs before the
+ * reservation is released, `after` once it is; returns the copy's hash. */
+export declare function verifiedDatabaseBackup(databaseFile: string, backupPath: string, gateId: string, inside?: () => Promise<void>, after?: () => void): Promise<string>;
 /** A SQLite OS lock releases on updater death. Each irreversible step has a
  * preceding durable intent; recovery determines the actual side by hashes. */
 export declare function runDesktopUpdate(stateDir: string, hooks?: UpdateHooks): Promise<void>;

package/dist/desktop-update.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, chmodSync, copyFileSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { backup, DatabaseSync } from "node:sqlite";
+import { createRequire } from "node:module";
 import { bundleHash, readDesktopBundle, verifyDesktopUpdateBundles } from "./desktop-bundle.js";
 import { readDesktopConfig, desktopServiceCommand, desktopServiceDefinition, verifyDesktopLiveness } from "./desktop-host.js";
 import { daemonStatus } from "./daemon.js";
@@ -10,6 +10,11 @@ import { readSchemaVersion, SCHEMA_VERSION, Store } from "./store.js";
 import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate, updateAdmissionPaused } from "./desktop-update-gate.js";
 import { currentDesktopAccess } from "./desktop-access.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists } from "./coding-update.js";
+/** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
+ * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
+function sqlite() {
+    return createRequire(import.meta.url)("node:sqlite");
+}
 export const updateTerminal = (phase) => ["complete", "restored", "cancelled"].includes(phase);
 const terminal = updateTerminal;
 const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
@@ -82,7 +87,7 @@ export function readUpdateJournal(stateDir, retainedReceipt) {
 function connect(file, readOnly = false) {
     if (!existsSync(file) || lstatSync(file).isSymbolicLink())
         throw Error("The task database is missing or linked. It was not recreated.");
-    const db = new DatabaseSync(file, { readOnly });
+    const db = new (sqlite().DatabaseSync)(file, { readOnly });
     db.exec("PRAGMA busy_timeout=1000");
     const schema = readSchemaVersion(db);
     if (!schema.ok || schema.version !== SCHEMA_VERSION) {
@@ -134,7 +139,7 @@ async function otherControllers(app, stateDir) {
     const command = `${join(resources(app), "runtime", "node")} ${join(resources(app), "dist", "desktop-host.js")} serve --state `;
     return result.stdout.split("\n").some(line => line.trim().startsWith(command) && line.trim() !== command + resolve(stateDir));
 }
-function lingeringWork(db) {
+export function lingeringWork(db) {
     const store = new Store(db);
     for (const row of db.prepare("SELECT DISTINCT run FROM run_process WHERE exited_at IS NULL").all()) {
         const problem = store.stopQuiescenceProblem(Number(row.run));
@@ -221,7 +226,7 @@ export async function prepareDesktopUpdate(stateDir, installed, candidate, label
 export function sqliteLock(file, busyTimeoutMs = 0) {
     if (existsSync(file))
         privateFile(file);
-    const db = new DatabaseSync(file);
+    const db = new (sqlite().DatabaseSync)(file);
     chmodSync(file, 0o600);
     try {
         db.exec(`PRAGMA busy_timeout=${busyTimeoutMs}; BEGIN EXCLUSIVE`);
@@ -335,16 +340,39 @@ async function verifiedBackup(j) {
     }
     // A crashed partial attempt gets a fresh filename; no backup is overwritten.
     const backupPath = existsSync(file) ? join(j.workDir, `orders.backup.${randomUUID()}.db`) : file;
-    const db = connect(j.databaseFile);
+    const backupHash = await verifiedDatabaseBackup(j.databaseFile, backupPath, j.id, async () => {
+        await verifiedCodingBackup(j);
+    }, () => {
+        for (const [source, name] of [[join(j.stateDir, "desktop.json"), "desktop.json"], [join(dirname(j.databaseFile), "repos.json"), "repos.json"], [join(dirname(j.databaseFile), "up-login.txt"), "up-login.txt"]]) {
+            if (source && name && existsSync(source)) {
+                if (!lstatSync(source).isFile() || lstatSync(source).isSymbolicLink())
+                    throw Error("A saved configuration file is linked or not a regular file. Nothing was replaced.");
+                if (name === "up-login.txt")
+                    privateFile(source);
+                copyFileSync(source, join(j.workDir, name));
+                chmodSync(join(j.workDir, name), 0o600);
+            }
+        }
+    });
+    j.backupPath = backupPath;
+    j.backupHash = backupHash;
+    save(j, "backing-up", "Private database backups verified; saved tasks, evidence and coding sessions match.");
+}
+/** A private, verified copy of the task database, made under a write
+ * reservation so no writer slips in between the snapshot and the copy. The
+ * copy drops the update's own admission pause. `inside` runs before the
+ * reservation is released, `after` once it is; returns the copy's hash. */
+export async function verifiedDatabaseBackup(databaseFile, backupPath, gateId, inside = async () => { }, after = () => { }) {
+    const db = connect(databaseFile);
     try {
         db.exec("BEGIN IMMEDIATE");
         // The write reservation prevents a concurrent writer; a separate read
         // connection is required because SQLite cannot back up a write transaction.
-        const source = connect(j.databaseFile, true);
+        const source = connect(databaseFile, true);
         let before;
         try {
             before = snapshot(source);
-            await backup(source, backupPath);
+            await sqlite().backup(source, backupPath);
         }
         finally {
             source.close();
@@ -354,23 +382,14 @@ async function verifiedBackup(j) {
         try {
             if (copied.prepare("PRAGMA integrity_check").get()?.integrity_check !== "ok" || copied.prepare("PRAGMA foreign_key_check").all().length !== 0 || snapshot(copied) !== before)
                 throw Error("Backup verification failed. The installed app is unchanged.");
-            removeUpdateGate(copied, j.id);
+            removeUpdateGate(copied, gateId);
         }
         finally {
             copied.close();
         }
-        await verifiedCodingBackup(j);
+        await inside();
         db.exec("COMMIT");
-        for (const [source, name] of [[join(j.stateDir, "desktop.json"), "desktop.json"], [join(dirname(j.databaseFile), "repos.json"), "repos.json"], [join(dirname(j.databaseFile), "up-login.txt"), "up-login.txt"]]) {
-            if (source && name && existsSync(source)) {
-                if (!lstatSync(source).isFile() || lstatSync(source).isSymbolicLink())
-                    throw Error("A saved configuration file is linked or not a regular file. Nothing was replaced.");
-                if (name === "up-login.txt")
-                    privateFile(source);
-                copyFileSync(source, join(j.workDir, name));
-                chmodSync(join(j.workDir, name), 0o600);
-            }
-        }
+        after();
         const fd = openSync(backupPath, "r");
         try {
             fsyncSync(fd);
@@ -378,9 +397,7 @@ async function verifiedBackup(j) {
         finally {
             closeSync(fd);
         }
-        j.backupPath = backupPath;
-        j.backupHash = fileHash(backupPath);
-        save(j, "backing-up", "Private database backups verified; saved tasks, evidence and coding sessions match.");
+        return fileHash(backupPath);
     }
     finally {
         db.close();

package/dist/evidence.d.ts

@@ -300,6 +300,30 @@ export type SecretHit = {
 };
 /** Scan text line by line; every hit names its pattern and line. */
 export declare function scanForSecrets(text: string): SecretHit[];
+/**
+ * Whether one matched secret shape is a documented or reserved placeholder:
+ * anything spelling EXAMPLE (AWS's own AKIAIOSFODNN7EXAMPLE), a password on
+ * a reserved example host, or a value that is mostly one repeated character.
+ */
+export declare function isPlaceholderSecret(name: string, line: string, match: RegExpExecArray): boolean;
+/** A secret shape the diff ADDS, with the patch line (for redaction) and
+ * the file and line it lands on at the new head (for the alert). */
+export type PatchSecretHit = SecretHit & {
+    file: string;
+    fileLine: number;
+};
+/**
+ * Scan a unified diff for secrets it commits: only added lines count —
+ * removing a line cannot commit a secret, and context lines were already
+ * there — and documented or reserved placeholders are not secrets.
+ */
+export declare function scanPatchForSecrets(patch: string): PatchSecretHit[];
+/** The alert for a candidate head with a flagged added line: where each
+ * hit is and what to do, without repeating the value. */
+export declare function secretAlert(hits: readonly PatchSecretHit[], runId: number): {
+    subject: string;
+    body: string;
+};
 /** Replace every hit line with a marker naming what was found — the display copy holds no secret. */
 export declare function redactSecretLines(text: string, hits: readonly SecretHit[]): string;
 /**

package/dist/evidence.js

@@ -638,6 +638,104 @@ export function scanForSecrets(text) {
     }
     return hits;
 }
+/** Hosts the DNS standards reserve for examples and loopback (RFC 2606,
+ * RFC 6761): a URL with a password on one of these reaches nothing real. */
+function reservedHost(host) {
+    const name = host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+    if (name === "127.0.0.1" || name === "::1")
+        return true;
+    if (/(?:^|\.)example\.(?:com|net|org)$/.test(name))
+        return true;
+    return /(?:^|\.)(?:example|test|invalid|localhost)$/.test(name);
+}
+/** Mostly one character, e.g. "sk-" and forty a's: a fixture, not a key. */
+function repeatedFiller(value) {
+    const longest = value.split(/[^A-Za-z0-9]+/).reduce((best, part) => (part.length > best.length ? part : best), "");
+    if (longest.length < 8)
+        return false;
+    const counts = new Map();
+    for (const char of longest)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    return Math.max(...counts.values()) * 2 > longest.length;
+}
+/**
+ * Whether one matched secret shape is a documented or reserved placeholder:
+ * anything spelling EXAMPLE (AWS's own AKIAIOSFODNN7EXAMPLE), a password on
+ * a reserved example host, or a value that is mostly one repeated character.
+ */
+export function isPlaceholderSecret(name, line, match) {
+    if (name === "private-key")
+        return false;
+    if (/example/i.test(match[0]))
+        return true;
+    if (name !== "password-in-url")
+        return repeatedFiller(match[0]);
+    const host = /^(\[[^\]\s]*\]|[^\s/:?#'"`]+)/.exec(line.slice(match.index + match[0].length - 1))?.[1] ?? "";
+    const password = /:([^\s:@/]+)@[^@]*$/.exec(match[0])?.[1] ?? "";
+    return reservedHost(host) || repeatedFiller(password);
+}
+/** The first secret shape on a line that is not a placeholder, if any. */
+function realSecretShape(line) {
+    for (const { name, pattern } of SECRET_PATTERNS) {
+        for (const match of line.matchAll(new RegExp(pattern.source, `${pattern.flags}g`))) {
+            if (!isPlaceholderSecret(name, line, match))
+                return name;
+        }
+    }
+    return null;
+}
+/**
+ * Scan a unified diff for secrets it commits: only added lines count —
+ * removing a line cannot commit a secret, and context lines were already
+ * there — and documented or reserved placeholders are not secrets.
+ */
+export function scanPatchForSecrets(patch) {
+    const hits = [];
+    const lines = patch.split("\n");
+    let file = "";
+    let inHunk = false;
+    let next = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.startsWith("diff --git ")) {
+            inHunk = false;
+            file = /^diff --git a\/.* b\/(.*)$/.exec(line)?.[1] ?? "";
+            continue;
+        }
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+        if (hunk !== null) {
+            inHunk = true;
+            next = Number(hunk[1]);
+            continue;
+        }
+        if (!inHunk) {
+            if (line.startsWith("+++ "))
+                file = line.slice(4).replace(/^b\//, "");
+            continue;
+        }
+        if (line.startsWith("+")) {
+            const name = realSecretShape(line.slice(1));
+            if (name !== null)
+                hits.push({ name, line: index + 1, file, fileLine: next });
+            next += 1;
+        }
+        else if (line.startsWith(" "))
+            next += 1;
+    }
+    return hits;
+}
+/** The alert for a candidate head with a flagged added line: where each
+ * hit is and what to do, without repeating the value. */
+export function secretAlert(hits, runId) {
+    const shown = hits.slice(0, 5).map(hit => `${hit.file}:${hit.fileLine} (${hit.name})`);
+    const more = hits.length > shown.length ? `, and ${hits.length - shown.length} more` : "";
+    return {
+        subject: `Run #${runId} adds what looks like a key`,
+        body: `${hits.length === 1 ? "An added line looks" : `${hits.length} added lines look`} like a real key: ${shown.join(", ")}${more}. ` +
+            `This run won't be published and the saved diff hides ${hits.length === 1 ? "that line" : "those lines"}. ` +
+            `If this is a real key, rotate it and rewrite the branch. If it's a test value, assemble it at run time.`,
+    };
+}
 /** Replace every hit line with a marker naming what was found — the display copy holds no secret. */
 export function redactSecretLines(text, hits) {
     const flagged = new Map(hits.map(hit => [hit.line, hit.name]));
@@ -689,8 +787,10 @@ export async function captureTerminalDiff(store, git, worktree, base, head, root
     // SECOND durable, console-served copy. Hit lines are redacted in the
     // stored artifact, the row says redacted, a page names the branch — and
     // the publication gate refuses to push a redacted run's branch anywhere.
+    // Only lines the diff adds count, and the alert is one per candidate head:
+    // every gate over the same head would otherwise repeat it.
     const rawPatch = patch.code === 0 ? patch.stdout : patch.stderr;
-    const hits = patch.code === 0 ? scanForSecrets(rawPatch) : [];
+    const hits = patch.code === 0 ? scanPatchForSecrets(rawPatch) : [];
     const patchContent = Buffer.from(hits.length > 0 ? redactSecretLines(rawPatch, hits) : rawPatch, "utf8");
     const diffId = storeEvidence(store, root, runId, "terminal-diff", "terminal-diff.patch", patchContent, patchCommand, now, {
         redacted: hits.length > 0,
@@ -699,13 +799,11 @@ export async function captureTerminalDiff(store, git, worktree, base, head, root
     if (hits.length > 0) {
         store.enqueueNotification({
             source: { run: runId },
-            dedupeKey: `secret:${runId}`,
+            dedupeKey: `secret:${head}`,
             kind: "secret-detected",
             pushClass: "attention",
             link: `/r/${runId}`,
-            subject: `possible committed secret: run #${runId}`,
-            body: `${hits.length} high-confidence secret shape(s) in the accepted diff (${[...new Set(hits.map(one => one.name))].join(", ")}). ` +
-                `The branch holds the real bytes — rewrite it before anything merges. Publication of this run is blocked.`,
+            ...secretAlert(hits, runId),
         }, now);
     }
     const statArgs = ["--no-optional-locks", "diff", "--numstat", "-z", base, head];