toolroll 0.9.76 → 0.9.78

package/dist/guides.js

@@ -482,13 +482,17 @@ with a time limit.
 10. **tree**: main's merge commit must have exactly the gated tree, or
    nothing is tagged.
 11. **tag**: pushes \`v<version>\` on that merge commit. In publish.yml,
-    macOS Node 22 and 24 must both pass before npm and GitHub publication.
+    macOS Node 22 and 24 must both pass before npm and GitHub publication
+    (the candidate's macOS checks already passed in ci.yml before the merge).
     macos.yml keeps the nightly matrix.
-12. **publish**: waits for npm, the GitHub release and the tag's macOS
-    and publish checks.
-13. **homebrew**: updates the tap's formula, waits for checks to register
-    and every registered check to pass, then merges. No checks means waiting,
-    within the Homebrew time limit; a failed or skipped check stops the release.
+12. **publish**: waits for npm, the GitHub release and the tag's publish
+    job (which needs the macOS legs); not main's own CI on the merge commit.
+13. **homebrew**: the release is published once npm and the GitHub release
+    are verified. It proposes the tap's formula change (checksum from npm's
+    tarball) and looks at its checks once: \`Published; Homebrew pending\`
+    (or failed) ends the run, and the same command finishes it later, waiting
+    for checks to register and every one to pass, then merging exactly that
+    change. A tap already on a newer version is never moved back.
 
 ## When it stops
 
@@ -508,11 +512,14 @@ instead of making them twice.
   A stop at the gate comes before the task is filed, so nothing was filed
   either: a fix pushed as a new commit is released with \`--new\`; after
   rerunning the failed job on GitHub, run the same command again.
-- \`publish-failed\` / \`homebrew-failed\`: fix the failed workflow before
-  resuming. A failed tag check cannot finish publication or update Homebrew.
-- \`base-moved\`: main gained a commit the branch doesn't have, so the
-  merge wouldn't be the checked tree. Nothing was merged: update the
-  branch and release it with \`--new\`.
+- \`publish-failed\`: fix the failed workflow before resuming. A failed tag
+  check cannot finish publication or update Homebrew.
+- Homebrew failed: the release is still published. Fix or rerun the tap's
+  check, then run the same command to finish Homebrew.
+- \`base-moved\`: the branch is behind main (it doesn't contain main's
+  head), so the merge wouldn't be the tree CI tested. Checked at the gate
+  (nothing filed) and again right before merging (nothing merged): update
+  the branch, push, and release it with \`--new\`.
 - \`tree-mismatch\`: main changed what was checked. Nothing was tagged;
   the deployed build stays.
 - \`timeout\`: rerun to keep waiting; \`--limit <step>=<minutes>\`
@@ -520,6 +527,10 @@ instead of making them twice.
 - An interrupted deployment resumes with \`deploy-browser.mjs --stage <saved
   path> --phase recover\` before any new attempt, including \`--new\`.
   Failed recovery stops there; the original deployment journal remains available.
+  \`toolroll release --recover-deploy\` shows what that recovery will do for
+  the one unfinished deployment, and \`--yes\` runs it: when the old service
+  isn't proved stopped it stops only processes proved to be that service's
+  own, restarts the previous service and lifts the pause. Safe to rerun.
 - \`link\`: a CLI name didn't answer as the new build, so both were put
   back. The service already runs the new build; fix the name and rerun.
 - \`gate-held\`: the deployment stopped before its swap but left new work

package/dist/latency-timeline.d.ts

@@ -0,0 +1,46 @@
+import type { CheckReport } from "./contracts/release-check.js";
+import { type Milestone, type Store } from "./store.js";
+/** A console request slower than this keeps its timeline. */
+export declare const SLOW_REQUEST_MS = 1000;
+/** One operation's milestones as they happen, bounded (the store bounds them again when kept). */
+export declare class Timeline {
+    readonly startedAt: Date;
+    private readonly t0;
+    readonly marks: Milestone[];
+    mark(name: string, detail?: string): void;
+    elapsed(): number;
+}
+/** Keep a finished console request's timeline when it was slow. Best effort: a failed write never touches the answer. */
+export declare function keepSlowRequest(store: Store, timeline: Timeline, route: string, status: number, now: Date): void;
+/** The check's own `took:` line (scripts/release-check.mjs): each part's duration, in ms, by label. */
+export declare function partDurations(stdout: string): Map<string, number>;
+/** A release check's parts as milestones: each part that started, and its end where its duration is known. */
+export declare function checkMilestones(report: CheckReport, stdout: string): {
+    startedAt: Date;
+    totalMs: number;
+    milestones: Milestone[];
+} | null;
+/** Keep a release check's timeline beside its run. Best effort: the check's outcome never depends on it. */
+export declare function keepCheckTimeline(store: Store, args: {
+    runId: number;
+    taskId: string;
+    report: CheckReport | null;
+    stdout: string;
+    now: Date;
+}): void;
+/** "Where the time went" on the task and run page: the run's check and the task's deploys, newest first. */
+export type TimingView = {
+    title: string;
+    total: string;
+    rows: {
+        label: string;
+        at: string;
+        detail: string | null;
+    }[];
+}[];
+/** 65 s → "1:05"; 3 723 s → "1:02:03". */
+export declare function clockWords(ms: number): string;
+/** A run's check timelines and its task's deploy timelines, for the page (null: none kept). */
+export declare function timingFor(store: Store, runId: number | null, taskId: string): TimingView | null;
+/** The approver's debug view beside /healthz (/health): the slowest recent console requests, one line each. */
+export declare function slowRequestLines(store: Store, limit?: number): string[];

package/dist/latency-timeline.js

@@ -0,0 +1,120 @@
+/**
+ * Latency timelines (docs/plans/actors-lessons.md, from durable-actors' latency timeline): for one operation, a short
+ * list of milestones, each an offset from its start, kept in the plane (latency_timeline, bounded and pruned) for:
+ *
+ * - console requests slower than SLOW_REQUEST_MS: route matched, signed in, chrome and worker reads, handler, render;
+ * - release checks: each part's start and end, from the sealed report's start times and the check's own `took:` line;
+ * - deploys: each phase, and each health wait with its reason (scripts/deploy-phases.mjs writes those).
+ *
+ * Milestones carry route ids, part and phase names and fixed reason words only: never a URL, a query, a body or a
+ * secret. A console request's offsets are monotonic (performance.now within one process); a check's and a deploy's
+ * are wall-clock offsets, since their parts run in other processes.
+ */
+import { performance } from "node:perf_hooks";
+import { latencyTimelines, MAX_MILESTONES, recordLatencyTimeline } from "./store.js";
+/** A console request slower than this keeps its timeline. */
+export const SLOW_REQUEST_MS = 1_000;
+/** One operation's milestones as they happen, bounded (the store bounds them again when kept). */
+export class Timeline {
+    startedAt = new Date();
+    t0 = performance.now();
+    marks = [];
+    mark(name, detail) {
+        if (this.marks.length >= MAX_MILESTONES * 2)
+            return;
+        this.marks.push({ name, ms: performance.now() - this.t0, ...(detail === undefined ? {} : { detail }) });
+    }
+    elapsed() { return performance.now() - this.t0; }
+}
+/** Keep a finished console request's timeline when it was slow. Best effort: a failed write never touches the answer. */
+export function keepSlowRequest(store, timeline, route, status, now) {
+    const total = timeline.elapsed();
+    if (total < SLOW_REQUEST_MS)
+        return;
+    try {
+        recordLatencyTimeline(store, { kind: "console", subject: route, startedAt: timeline.startedAt, totalMs: total,
+            milestones: [...timeline.marks, { name: "answered", ms: total, detail: `status ${status}` }] }, now);
+    }
+    catch { /* display only */ }
+}
+const TOOK = /^(\d+(?:\.\d+)?) (s|min)$/;
+/** The check's own `took:` line (scripts/release-check.mjs): each part's duration, in ms, by label. */
+export function partDurations(stdout) {
+    const line = stdout.split("\n").reverse().find(one => one.startsWith("took: "));
+    const durations = new Map();
+    if (line === undefined)
+        return durations;
+    for (const one of line.slice("took: ".length).split(";")[0].split(", ")) {
+        const at = one.lastIndexOf(" ", one.lastIndexOf(" ") - 1);
+        if (at < 1)
+            continue;
+        const label = one.slice(0, at), took = TOOK.exec(one.slice(at + 1));
+        if (took !== null)
+            durations.set(label, Number(took[1]) * (took[2] === "min" ? 60_000 : 1_000));
+    }
+    return durations;
+}
+/** A release check's parts as milestones: each part that started, and its end where its duration is known. */
+export function checkMilestones(report, stdout) {
+    const took = partDurations(stdout);
+    const started = report.parts.flatMap(part => {
+        const at = part.startedAt == null ? NaN : Date.parse(part.startedAt);
+        return Number.isFinite(at) ? [{ part: part.part, at, ms: took.get(part.part) ?? null }] : [];
+    });
+    if (started.length === 0)
+        return null;
+    const first = Math.min(...started.map(one => one.at));
+    const milestones = started.flatMap(one => [
+        { name: `${one.part} started`, ms: one.at - first },
+        ...(one.ms === null ? [] : [{ name: `${one.part} ended`, ms: one.at - first + one.ms }]),
+    ]).sort((a, b) => a.ms - b.ms);
+    return { startedAt: new Date(first), totalMs: Math.max(...milestones.map(one => one.ms)), milestones };
+}
+/** Keep a release check's timeline beside its run. Best effort: the check's outcome never depends on it. */
+export function keepCheckTimeline(store, args) {
+    if (args.report === null)
+        return;
+    try {
+        const timeline = checkMilestones(args.report, args.stdout);
+        if (timeline === null)
+            return;
+        recordLatencyTimeline(store, { kind: "release-check", subject: `check ${args.report.mode}`, runId: args.runId, taskId: args.taskId, ...timeline }, args.now);
+    }
+    catch { /* display only */ }
+}
+/** 65 s → "1:05"; 3 723 s → "1:02:03". */
+export function clockWords(ms) {
+    const seconds = Math.round(ms / 1000), h = Math.floor(seconds / 3600), m = Math.floor((seconds % 3600) / 60), s = seconds % 60;
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
+}
+function viewOf(one) {
+    const title = one.kind === "deploy" ? `Deploy ${one.subject}` : one.kind === "release-check" ? "Release check" : `Request ${one.subject}`;
+    const started = new Map();
+    return { title, total: clockWords(one.totalMs), rows: one.milestones.map(mark => {
+            const part = / (started|ended)$/.exec(mark.name);
+            if (part?.[1] === "started")
+                started.set(mark.name.slice(0, -" started".length), mark.ms);
+            const began = part?.[1] === "ended" ? started.get(mark.name.slice(0, -" ended".length)) : undefined;
+            return { label: mark.name, at: `+${clockWords(mark.ms)}`, detail: began === undefined ? mark.detail ?? null : `took ${clockWords(mark.ms - began)}` };
+        }) };
+}
+/** A run's check timelines and its task's deploy timelines, for the page (null: none kept). */
+export function timingFor(store, runId, taskId) {
+    try {
+        const kept = runId === null ? latencyTimelines(store, { taskId, limit: 5 }) : latencyTimelines(store, { runId, taskId, limit: 5 });
+        const shown = kept.filter(one => one.kind === "deploy" || one.runId === runId);
+        return shown.length === 0 ? null : shown.map(viewOf);
+    }
+    catch {
+        return null;
+    }
+}
+/** The approver's debug view beside /healthz (/health): the slowest recent console requests, one line each. */
+export function slowRequestLines(store, limit = 20) {
+    try {
+        return latencyTimelines(store, { kind: "console", limit }).map(one => `${one.startedAt} ${one.subject} ${Math.round(one.totalMs)} ms: ${one.milestones.map(mark => `${mark.name} +${Math.round(mark.ms)}${mark.detail === undefined ? "" : ` (${mark.detail})`}`).join(", ")}`);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/live-backup.d.ts

@@ -0,0 +1,39 @@
+import { type LiveBackupCopy, type LiveBackupSettings, type Store } from "./store.js";
+/** The choices Settings offers, in minutes (0: off is its own choice). */
+export declare const LIVE_EVERY_MINUTES: readonly [1, 5, 15, 30];
+/** Daily copies are kept this many days besides the newest `keep`. */
+export declare const LIVE_DAILY_DAYS = 7;
+/** `backups/live` beside the database, through its real path (the folder check refuses a path through a link). */
+export declare function defaultLiveFolder(databaseFile: string): string;
+export declare const liveFolderOf: (settings: LiveBackupSettings, databaseFile: string) => string;
+/** Why a folder can't hold the copies, or null. Missing is fine (it is made on first use, then checked again). */
+export declare function liveFolderProblem(folder: string, forbidden: readonly string[], protectedRoot?: string): string | null;
+/** This database's copies in a folder, newest first (plain files named for it only). */
+export declare function liveCopies(folder: string, tag: string): {
+    name: string;
+    path: string;
+    day: string;
+}[];
+/** Keep the newest `keep`, the newest of each of the last LIVE_DAILY_DAYS days, and `protect`; remove the rest (and
+ * this database's partial files older than an hour). Never anything not named for this database. */
+export declare function pruneLiveCopies(folder: string, tag: string, keep: number, now: Date, protect: string | null): number;
+/** One copy on a worker thread: copied, checked, hashed and renamed into place, or a problem (nothing left behind). */
+export declare function copyOffThread(source: string, folder: string, tag: string, now: Date): Promise<{
+    ok: true;
+    copy: Omit<LiveBackupCopy, "madeAt">;
+} | {
+    ok: false;
+    problem: string;
+}>;
+/** Whether a copy is due: on, and the latest (or the latest try) is at least the schedule old. */
+export declare function liveCopyDue(store: Store, now: Date): boolean;
+/** One pass: hold the lease, and when due check the folder, copy, record and prune. */
+export declare function liveBackupPass(store: Store, databaseFile: string, holder: string, forbidden: () => readonly string[], clock?: () => Date): Promise<{
+    ok: true;
+    copy: LiveBackupCopy;
+} | {
+    ok: false;
+    problem: string;
+} | null>;
+/** The loop in the worker: a pass a minute (the first after 30 s). The returned stop waits for a copy under way. */
+export declare function startLiveBackups(store: Store, databaseFile: string, forbidden: () => readonly string[], everyMs?: number): () => Promise<void>;

package/dist/live-backup.js

@@ -0,0 +1,271 @@
+/**
+ * The continuous copy (docs/plans/actors-lessons.md): every few minutes (default 5) the worker takes an online SQLite
+ * backup of the database into a folder (default `backups/live` beside it), checks it with `PRAGMA integrity_check`,
+ * hashes it and renames it into place, then records it as the latest verified copy (path, sha256, time, schema). It
+ * keeps the newest 24 and the newest of each of the last 7 days.
+ *
+ * Off the hot path: the copy, the check and the hash run on a worker thread, so neither the console nor the worker's
+ * loops wait for them. One process copies at a time (the live_backup lease).
+ *
+ * The folder is checked every time before use: a plain directory this user owns, not a link and reached through none,
+ * not writable by others, and inside the permanent fenced `backups` namespace beside the actual database, outside
+ * every project and build checkout (backup.ts checkBackupFolder). Restoring stays manual (`toolroll restore <file>` with Toolroll stopped). A deploy reuses the latest copy only
+ * when it is fresh, its schema matches and its content proves equal to the database it would otherwise copy
+ * (scripts/deploy-phases.mjs liveCopyBackup).
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Worker } from "node:worker_threads";
+import { checkBackupFolder, databaseTag } from "./backup.js";
+import { holdLiveBackup, liveBackupState, recordLiveBackup, releaseLiveBackup } from "./store.js";
+/** The choices Settings offers, in minutes (0: off is its own choice). */
+export const LIVE_EVERY_MINUTES = [1, 5, 15, 30];
+/** Daily copies are kept this many days besides the newest `keep`. */
+export const LIVE_DAILY_DAYS = 7;
+/** How long one copy may hold the lease. */
+const LEASE_MS = 15 * 60_000;
+/** `backups/live` beside the database, through its real path (the folder check refuses a path through a link). */
+export function defaultLiveFolder(databaseFile) {
+    let database = resolve(databaseFile);
+    try {
+        database = realpathSync(database);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    let at = dirname(database);
+    try {
+        at = realpathSync(at);
+    }
+    catch { /* not there yet: as given */ }
+    return join(at, "backups", "live");
+}
+export const liveFolderOf = (settings, databaseFile) => settings.folder ?? defaultLiveFolder(databaseFile);
+/** Why a folder can't hold the copies, or null. Missing is fine (it is made on first use, then checked again). */
+export function liveFolderProblem(folder, forbidden, protectedRoot) {
+    const said = checkBackupFolder(folder, forbidden);
+    if (said !== null)
+        return said;
+    if (protectedRoot !== undefined) {
+        const rel = relative(resolve(protectedRoot), resolve(folder));
+        if (rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") || isAbsolute(rel))
+            return `Choose a location inside the protected backup folder ${protectedRoot}.`;
+    }
+    let stat;
+    try {
+        stat = lstatSync(folder);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        return `${folder} isn't a plain folder.`;
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        return `${folder} belongs to another user.`;
+    if ((stat.mode & 0o022) !== 0)
+        return `Other users can write to ${folder}.`;
+    let real;
+    try {
+        real = realpathSync(folder);
+    }
+    catch {
+        return `${folder} can't be read.`;
+    }
+    if (real !== resolve(folder))
+        return `${folder} goes through a link; choose its real path (${real}).`;
+    return null;
+}
+const NAME = (tag) => new RegExp(`^live-${tag}-(\\d{4}-\\d{2}-\\d{2})-(\\d{6})(?:-(\\d+))?\\.db$`);
+const PARTIAL = (tag) => new RegExp(`^\\.live-${tag}-.*\\.partial$`);
+const stampOf = (now) => now.toISOString().replace(/\.\d+Z$/, "").replace("T", "-").replace(/:/g, "");
+/** This database's copies in a folder, newest first (plain files named for it only). */
+export function liveCopies(folder, tag) {
+    let names;
+    try {
+        names = readdirSync(folder);
+    }
+    catch {
+        return [];
+    }
+    const pattern = NAME(tag);
+    return names.flatMap(name => {
+        const m = pattern.exec(name);
+        if (m === null)
+            return [];
+        try {
+            if (!lstatSync(join(folder, name)).isFile())
+                return [];
+        }
+        catch {
+            return [];
+        }
+        return [{ name, path: join(folder, name), day: m[1], order: `${m[1]}-${m[2]}-${(m[3] ?? "1").padStart(6, "0")}` }];
+    }).sort((a, b) => a.order < b.order ? 1 : a.order > b.order ? -1 : 0).map(({ name, path, day }) => ({ name, path, day }));
+}
+/** Keep the newest `keep`, the newest of each of the last LIVE_DAILY_DAYS days, and `protect`; remove the rest (and
+ * this database's partial files older than an hour). Never anything not named for this database. */
+export function pruneLiveCopies(folder, tag, keep, now, protect) {
+    const copies = liveCopies(folder, tag);
+    const kept = new Set(copies.slice(0, Math.max(1, keep)).map(one => one.path));
+    const oldest = new Date(now.getTime() - (LIVE_DAILY_DAYS - 1) * 86_400_000).toISOString().slice(0, 10);
+    const days = new Set();
+    for (const one of copies)
+        if (one.day >= oldest && !days.has(one.day)) {
+            days.add(one.day);
+            kept.add(one.path);
+        }
+    if (protect !== null)
+        kept.add(resolve(protect));
+    let removed = 0;
+    for (const one of copies)
+        if (!kept.has(one.path)) {
+            try {
+                rmSync(one.path);
+                removed++;
+            }
+            catch { /* the next pass tries again */ }
+        }
+    try {
+        for (const name of readdirSync(folder).filter(one => PARTIAL(tag).test(one))) {
+            const path = join(folder, name), stat = lstatSync(path);
+            if (stat.isFile() && now.getTime() - stat.mtimeMs > 60 * 60_000)
+                rmSync(path, { force: true });
+        }
+    }
+    catch { /* the next pass tries again */ }
+    return removed;
+}
+/** The thread's whole job, plain JavaScript (an eval worker: no loader, the same in a checkout and when installed). */
+const COPY_THREAD = `
+const { workerData, parentPort } = require("node:worker_threads");
+const { DatabaseSync, backup } = require("node:sqlite");
+const fs = require("node:fs"), crypto = require("node:crypto"), path = require("node:path");
+(async () => {
+  const { source, partial, target } = workerData;
+  try {
+    const db = new DatabaseSync(source);
+    db.exec("PRAGMA busy_timeout = 5000");
+    // SQLite inherits the private file: no world-readable partial exists even briefly.
+    fs.closeSync(fs.openSync(partial, "wx", 0o600));
+    try { await backup(db, partial, { rate: 1000000 }); } finally { db.close(); }
+    fs.chmodSync(partial, 0o600);
+    const copy = new DatabaseSync(partial);
+    let schemaVersion;
+    try {
+      copy.exec("PRAGMA journal_mode = DELETE");
+      const check = copy.prepare("PRAGMA integrity_check").all();
+      if (check.length !== 1 || check[0].integrity_check !== "ok") throw new Error("the copy failed SQLite's integrity check");
+      schemaVersion = Number(copy.prepare("SELECT version FROM schema_version").get()?.version);
+      if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) throw new Error("the copy has no settled schema version");
+    } finally { copy.close(); }
+    const hash = crypto.createHash("sha256"), buffer = Buffer.alloc(1 << 20), fd = fs.openSync(partial, "r");
+    try { let n; while ((n = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, n)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    fs.renameSync(partial, target);
+    const dir = fs.openSync(path.dirname(target), "r");
+    try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); }
+    parentPort.postMessage({ ok: true, sha256: hash.digest("hex"), bytes: fs.statSync(target).size, schemaVersion });
+  } catch (error) {
+    try { fs.rmSync(partial, { force: true }); } catch {}
+    parentPort.postMessage({ ok: false, problem: String((error && error.message) || error).slice(0, 300) });
+  }
+})();
+`;
+/** One copy on a worker thread: copied, checked, hashed and renamed into place, or a problem (nothing left behind). */
+export function copyOffThread(source, folder, tag, now) {
+    const stamp = stampOf(now);
+    let name = `live-${tag}-${stamp}.db`;
+    for (let n = 2; (() => { try {
+        lstatSync(join(folder, name));
+        return true;
+    }
+    catch {
+        return false;
+    } })(); n++)
+        name = `live-${tag}-${stamp}-${n}.db`;
+    const target = join(folder, name), partial = join(folder, `.live-${tag}-${stamp}.${randomBytes(4).toString("hex")}.partial`);
+    return new Promise(done => {
+        const thread = new Worker(COPY_THREAD, { eval: true, workerData: { source, partial, target } });
+        let settled = false;
+        const finish = (answer) => { if (!settled) {
+            settled = true;
+            done(answer);
+        } };
+        thread.once("message", (message) => finish(message.ok
+            ? { ok: true, copy: { file: target, sha256: String(message.sha256), bytes: Number(message.bytes), schemaVersion: Number(message.schemaVersion) } }
+            : { ok: false, problem: message.problem ?? "the copy failed" }));
+        thread.once("error", (error) => { rmSync(partial, { force: true }); finish({ ok: false, problem: String(error.message).slice(0, 300) }); });
+        thread.once("exit", () => finish({ ok: false, problem: "the copy stopped before it finished" }));
+    });
+}
+/** Whether a copy is due: on, and the latest (or the latest try) is at least the schedule old. */
+export function liveCopyDue(store, now) {
+    const state = liveBackupState(store);
+    if (!state.settings.enabled)
+        return false;
+    const every = state.settings.everyMinutes * 60_000;
+    const last = Math.max(state.latest === null ? 0 : Date.parse(state.latest.madeAt), state.triedAt === null ? 0 : Date.parse(state.triedAt));
+    return !Number.isFinite(last) || now.getTime() - last >= every;
+}
+/** One pass: hold the lease, and when due check the folder, copy, record and prune. */
+export async function liveBackupPass(store, databaseFile, holder, forbidden, clock = () => new Date()) {
+    const now = clock();
+    if (!liveCopyDue(store, now))
+        return null;
+    if (!holdLiveBackup(store, holder, now, new Date(now.getTime() + LEASE_MS)))
+        return null;
+    try {
+        const state = liveBackupState(store);
+        const folder = liveFolderOf(state.settings, databaseFile);
+        const fail = (problem) => { recordLiveBackup(store, { ok: false, problem }, clock()); return { ok: false, problem }; };
+        let problem = liveFolderProblem(folder, forbidden(), dirname(defaultLiveFolder(databaseFile)));
+        if (problem !== null)
+            return fail(problem);
+        try {
+            mkdirSync(folder, { recursive: true, mode: 0o700 });
+        }
+        catch (error) {
+            return fail(`${folder} couldn't be made (${error.message})`);
+        }
+        // Checked again now that it exists: what was made (or found) is what is used.
+        problem = liveFolderProblem(folder, forbidden(), dirname(defaultLiveFolder(databaseFile)));
+        if (problem !== null)
+            return fail(problem);
+        const made = await copyOffThread(databaseFile, folder, databaseTag(databaseFile), now);
+        if (!made.ok)
+            return fail(made.problem);
+        const copy = { ...made.copy, madeAt: now.toISOString() };
+        recordLiveBackup(store, { ok: true, copy }, clock());
+        pruneLiveCopies(folder, databaseTag(databaseFile), state.settings.keep, clock(), copy.file);
+        return { ok: true, copy };
+    }
+    finally {
+        releaseLiveBackup(store, holder);
+    }
+}
+/** The loop in the worker: a pass a minute (the first after 30 s). The returned stop waits for a copy under way. */
+export function startLiveBackups(store, databaseFile, forbidden, everyMs = 60_000) {
+    const holder = `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+    let stopped = false, timer = null, running = Promise.resolve();
+    const pass = () => {
+        if (stopped)
+            return;
+        running = liveBackupPass(store, databaseFile, holder, forbidden).catch(() => null).finally(() => {
+            if (!stopped) {
+                timer = setTimeout(pass, everyMs);
+                timer.unref?.();
+            }
+        });
+    };
+    timer = setTimeout(pass, 30_000);
+    timer.unref?.();
+    return async () => {
+        stopped = true;
+        if (timer !== null)
+            clearTimeout(timer);
+        // A copy under way gets a few seconds; past that the process may end under it (its partial file is removed later).
+        await Promise.race([running, new Promise(resolveWait => setTimeout(resolveWait, 10_000).unref?.())]);
+    };
+}

package/dist/operate.d.ts

@@ -6,6 +6,7 @@ import type { StepIo } from "./flow-steps.js";
 import type { FetchLike } from "./flow-share.js";
 import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
+import { type RolePort, type UpRoleStart } from "./up-processes.js";
 import { type TelegramTransport } from "./telegram.js";
 import { type LeadCliSeams } from "./lead-cli.js";
 import { type Principal, type RemoteSource } from "./operate-remote.js";
@@ -89,6 +90,8 @@ export type OperateOptions = {
     };
     /** Injected by tests: the classifier that sizes filed tasks (none by default under test). */
     filingSizer?: Sizer;
+    /** Set only by up-role-child.ts: this process is one role of a `toolroll up` (the console or the worker). */
+    upRole?: UpRoleHost;
 };
 export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection" | "pullRequests">>;
 export declare const OPERATE_HELP: string;
@@ -117,6 +120,8 @@ export declare const KEYS_ACTIONS: readonly ["status", "set", "clear", "verify",
  * tests): every value-taking flag any verb reads, and every boolean.
  * A --flag in neither set is a typo, refused by name.
  */
+/** Flags whose value is a secret someone types or pastes: taken as the next argument even when it starts with "--". */
+export declare const SECRET_VALUE_FLAGS: ReadonlySet<string>;
 export declare const OPERATE_VALUE_FLAGS: ReadonlySet<string>;
 export declare const OPERATE_BOOLEAN_FLAGS: ReadonlySet<string>;
 export declare function parseOperateArgs(argv: readonly string[], ownValues?: ReadonlySet<string>): Args | {
@@ -168,3 +173,11 @@ export declare function readUpConsoleUrl(dir: string): string | null;
 export declare const PROPOSALS_ACTIONS: readonly ["list", "confirm", "dismiss"];
 /** The value flags a verb reads under a global switch's name, for parseOperateArgs. */
 export declare function ownValueFlags(command: string, argv: readonly string[]): ReadonlySet<string> | undefined;
+/** What up-role-child.ts hands runOperate: the role's start, and its channel to the `up` that started it. */
+export type UpRoleHost = {
+    start: UpRoleStart;
+    port: RolePort;
+};
+/** A role child's whole run (up-role-child.ts): the ordinary command prelude (containment, secrets, limits), then the
+ * role itself. Only a process started by `up` gets here; no command line selects a role. */
+export declare function runUpRole(start: UpRoleStart, port: RolePort): Promise<number>;