toolroll 0.9.77 → 0.9.78

package/dist/deploy-rescue.js

@@ -0,0 +1,94 @@
+/**
+ * `toolroll release --recover-deploy [--stage <dir>] [--yes]`: one command for a browser deployment that stopped half
+ * way and could not put itself back (the 2026-10-29 deploy stuck at "stopping": an `up` left running under launchd
+ * that ignored SIGTERM, a restart refused while its stale heartbeat lapsed, and every resume refusing "not proved
+ * stopped"). It does what was done by hand, through the deployment's own recovery (scripts/deploy-browser.mjs
+ * --phase recover, run from the recorded commit's pristine extraction exactly as `toolroll release` resumes one):
+ *
+ *   - the journal is verified (one unfinished deployment of this database, its run recorded) under the deployment lock
+ *   - when the journal says the old service must be stopped, recovery requires proof it already exited; historical
+ *     PIDs and argv never authorize signals or booting out a currently loaded service. Remaining processes must be
+ *     stopped through their owner before recovery can resume.
+ *   - the previous service is started again (the verified backup first when the database was migrated past it) and
+ *     waited for past a stale worker heartbeat's window, then the deployment's update pause is lifted
+ *
+ * A journal at or past the new service's start is never touched here: the new service may be running, and the
+ * release resumes it forward. Finished journals need nothing. Run again after a refusal or a failure: every step
+ * re-proves itself, so a rerun does only what is still left.
+ */
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { BEFORE_SWAP } from "./release-gate.js";
+/** Phases where the new service may be running: recovery leaves them to the release, which resumes forward. */
+export const FORWARD_ONLY = Object.freeze(["starting", "started", "healthy"]);
+const FINISHED = Object.freeze(["released", "deployed"]);
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return path;
+} };
+/** What recovery will do from a phase, in a few words. */
+export function rescuePlan(phase, journal) {
+    const id = String(journal["id"] ?? "?"), prior = String(journal["priorRuntime"] ?? "?");
+    if (BEFORE_SWAP.includes(phase))
+        return [`The service was never stopped. Lifts update pause ${id}, if this deployment holds it.`];
+    if (phase === "restored")
+        return [`The previous service is already running again. Lifts update pause ${id}.`];
+    const words = [];
+    if (phase === "stopping") {
+        words.push("The old service must already be stopped. Recovery checks for remaining processes and refuses while any may still be running. Stop them through the service owner, then rerun recovery.");
+    }
+    if (["stopping", "stopped", "migrating", "migrated", "start-failed", "backup-restored"].includes(phase)) {
+        if (["migrating", "migrated", "start-failed"].includes(phase))
+            words.push("Puts the verified backup back first when the previous runtime can't read the migrated database.");
+        words.push(`Starts the previous service (${prior}) again and waits for it to answer, past a stopped worker's heartbeat window; then lifts update pause ${id}.`);
+    }
+    return words.length > 0 ? words : [`Journal phase ${phase}: the deployment's own recovery decides; it refuses anything it can't prove.`];
+}
+/** Find the one unfinished deployment (or the named stage), verify its journal, and recover it (with `yes`). */
+export async function rescueDeployment(stageArg, yes, world) {
+    const all = world.journals();
+    let chosen;
+    if (stageArg !== undefined) {
+        chosen = all.find(one => real(one.stage) === real(stageArg));
+        if (chosen === undefined)
+            return { ok: false, reason: "usage", message: `${stageArg} is not a deployment stage of this installation (under ${join(world.stateDir, "staged-upgrades")}).` };
+    }
+    else {
+        const open = all.filter(one => one.journal === null || !FINISHED.includes(String(one.journal["phase"])));
+        if (open.length === 0)
+            return { ok: true, acted: false, stage: null, phase: null, words: ["Nothing to recover: every deployment finished or was already put back."] };
+        if (open.length > 1)
+            return { ok: false, reason: "conflict", message: `${open.length} deployments are unfinished: ${open.map(one => one.stage).join(", ")}. Name one with --stage <dir>.` };
+        chosen = open[0];
+    }
+    const { stage, journal } = chosen;
+    if (journal === null)
+        return { ok: false, reason: "damaged", message: `${join(stage, "deployment.json")} can't be read; nothing was changed.` };
+    const phase = journal["phase"], run = journal["builder"];
+    if (typeof phase !== "string" || typeof journal["priorRuntime"] !== "string" || typeof journal["nextRuntime"] !== "string" || typeof journal["id"] !== "string") {
+        return { ok: false, reason: "damaged", message: `${join(stage, "deployment.json")} is missing its phase, runtimes or update id; nothing was changed.` };
+    }
+    if (journal["database"] !== world.database)
+        return { ok: false, reason: "conflict", message: `That deployment ran on ${String(journal["database"])}, not ${world.database}; nothing was changed.` };
+    if (!Number.isSafeInteger(run) || run < 1)
+        return { ok: false, reason: "damaged", message: `${join(stage, "deployment.json")} names no builder run, so its commit's recovery can't be found; nothing was changed.` };
+    if (FINISHED.includes(phase))
+        return { ok: true, acted: false, stage, phase, words: [`Nothing to recover: that deployment is ${phase}.`] };
+    if (FORWARD_ONLY.includes(phase)) {
+        return { ok: false, reason: "forward", message: `That deployment is at ${phase}: the new service may be running, so nothing was stopped. Continue it forward with \`toolroll release <branch>\` (it resumes the deployment's finish).` };
+    }
+    const plan = rescuePlan(phase, journal);
+    if (!yes)
+        return { ok: true, acted: false, stage, phase, words: [`Deployment ${String(journal["id"])} stopped at ${phase} (${stage}).`, ...plan, "Run it: toolroll release --recover-deploy --yes"] };
+    const worktree = world.runWorktree(run);
+    if (worktree === null)
+        return { ok: false, reason: "damaged", message: `Run ${String(run)} has no recorded worktree, so its commit's recovery can't run; nothing was changed.` };
+    const recovered = await world.recover({ run: run, worktree, stage });
+    const after = world.journals().find(one => one.stage === stage)?.journal ?? null;
+    const now = typeof after?.["phase"] === "string" ? after["phase"] : null;
+    if (!recovered.ok)
+        return { ok: false, reason: "failed", message: `${recovered.message}${now === null ? "" : ` The journal is at ${now}.`} Fix what it names, then run \`toolroll release --recover-deploy --yes\` again.` };
+    return { ok: true, acted: true, stage, phase: now, words: [now === "released" ? "The previous service is running and new work can start again." : `The deployment's recovery finished; its journal is at ${now ?? "an unreadable phase"}.`] };
+}

package/dist/desktop-update.d.ts

@@ -97,6 +97,7 @@ export declare function sqliteLock(file: string, busyTimeoutMs?: number): Databa
 export declare function lockHeld(file: string): boolean;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -110,7 +111,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/dispose.js

@@ -23,7 +23,7 @@ import { nightlyTaskRef, releaseTaskRef } from "./store.js";
 import {} from "./proof.js";
 import { verificationEvidence, failedVerificationEvidence } from "./verification-evidence.js";
 import { classifyGateFailure, describeGateFailure, gateFailureSummary } from "./gate-failure.js";
-import { propose, approve, liveReleaseOf } from "./scope.js";
+import { propose, approve, liveReleaseOf, releaseCheckScope } from "./scope.js";
 import { headWithin } from "./names.js";
 /** The reasons tick classifies as the attempt itself breaking. */
 const TICK_FAILURE_REASONS = new Set([
@@ -456,14 +456,15 @@ export function regateTask(store, taskId, now, approval) {
         return { ok: false, reason: "no-attempt", message: `${taskId} has no scope` };
     const head = last.headRevision;
     const actor = approval.kind === "operator" ? approval.name : approval.kind === "release" ? approval.name : `mode ${approval.name}`;
-    if (approval.kind === "release" && ((scope.candidate ?? null) === null || (scope.releaseTerms ?? null) === null)) {
+    // A release task: signed terms or a release check purpose (pipeline-speed.md, P0), each sealed with the approval.
+    if (approval.kind === "release" && ((scope.candidate ?? null) === null || !releaseCheckScope(scope))) {
         return { ok: false, reason: "not-approved", message: `${taskId} isn't a release candidate; only a release reruns under its own approval` };
     }
     // A prepared candidate (a release gate, the nightly check) already names the approved commit, and the builder loads
     // exactly its tree on every attempt. The rerun keeps that scope and its approval as they are: nothing is proposed or
     // sealed again, so a regate can never swap the approved commit, its release terms or the person's yes for others
     // (2026-10-27: a regate rewrote release-0.9.73's candidate to its own build commit and the release refused it).
-    if ((scope.candidate ?? null) !== null || (scope.releaseTerms ?? null) !== null) {
+    if ((scope.candidate ?? null) !== null || releaseCheckScope(scope)) {
         const candidate = scope.candidate ?? null;
         if (candidate === null || scope.approvedDigest !== scope.digest || last.scopeDigest !== scope.digest) {
             return { ok: false, reason: "not-approved", message: `${taskId}'s approved commit or scope changed since attempt #${last.id}, or its approval no longer stands; approve its scope again instead` };

package/dist/evidence.d.ts

@@ -73,6 +73,15 @@ export declare function isBinaryAssetPath(path: string): boolean;
 export declare const SHORTENED_MARKER = "\n\u2026 output shortened; ending follows \u2026\n";
 export declare function boundStreamHeadTail(value: string, cap: number, headShare?: number): string;
 export declare const EVIDENCE_CAPS: Record<Artifact["kind"], number>;
+/**
+ * The bound a writer may seal a kind at with storeEvidence's `cap`, above its default: a release check's sealed report and
+ * inventory (check-report.ts CHECK_ARTIFACT_CAP, 256 KiB). Readers accept exactly what writers may seal: 0.9.77 sealed
+ * reports up to 256 KiB but read structured output back only to 64 KiB, so every full report over that (~85 KiB for a
+ * 585-file suite) read as "no longer verifies" and the release's check as unavailable.
+ */
+export declare const SEALED_EVIDENCE_CAPS: Partial<Record<Artifact["kind"], number>>;
+/** The most a stored artifact of this kind may hold: its default cap, or the larger bound a sealed payload may use. */
+export declare function evidenceReadCap(kind: Artifact["kind"]): number;
 export declare function evidenceRoot(home: string): string;
 /**
  * Unpredictable per attempt, so nothing on disk before this build can already

package/dist/evidence.js

@@ -116,6 +116,17 @@ export const EVIDENCE_CAPS = {
     // to hold the JSON-escaped form of that bounded content plus provenance.
     "review-context": 200 * 1024 * 1024,
 };
+/**
+ * The bound a writer may seal a kind at with storeEvidence's `cap`, above its default: a release check's sealed report and
+ * inventory (check-report.ts CHECK_ARTIFACT_CAP, 256 KiB). Readers accept exactly what writers may seal: 0.9.77 sealed
+ * reports up to 256 KiB but read structured output back only to 64 KiB, so every full report over that (~85 KiB for a
+ * 585-file suite) read as "no longer verifies" and the release's check as unavailable.
+ */
+export const SEALED_EVIDENCE_CAPS = { "structured-output": 256 * 1024 };
+/** The most a stored artifact of this kind may hold: its default cap, or the larger bound a sealed payload may use. */
+export function evidenceReadCap(kind) {
+    return Math.max(EVIDENCE_CAPS[kind], SEALED_EVIDENCE_CAPS[kind] ?? 0);
+}
 export function evidenceRoot(home) {
     // Same continuity rule as the database: evidence recorded under an older
     // name keeps verifying until a new-name root exists.
@@ -398,8 +409,9 @@ export function imageDimensions(bytes, kind) {
  * store the caller passed — inside whatever transaction the caller holds.
  */
 export function storeEvidence(store, root, runId, kind, name, content, capture, now, options = {}) {
-    // `cap`: a sealed structured payload with its own documented bound (a release check's report: 256 KiB), never above 1 MiB.
-    const cap = options.cap === undefined ? EVIDENCE_CAPS[kind] : Math.min(options.cap, 1024 * 1024);
+    // `cap`: a sealed structured payload with its own documented bound (a release check's report: 256 KiB), never above what
+    // a reader of this kind accepts (evidenceReadCap): a record written larger would never verify again.
+    const cap = options.cap === undefined ? EVIDENCE_CAPS[kind] : Math.min(options.cap, evidenceReadCap(kind));
     const stored = content.subarray(0, cap);
     // Some callers that deliberately summarize/bound a source before storage
     // may still report its true original size. This keeps `truncated` honest
@@ -469,7 +481,7 @@ function withArtifactFile(root, artifact, use) {
             !/[\u0000-\u001f\u007f:]/.test(segment));
     if (!wellFormed)
         return { ok: false, problem: "the key is not a normalized relative path" };
-    const cap = EVIDENCE_CAPS[artifact.kind];
+    const cap = evidenceReadCap(artifact.kind);
     if (artifact.bytesStored > cap) {
         return { ok: false, problem: "the record claims more bytes than its kind may store" };
     }

package/dist/exec.d.ts

@@ -252,6 +252,8 @@ export type SpawnAttempt = {
  */
 export declare function retryTransientSpawn(attempt: () => Promise<SpawnAttempt>, delays?: readonly number[], sleep?: (ms: number) => Promise<void>): Promise<ExecResult>;
 export declare function run(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+/** How long a timed-out plain command has to exit after SIGTERM before it is killed outright. */
+export declare const TERM_GRACE_MS = 2000;
 /**
  * Provider replies are nested inside their JSONL envelope. A 64 KiB reply
  * therefore needs appreciably more than 64 KiB on the wire once quotes,

package/dist/exec.js

@@ -584,7 +584,10 @@ export function run(file, args, options = {}) {
         return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } });
     }
     return retryTransientSpawn(() => new Promise(resolve => {
-        execFile(wrapped.file, wrapped.args, {
+        // execFile's timeout sends SIGTERM and nothing more: a process that survives it (one that ignores or blocks
+        // it) never exits, and its caller would wait forever. SIGKILL follows a short grace later.
+        let hardKill;
+        const child = execFile(wrapped.file, wrapped.args, {
             cwd,
             timeout: timeoutMs,
             maxBuffer,
@@ -593,6 +596,8 @@ export function run(file, args, options = {}) {
             windowsHide: true,
             ...((env => env === undefined ? {} : { env }))(withSandboxEnv(childEnv, wrapped.env, (options.fence?.length ?? 0) > 0)),
         }, (error, stdout, stderr) => {
+            if (hardKill !== undefined)
+                clearTimeout(hardKill);
             if (error === null) {
                 resolve({ result: { code: 0, stdout, stderr, timedOut: false, notFound: false }, transient: false });
                 return;
@@ -602,8 +607,17 @@ export function run(file, args, options = {}) {
                 transient: isTransientSpawnFailure(error),
             });
         });
+        if (timeoutMs > 0) {
+            hardKill = setTimeout(() => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* gone */ } }, timeoutMs + TERM_GRACE_MS);
+            hardKill.unref?.();
+        }
     }));
 }
+/** How long a timed-out plain command has to exit after SIGTERM before it is killed outright. */
+export const TERM_GRACE_MS = 2_000;
 /**
  * The buffered transport for process-group providers (claude): spawn
  * detached so the harness and everything it launches share one killable

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,8 +512,10 @@ 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.
+- \`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
@@ -521,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>;