toolroll 0.9.104 → 0.9.105

package/dist/lesson-notes.js

@@ -1,27 +1,3 @@
-/**
- * Lesson notes (docs/plans/learning-loops.md, "Lesson notes"): when a check failure is followed by a revision whose check
- * explicitly passed the same tests, Toolroll proposes a note saying exactly that — "`<test>` failed in build #F; it
- * passed in revision R, which changed `<files>`". Not a claim that R caused it. A person writes or edits the words and
- * accepts it as a project decision through the memory proposal flow (memory-pass.ts decideProposal); nothing changes
- * before that. Then Toolroll reports how often the test fails afterwards, with no causal claim.
- *
- * The rules (all must hold), checked here when R's check is recorded:
- *  1. F is a builder run whose check failed (its own result), not infrastructure, with at least one case that failed
- *     with explicit execution evidence. File-level-only failures get no note.
- *  2. R is a builder run of a revision of F's task, or of F's explicit repair draft, or the next Full check of the same
- *     release; R's commit descends from F's (a verified commit walk).
- *  3. R's check passed with the same command and access as F's.
- *  4. Every failed case of F has an explicit `passed` line in R. F's cases join R's advisory `learn` request (never the
- *     gate's `watch`) so that can be true.
- *  5. No retry-assisted pass: nothing in R passed on a retry.
- *  6. None of those cases has mixed outcomes at F's tree.
- *  7. Otherwise no note, and R's page says exactly what was recorded: an explicit skip, a test file that isn't in R, or
- *     no test result at all. Each has its own words; none is read as another.
- *
- * Tallies are written with each check's results and never pruned, so "since" numbers survive retention. The only writer
- * of `lesson_note` and `lesson_note_tally`, and with flaky.ts of `learning_watch`. A policy path (release-auto.ts
- * EVAL_POLICY). Nothing here changes a check's outcome, a verdict, an approval or a rerun.
- */
 import { createHash } from "node:crypto";
 import { isUnitFile, projectGitDir } from "./check-report.js";
 import { readVerifiedCommit, verifiedBlobs, verifiedTreeDiff } from "./commit-extract.js";
@@ -34,7 +10,6 @@ const PATHS_MAX = 200;
 const WALK_MAX = 500;
 export const NOTE_SURFACE = "lesson-note";
 const FINGERPRINT = "note:";
-/** How deep a revision's ancestry is followed looking for the failed check. */
 const ANCESTRY_MAX = 8;
 export function lessonNoteOf(store, proposal) {
     const row = store.handle.prepare("SELECT * FROM lesson_note WHERE proposal = ?").get(proposal);
@@ -52,8 +27,6 @@ function factOf(store, run) {
 }
 const receiptIs = (store, run, state) => store.handle.prepare("SELECT 1 FROM check_result WHERE run = ? AND identity = 'check' AND source = 'receipt' AND state = ?").get(run, state) !== undefined;
 const roleOf = (store, run) => { const row = store.handle.prepare("SELECT role FROM run WHERE id = ?").get(run); return row === undefined ? null : String(row["role"]); };
-/** The check F a run revises, by the plane's own records: its repair draft's source, the failed check of the nearest
- * ancestor task with one, or the previous check of the same release. Null when it revises none. */
 function revisedRun(store, runId, taskRef, purpose) {
     const ref = store.handle.prepare("SELECT external_id, revision_of, revision_origin FROM task_ref WHERE id = ?").get(taskRef);
     if (ref === undefined)
@@ -80,15 +53,9 @@ function revisedRun(store, runId, taskRef, purpose) {
     }
     return null;
 }
-/** A run's failed cases with explicit execution evidence (the report's lines; file-level names don't count). */
 function failedCases(store, run) {
     return store.handle.prepare("SELECT DISTINCT identity FROM check_result WHERE run = ? AND state = 'failed' AND source = 'report' ORDER BY identity").all(run).map(row => String(row["identity"])).filter(isExactCase);
 }
-/**
- * What this run's check should also ask about for learning: the failed cases of the check it revises (rule 4). Advisory:
- * a separate handshake field, never the gate's `watch`. Called before the run's check starts, so its own facts don't
- * exist yet.
- */
 export function revisedFailures(store, runId) {
     const run = store.handle.prepare("SELECT task_ref, role FROM run WHERE id = ?").get(runId);
     if (run === undefined || run["role"] !== "builder")
@@ -98,7 +65,6 @@ export function revisedFailures(store, runId) {
     const prior = revisedRun(store, runId, taskRef, scoped === undefined ? null : String(scoped["purpose"]));
     return prior === null ? [] : failedCases(store, prior.failed);
 }
-/** Whether `head` descends from `ancestor`, walking verified commits, bounded. Unreadable is false: no note. */
 function descends(gitDir, head, ancestor) {
     if (head === ancestor)
         return false;
@@ -117,19 +83,15 @@ function descends(gitDir, head, ancestor) {
     }
     return false;
 }
-/** Test and harness files, as a reader would call them. Every one R changed is listed, never hidden. */
 export function testOrHarnessPath(path) {
     return isUnitFile(path) || /^(?:tests?|scripts|\.github)\//.test(path) || /(?:^|\/)(?:vitest|jest|playwright)[^/]*\.[a-z]+$/.test(path) || /(?:^|\/)package(?:-lock)?\.json$/.test(path);
 }
-/** Text from a candidate, made safe to show: one line, clipped, control-free; anything secret-shaped is withheld. */
 function safeText(text, max) {
-    // eslint-disable-next-line no-control-regex
     const line = text.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").trim();
     if (scanForSecrets(line).length > 0)
         return "(text withheld)";
     return line.length > max ? `${line.slice(0, max - 1)}…` : line;
 }
-/** The first failure line of F's sealed log, as output: clipped, secret-scanned, null when there is none to read. */
 function firstFailureLine(store, root, run) {
     const log = store.artifactsFor(run).find(one => one.kind === "check-log");
     if (log === undefined)
@@ -140,10 +102,6 @@ function firstFailureLine(store, root, run) {
     const line = read.content.toString("utf8").split("\n").find(one => /\b(?:FAIL|AssertionError|Error)\b/.test(one));
     return line === undefined ? null : safeText(line, 160);
 }
-/**
- * Consider a note for run R, once its check is recorded. Returns what happened; a note that can't be proposed for a
- * reason a person should see says so on R (rule 7). Any unreadable fact means no note.
- */
 export function considerLessonNote(store, root, runId, now) {
     const passing = factOf(store, runId);
     if (passing === null || passing.repo === null || passing.head === null || passing.tree === null || roleOf(store, runId) !== "builder")
@@ -225,16 +183,13 @@ export function considerLessonNote(store, root, runId, now) {
         return { proposal };
     });
 }
-// ---- accepted notes ------------------------------------------------------------------------------------------------
 const sourceRefOf = (proposal) => `lesson-note:${proposal}`;
 const noteOfDecision = (ref) => { const found = ref === null ? null : /^lesson-note:(\d+)$/.exec(ref); return found === null ? null : Number(found[1]); };
-/** Track an accepted note's cases in every later Full check, whether or not a run received it. */
 export function watchNote(store, input) {
     const sourceRef = input.decisionRevision === undefined ? `note:${input.proposal}` : `note:${input.proposal}:${input.decisionRevision}`;
     for (const identity of input.identities)
         store.handle.prepare(`INSERT INTO learning_watch (repo, identity, reason, source_ref, since, until) VALUES (?, ?, 'note', ?, ?, NULL) ON CONFLICT (repo, identity, reason, source_ref) DO NOTHING`).run(input.repo, identity, sourceRef, input.now.toISOString());
 }
-/** A note's tracking ends when its decision stops being active. */
 export function endNoteWatch(store, decisionSourceRef, now) {
     const proposal = noteOfDecision(decisionSourceRef);
     if (proposal === null)
@@ -253,12 +208,6 @@ function addTally(store, note, month, add, partial = 0) {
 const activeNotes = (store, repo) => store.handle.prepare(`SELECT n.proposal, n.identities_json, d.id AS decision, d.decided_at FROM lesson_note n JOIN project_decision d ON d.repo = n.repo AND d.source_ref = 'lesson-note:' || n.proposal AND d.status = 'active' WHERE n.repo = ?`).all(repo)
     .map(row => ({ note: Number(row["proposal"]), decision: Number(row["decision"]), identities: JSON.parse(String(row["identities_json"])), since: String(row["decided_at"]) }));
 const monthOf = (now) => now.toISOString().slice(0, 7);
-/**
- * Count one check for every accepted note, in the transaction that records its results: distinct `(run, identity)`
- * pairs with explicit results, split by whether the run received the decision. A check with no line for the note's
- * tests counts as unreported. `observations`: what this check just added, so a failure elsewhere that turned out to
- * have mixed outcomes is counted as such.
- */
 export function tallyCheck(store, runId, repo, observations, now) {
     const notes = activeNotes(store, repo);
     if (notes.length === 0)
@@ -291,7 +240,6 @@ export function tallyCheck(store, runId, repo, observations, now) {
             tally.unreported = 1;
         addTally(store, one.note, month, tally);
     }
-    // Observations this check added about an earlier failure: that failure is now known to have mixed outcomes.
     for (const id of observations) {
         const row = store.handle.prepare("SELECT identity, failed_run FROM local_observation WHERE id = ?").get(id);
         if (row === undefined || Number(row["failed_run"]) === runId)
@@ -303,12 +251,10 @@ export function tallyCheck(store, runId, repo, observations, now) {
             }
     }
 }
-/** A month whose check couldn't be recorded is partial, and says so. */
 export function markTalliesPartial(store, repo, now) {
     for (const one of activeNotes(store, repo))
         addTally(store, one.note, monthOf(now), { executions: 0, failures: 0, mixed: 0, receivedExecutions: 0, receivedFailures: 0, unreported: 0, sources: new Set() }, 1);
 }
-/** What a note's tallies say since it was accepted: sums of durable rows, unchanged by retention. */
 export function noteAfterwards(store, decision) {
     const note = noteOfDecision(decision.sourceRef);
     if (note === null)
@@ -319,7 +265,6 @@ export function noteAfterwards(store, decision) {
         partial: rows.some(row => Number(row["partial"]) === 1), sources: [...new Set(rows.flatMap(row => JSON.parse(String(row["sources_json"]))))].sort() };
 }
 const DAY = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
-/** "Since Nov 5: failed 1 of 31 runs of this test (0 of 18 that received this note; 1 of 13 that didn't). …". No "helped". */
 export function afterwardsWords(after) {
     const others = after.executions - after.receivedExecutions, otherFailures = after.failures - after.receivedFailures;
     return [
@@ -329,7 +274,6 @@ export function afterwardsWords(after) {
         after.partial ? "Partial: not every check was counted." : "",
     ].filter(Boolean).join(" ");
 }
-/** What waits for a person, for pages and chat. */
 export function memoryWaiting(store, repo) {
     return { notes: Number(store.handle.prepare("SELECT COUNT(*) AS n FROM memory_proposal WHERE repo = ? AND status = 'pending' AND surface = ?").get(repo, NOTE_SURFACE)?.["n"] ?? 0),
         cleanups: Number(store.handle.prepare("SELECT COUNT(*) AS n FROM memory_tidy_proposal WHERE repo = ? AND status = 'pending'").get(repo)?.["n"] ?? 0) };

package/dist/limits-ui.js

@@ -2,9 +2,7 @@ import { windowLabel } from "./provider-limits.js";
 import { usd } from "./spend.js";
 import { html } from "./html.js";
 const PROVIDER_NAMES = { claude: "Claude", codex: "Codex", gemini: "Gemini" };
-/** Plan names worth showing; anything else (an internal billing name) is left off. */
 const PLAN_NAMES = { free: "Free", plus: "Plus", pro: "Pro", max: "Max", team: "Team", business: "Business", enterprise: "Enterprise", edu: "Edu" };
-/** "in 25 min", "in 2 h 10 min", or a day and hour ("Fri 11 PM") beyond a day. */
 export function resetWords(resetsAt, now) {
     const minutes = Math.max(1, Math.round((Date.parse(resetsAt) - now.getTime()) / 60_000));
     if (minutes < 60)
@@ -21,7 +19,6 @@ const toneOf = (percent, reached) => reached || percent >= 100 ? "danger" : perc
 export function limitsView(windows, budgets, names, now) {
     const tiles = [];
     for (const one of windows) {
-        // A window that has turned over since the reading starts again from nothing.
         const turned = one.resetsAt !== null && Date.parse(one.resetsAt) <= now.getTime();
         const percent = turned ? 0 : one.usedPercent;
         const reached = !turned && one.reached;
@@ -48,20 +45,11 @@ export function limitsView(windows, budgets, names, now) {
     }
     return tiles.length === 0 ? null : { tiles };
 }
-/** One short reset: "3h", "25 min", or "Fri 11 PM". */
 const shortReset = (resetsAt, now) => {
     const minutes = Math.max(1, Math.round((Date.parse(resetsAt) - now.getTime()) / 60_000));
     return minutes < 60 ? `${minutes} min` : minutes < 24 * 60 ? `${Math.round(minutes / 60)}h` : resetWords(resetsAt, now);
 };
-/**
- * The usage chip (cockpit §3, R16): the subscription window with the highest use the providers last reported, as
- * "Claude 5-hour · 82% · resets 3h". A reading older than 30 minutes stays visibly stale ("as of 2h ago"), judged by
- * the reading's age as the Limits view judges it; a window with no known reset says "resets: unknown". API-key budgets
- * are not compared here (they stay in the details). An operator's view, as the Limits view is. Null: nothing reported.
- */
 export function usageChipOf(windows, now) {
-    // A window whose reset has passed since its reading is not measured again yet: it ranks below every current one, and
-    // shows what was last read, as stale — never an inferred 0%.
     const expired = (one) => one.resetsAt !== null && Date.parse(one.resetsAt) <= now.getTime();
     const rank = (one) => (expired(one) ? -1_000 : 0) + one.usedPercent + (one.reached && !expired(one) ? 1_000 : 0);
     const top = [...windows].sort((a, b) => rank(b) - rank(a))[0];
@@ -69,12 +57,10 @@ export function usageChipOf(windows, now) {
         return null;
     const old = expired(top);
     const stale = old || now.getTime() - Date.parse(top.observedAt) > 30 * 60_000;
-    // A window with no known length or reset has no reset to name.
     const reset = old ? "window reset" : top.resetsAt === null || top.windowMinutes === null ? "resets: unknown" : `resets ${shortReset(top.resetsAt, now)}`;
     const text = `${PROVIDER_NAMES[top.provider] ?? top.provider} ${windowLabel(top.window, top.windowMinutes)} · ${Math.round(top.usedPercent)}% · ${reset}${stale ? ` · as of ${ago(top.observedAt, now)}` : ""}`;
     return { text, tone: old ? "neutral" : toneOf(top.usedPercent, top.reached), stale, href: "/tasks", title: `What the providers last reported: ${text}` };
 }
-/** The same tiles for the page without scripts. */
 export function limitsHtml(limits) {
     if (limits === null)
         return html ``;

package/dist/link.js

@@ -1,44 +1,11 @@
-/**
- * Putting the command on PATH, as an explicit act.
- *
- * Toolroll refuses to install things on an operator's behalf — it prints
- * the command and its side effects and lets them run it. A tool that applied
- * that rule to `bd init` and then quietly edited PATH during its own install
- * would not deserve to be believed, so this is a command you run, it shows
- * you what it will do before it does it, and `unlink` undoes it exactly.
- *
- * Three rules hold throughout: never sudo, never a directory outside the home
- * directory unless explicitly named, and never delete anything that is not
- * something we put there.
- *
- * Two mechanisms, because "a command on PATH" means different things. On POSIX
- * it is a symlink with the execute bit set. On Windows the shell resolves
- * commands through PATHEXT, so an extensionless symlink is invisible no matter
- * which directory it sits in — there it is a `.cmd` shim, which is also what
- * npm writes, and which needs no Developer Mode to create.
- */
 import { chmod, mkdir, lstat, readFile, readlink, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 const isWindows = process.platform === "win32";
-/** What you type. */
 export const BIN_NAME = "toolroll";
-/** What lands on disk. Windows needs the extension to resolve it through PATHEXT. */
 export const LINK_FILE = isWindows ? `${BIN_NAME}.cmd` : BIN_NAME;
-/** Owner, group, and other execute — the same bits npm sets on a package bin. */
 const EXECUTABLE_BITS = 0o111;
-/**
- * How a shim is known to be ours. The symlink case can ask the filesystem what
- * it is; a `.cmd` is an ordinary file, so it has to say so in its own text or
- * `unlink` could not tell it from someone else's program of the same name.
- */
 const SHIM_MARKER = "toolroll-link: generated by `toolroll link`";
-/** Shims written before the rename to Toolroll stay ours. */
 const LEGACY_SHIM_MARKER = "standing-orders-link: generated by `standing-orders link`";
-/**
- * Windows path comparison is case-insensitive, and a PATH entry may or may not
- * carry a trailing separator. Comparing the raw strings means a directory that
- * is on PATH gets reported as missing from it.
- */
 function comparablePath(path) {
     const trimmed = path.length > 1 && path.endsWith(sep) ? path.slice(0, -1) : path;
     return isWindows ? trimmed.toLowerCase() : trimmed;
@@ -46,17 +13,11 @@ function comparablePath(path) {
 function samePath(left, right) {
     return comparablePath(left) === comparablePath(right);
 }
-/** Whether `path` is the home directory or sits beneath it. */
 function isInside(path, home) {
     const inner = comparablePath(path);
     const outer = comparablePath(home);
     return inner === outer || inner.startsWith(outer + sep);
 }
-/**
- * Where the link should go. Only directories inside the home directory are
- * ever proposed: everything else needs sudo, and needing sudo to read your own
- * git repositories would be absurd.
- */
 export function chooseTarget(options) {
     const { pathEntries, home, override } = options;
     const isOnPath = (dir) => pathEntries.some(entry => samePath(entry, dir));
@@ -71,7 +32,6 @@ export function chooseTarget(options) {
     const homeOwned = pathEntries.find(entry => isInside(entry, home));
     if (homeOwned !== undefined)
         return { dir: homeOwned, onPath: true };
-    // Nothing usable on PATH. Propose the conventional location and say so.
     return { dir: conventional[0], onPath: false };
 }
 export async function planLink(source, dir) {
@@ -93,7 +53,6 @@ export async function applyLink(plan) {
     if (plan.action === "already")
         return;
     await mkdir(dirname(plan.target), { recursive: true });
-    // Only ever removing a shim we recognise, never someone else's file.
     if (plan.action === "replace")
         await unlink(plan.target);
     if (isWindows) {
@@ -103,31 +62,6 @@ export async function applyLink(plan) {
     await symlink(plan.source, plan.target);
     await ensureExecutable(plan.source);
 }
-/**
- * `%*` forwards arguments with their quoting intact — the same mechanism npm's
- * own generated shims use — and `EXIT /B` hands the command's exit code back to
- * the shell, without which a failing scan would look like a success to anything
- * that checked.
- *
- * The path is written with `%` doubled, because a percent sign is legal in a
- * Windows path and cmd would otherwise read `%Foo%` in it as a variable and
- * substitute it away. The `REM source:` line keeps the path verbatim: it is
- * read back by this program, not by cmd.
- *
- * `SETLOCAL DisableDelayedExpansion` is not ceremony. Delayed expansion is
- * inherited — a shim invoked under `cmd /v:on`, or from a batch file that
- * enabled it, would have every `!` in the path *and in the arguments* eaten
- * before node saw them, turning `a!name!b` into `ab` silently. Disabling it for
- * our own scope is the only way to be sure. `ENDLOCAL &` shares a line with the
- * exit so that `%ERRORLEVEL%` is read inside the scope, before it is torn down.
- *
- * One inherited quirk remains, worth knowing before someone reports it as a
- * bug: a batch file reaching this through CALL has its arguments parsed a
- * second time by cmd, which doubles any caret in them. That happens to
- * `CALL node ...` just the same, with no shim involved, and no batch file can
- * avoid it — only a compiled launcher could. The tests pin the shim to being
- * transparent rather than to being immune.
- */
 function shimText(source) {
     return [
         "@ECHO off",
@@ -139,18 +73,12 @@ function shimText(source) {
         "",
     ].join("\r\n");
 }
-/** The source a shim points at, or null when the text is not one of ours. */
 function readShimSource(text) {
     if (!text.includes(SHIM_MARKER) && !text.includes(LEGACY_SHIM_MARKER))
         return null;
     const declared = /^REM source: (.+)$/m.exec(text);
     return declared?.[1]?.trim() ?? null;
 }
-/**
- * tsc emits a file with the shebang intact but without the execute bit, so a
- * symlink to it fails with "permission denied" the first time it is typed.
- * Windows has no such bit, and chmod there is a no-op at best.
- */
 async function ensureExecutable(source) {
     if (isWindows)
         return;
@@ -177,10 +105,6 @@ export async function applyUnlink(plan) {
         return;
     await unlink(plan.target);
 }
-/**
- * null when nothing is there. Otherwise: ours, and what it points at, or
- * foreign, and why we will not touch it.
- */
 async function describeExisting(target) {
     let stats;
     try {
@@ -209,9 +133,6 @@ async function describeExisting(target) {
     if (!stats.isSymbolicLink()) {
         return { kind: "foreign", reason: "something that is not a link is already there" };
     }
-    // readlink returns the link's raw text, which may be relative. Comparing that
-    // against an absolute source would call a perfectly good link stale and
-    // replace it on every run.
     const raw = await readlink(target);
     return { kind: "ours", pointsTo: resolve(dirname(target), raw) };
 }

package/dist/live-backup.js

@@ -1,18 +1,3 @@
-/**
- * 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";
@@ -20,13 +5,9 @@ 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 {
@@ -40,11 +21,10 @@ export function defaultLiveFolder(databaseFile) {
     try {
         at = realpathSync(at);
     }
-    catch { /* not there yet: as given */ }
+    catch { }
     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)
@@ -81,7 +61,6 @@ export function liveFolderProblem(folder, forbidden, protectedRoot) {
 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 {
@@ -105,8 +84,6 @@ export function liveCopies(folder, tag) {
         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));
@@ -126,7 +103,7 @@ export function pruneLiveCopies(folder, tag, keep, now, protect) {
                 rmSync(one.path);
                 removed++;
             }
-            catch { /* the next pass tries again */ }
+            catch { }
         }
     try {
         for (const name of readdirSync(folder).filter(one => PARTIAL(tag).test(one))) {
@@ -135,10 +112,9 @@ export function pruneLiveCopies(folder, tag, keep, now, protect) {
                 rmSync(path, { force: true });
         }
     }
-    catch { /* the next pass tries again */ }
+    catch { }
     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");
@@ -173,7 +149,6 @@ const fs = require("node:fs"), crypto = require("node:crypto"), path = require("
   }
 })();
 `;
-/** 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`;
@@ -200,7 +175,6 @@ export function copyOffThread(source, folder, tag, now) {
         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)
@@ -209,7 +183,6 @@ export function liveCopyDue(store, now) {
     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))
@@ -229,7 +202,6 @@ export async function liveBackupPass(store, databaseFile, holder, forbidden, clo
         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);
@@ -245,7 +217,6 @@ export async function liveBackupPass(store, databaseFile, holder, forbidden, clo
         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();
@@ -265,7 +236,6 @@ export function startLiveBackups(store, databaseFile, forbidden, everyMs = 60_00
         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?.())]);
     };
 }