toolroll 0.9.104 → 0.9.105

package/dist/checkout-cleanup.js

@@ -1,29 +1,3 @@
-/**
- * Checkout cleanup (Settings → Storage, `toolroll storage clean`): which task checkouts can go, and removing them.
- *
- * A finished task's clean checkout goes as the setting says: when its task is complete or cancelled (the default),
- * 2 days or a week after that, or never (only a clean-up by hand). A clean-up by hand doesn't wait for the setting.
- * Only the working copy goes: its branch, and so every commit, stays, and a later lease of the branch makes a new one.
- *
- * Kept until idle (below): one whose task isn't finished (on hold, failed, a revision under way) and a result still
- * waiting for review. Always kept: a checkout in use, one with changes (files Toolroll wrote itself aside), and one
- * with commits on no branch. A release check's checkout (a deploy installs from it) goes once its task is complete, with its dependency
- * install and journey output, except the one deployed now and the project's newest complete one still waiting for its
- * deploy (no deploy since it was complete; at most a week). A superseded or cancelled gate goes at once, whatever its
- * task's state (staged releases keep the rollback copy). A checkout no task names (adopted after a crash) goes only
- * in a clean-up by hand. Every removal is in the ledger.
- *
- * Idle checkouts go too (the idle limit, 14 days by default): one whose whole task family has been idle that long (no
- * run, no person's act, no open lease) goes even with its result waiting for review or its task unfinished, in the
- * storage sweep's child only, never in a clean-up by hand, and only when `WorktreePool.proveRecreatable` says nothing is lost.
- * Nothing needs that working copy: a result page, Accept, Send back and Run checks read saved evidence and the branch,
- * and a retry, revision or resume leases the branch, which makes a new one. Excluded, because that can't be proven: a
- * release gate (a deploy installs from its checkout), work from an external tracker, and a checkout no task names. A
- * checkout with uncommitted changes is never removed by this; it is listed for a person.
- *
- * A kept checkout waiting for review or with changes drops its dependencies and build output once its run ends
- * (`slimKeptCheckouts`); the next run's setup restores them.
- */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
@@ -34,11 +8,8 @@ import { CLEANUP_CHOICES, IDLE_CHOICES, bytesWords, diskBytes, diskBytesAsync }
 import { checkoutIdle } from "./store.js";
 import { worktreePath } from "./worktree.js";
 const DAY_MS = 86_400_000;
-/** A release candidate's checkout holds the build a deploy installs: the newest complete one waits at most a week for it. */
 export const CANDIDATE_KEEP_MS = 7 * DAY_MS;
-/** The worker's pass removes at most this many; a clean-up by hand has no cap. */
 export const AUTO_MAX = 20;
-/** Git inspections at once. */
 const INSPECT_AT_ONCE = 8;
 export function deployedRelease(stateDir) {
     if (stateDir === null)
@@ -69,23 +40,16 @@ export function deployedRelease(stateDir) {
     }
     return newest === null ? null : { head: newest.head, run: newest.run, at: newest.at === "" ? null : newest.at };
 }
-/** The folder beside the database (where staged releases live), or null for a database in memory. */
 function stateDirOf(store) {
     const main = store.handle.prepare("PRAGMA database_list").all().find(row => row["name"] === "main");
     return typeof main?.["file"] === "string" && main["file"] !== "" ? dirname(main["file"]) : null;
 }
-/**
- * Which release a gate belongs to: a failed gate is re-filed as the same name plus a letter (`release-x`, then
- * `release-xb`, `release-xc` …), so a gate whose name is another gate's in the same project plus one letter is that
- * release's.
- */
 export function releaseOf(id, gates) {
     return /[b-z]$/.test(id) && gates.has(id.slice(0, -1)) ? id.slice(0, -1) : id;
 }
 const STRENGTH = { "in use": 5, "task not finished": 4, "waiting for review": 3, "release candidate": 2 };
 const strength = (one) => one === undefined ? -1 : one.keep === null ? 0 : STRENGTH[one.keep] ?? 1;
 const stronger = (a, b) => strength(b) > strength(a) || (strength(b) === 0 && strength(a) === 0 && (b.finishedAt ?? "") > (a.finishedAt ?? "")) ? b : a;
-/** Where every task stands for cleanup, by task_ref id and by each branch it or its runs used. */
 export function taskStatuses(store, now, deployed) {
     const db = store.handle;
     const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.updated_at AS updated_at,
@@ -95,7 +59,6 @@ export function taskStatuses(store, now, deployed) {
     FROM task_ref r LEFT JOIN task t ON t.id = r.external_id AND r.backend = 'built-in'`).all();
     const runs = db.prepare("SELECT id, task_ref, branch FROM run").all();
     const refOfRun = new Map(runs.map(row => [Number(row["id"]), Number(row["task_ref"])]));
-    // Release candidates: per project and release, the newest gate not cancelled; and the one deployed.
     const gates = refs.filter(row => row["candidate"] !== null);
     const gateIds = new Map();
     for (const row of gates) {
@@ -114,7 +77,6 @@ export function taskStatuses(store, now, deployed) {
     const deployedRef = live === null ? undefined : live.run !== null ? refOfRun.get(live.run) : undefined;
     const isDeployed = (row) => live !== null &&
         (Number(row["ref"]) === deployedRef || (live.head !== null && String(row["candidate"]) === live.head));
-    // The completion names its family's root; its run names the result it completes.
     const completed = new Map();
     const completedRef = new Map();
     for (const row of db.prepare("SELECT task_id, run_id, at FROM action_ledger WHERE action = ?").all(COMPLETION_ACTION)) {
@@ -129,8 +91,6 @@ export function taskStatuses(store, now, deployed) {
             completedRef.set(ref, at);
     }
     const completedAtOf = (row) => [completed.get(String(row["id"])), completedRef.get(Number(row["ref"]))].filter((one) => one !== undefined).sort().at(-1) ?? null;
-    // Per project, the newest complete gate (by when it was complete): the one a deploy may still be about to install.
-    // Once the project deployed after it was complete, it waits for nothing.
     const deployedRepo = deployedRef === undefined ? (live?.head == null ? undefined : gates.find(row => String(row["candidate"]) === live.head)?.["repo"]) : refs.find(row => Number(row["ref"]) === deployedRef)?.["repo"];
     const newestDone = new Map();
     for (const row of gates) {
@@ -155,7 +115,6 @@ export function taskStatuses(store, now, deployed) {
             status = { keep: "in use", taskId: id, finishedAt: null };
         else if (gate && isDeployed(row))
             status = { keep: "release candidate", taskId: id, finishedAt: updated };
-        // A superseded or cancelled gate goes at once, whatever its task's state: a newer gate (or none) is the release.
         else if (gate && (state === "cancelled" || newestGate.get(releaseKey(row)) !== ref))
             status = { keep: null, taskId: id, finishedAt: updated, atOnce: true };
         else if (state === null || Number(row["held"]) === 1 || (state !== "done" && state !== "cancelled"))
@@ -179,7 +138,6 @@ export function taskStatuses(store, now, deployed) {
         if (row["revision_of"] !== null)
             parentOf.set(id, String(row["revision_of"]));
     }
-    // A revision under way keeps what its ancestors worked on: it builds on their branch.
     for (const [id, status] of byId) {
         if (status.keep === null || status.keep === "release candidate")
             continue;
@@ -206,7 +164,6 @@ export function taskStatuses(store, now, deployed) {
     }
     return { byRef, byBranch };
 }
-/** Where one checkout's task stands: by its task, its branch, or (branch unknown) the name a lease of a branch would give it. */
 function statusOf(row, statuses) {
     let found = stronger(row.taskRef === null ? undefined : statuses.byRef.get(row.taskRef), statuses.byBranch.get(row.branch));
     if (found === undefined) {
@@ -217,8 +174,6 @@ function statusOf(row, statuses) {
     }
     return found;
 }
-/** The let-go checkouts whose task is complete or cancelled, and when it finished. Not a release candidate's that
- * stays: a deploy runs from it. */
 export function finishedCheckouts(store, now, repo) {
     const statuses = taskStatuses(store, now);
     return store.listWorktrees().filter(row => row.releasedAt !== null && row.runner === null && (repo === undefined || row.repo === repo)).flatMap(row => {
@@ -228,14 +183,8 @@ export function finishedCheckouts(store, now, repo) {
         return [{ row, taskId: status.taskId, finishedAt: status.finishedAt }];
     });
 }
-/** Toolroll's own bookkeeping about a task: none of it is anyone using the task. Every other ledger entry counts as activity. */
 const NOT_ACTIVITY = ["assignment status baseline", "assignment status observed", "task archived", "checkout removed", "checkout slimmed", "checkout processes stopped",
     "run processes stopped", "orphan process stopped", "process observation failed", "process witness settled", "branch deleted", "landed work cleaned up"];
-/**
- * When each task family last saw a run, a person's act or a lease, read in one pass. A revision builds on what it
- * revises, so a family is idle together. `blocked`: an open run, an unreleased claim, a release gate, or a task only an
- * external tracker knows, in the family.
- */
 export function idleFacts(store) {
     const db = store.handle;
     const refs = db.prepare(`SELECT r.id AS ref, r.external_id AS id, r.revision_of AS revision_of, t.state AS state, t.created_at AS created_at, t.updated_at AS updated_at,
@@ -302,7 +251,6 @@ export function idleFacts(store) {
     const byRef = new Map();
     for (const [ref, root] of rootByRef)
         byRef.set(ref, families.get(root));
-    // A branch answers for every family that used it: the newest activity and any block among them.
     const byBranch = new Map();
     const share = (branch, root) => {
         const one = families.get(root), seen = byBranch.get(branch);
@@ -315,11 +263,9 @@ export function idleFacts(store) {
         share(branch, root);
     return { byRef, byBranch };
 }
-/** The idle limit in days as it stands: null when idle cleanup is off (the limit, or automatic cleanup altogether). */
 function idleDays(store) {
     return store.checkoutCleanup() === "never" ? null : IDLE_CHOICES.find(one => one.value === checkoutIdle(store)).days;
 }
-/** When this checkout's task last saw activity, when that is past the limit and only its task's standing keeps it; else null. */
 function idleSince(pool, row, statuses, facts, days, now) {
     if (days === null || row.taskRef === null || row.branch === "unknown" || row.releasedAt === null || row.runner !== null || pool.inUse(row.path).held)
         return null;
@@ -332,11 +278,9 @@ function idleSince(pool, row, statuses, facts, days, now) {
     const since = [own.activeAt, shared?.activeAt, row.createdAt, row.leasedAt, row.releasedAt].filter((one) => typeof one === "string").sort().at(-1);
     return Date.parse(since) + days * DAY_MS <= now.getTime() ? since : null;
 }
-/** Every commit a task's runs recorded on this checkout or its branch: what `proveRecreatable` must find on a branch. */
 function recordedHeads(store, row) {
     return store.handle.prepare("SELECT DISTINCT head_revision AS head FROM run WHERE (branch = ? OR worktree = ?) AND head_revision IS NOT NULL").all(row.branch, row.path).map(one => String(one["head"]));
 }
-/** Why a checkout stays before anyone looks at its files, or null: it may go (as far as its task and the setting say). */
 function keptFor(pool, row, statuses, now, cleanup) {
     const status = statusOf(row, statuses);
     const taskId = status?.taskId ?? null;
@@ -346,7 +290,6 @@ function keptFor(pool, row, statuses, now, cleanup) {
         return { why: status.keep, taskId, ...(status.dueAt === undefined ? {} : { dueAt: status.dueAt }) };
     if (cleanup === "manual")
         return { why: null, taskId };
-    // A checkout no task names (adopted after a crash, say) has no task to finish: only a clean-up by hand takes it.
     if (status === undefined)
         return { why: "no task", taskId };
     if (cleanup === "finished")
@@ -360,7 +303,6 @@ function keptFor(pool, row, statuses, now, cleanup) {
     const dueAt = new Date(Date.parse(since) + days * DAY_MS).toISOString();
     return dueAt > now.toISOString() ? { why: "not due yet", taskId, dueAt } : { why: null, taskId };
 }
-/** Why a checkout stays as a clean-up by hand reads it (in use, or its task not done with it), before its files; null: it may go. */
 export function checkoutKeepWhy(pool, row, statuses, now) {
     return keptFor(pool, row, statuses, now, "manual").why;
 }
@@ -375,10 +317,6 @@ async function eachAtMost(items, limit, work) {
     }));
     return out;
 }
-/**
- * What a clean-up would remove now, how much space it would free, and what stays and why. `manual` is a clean-up by
- * hand (it doesn't wait for the setting); otherwise it is the worker's pass under the setting. Reads only.
- */
 export async function checkoutPlan(store, pool, now, options) {
     const cleanup = store.checkoutCleanup();
     const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo));
@@ -412,27 +350,17 @@ export async function checkoutPlan(store, pool, now, options) {
         idleCount: idle.length, idleBytes: idle.reduce((sum, one) => sum + one.bytes, 0),
     };
 }
-/** Names exactly what a preview would remove, so a confirmation removes that and nothing else. */
 export function previewDigest(plan) {
     return createHash("sha256").update(plan.go.map(one => one.path).sort().join("\u0000"), "utf8").digest("hex").slice(0, 32);
 }
-/**
- * Remove what may go: the worker's pass (`manual` false: under the setting, at most AUTO_MAX, one repository) or a
- * clean-up by hand (no cap, every repository). Each checkout is asked again right before it goes; each removal is in
- * the ledger. Idle checkouts go only with `idle`, the storage sweep's child (never the service's own pass, whose git
- * and du must not hold up its heartbeats): each is judged again from a fresh read of its task and its family's
- * activity, `spare` (live work), the OS's list of what runs in the folder, and `proveRecreatable`, inside its reservation.
- */
 export async function cleanCheckouts(store, pool, now, options) {
     const cleanup = store.checkoutCleanup();
     if (!options.manual && cleanup === "never")
         return { removed: [], kept: [], freed: 0 };
-    // `only`: the checkouts a person saw in the preview; nothing they didn't see goes.
     const rows = store.listWorktrees().filter(row => existsSync(row.path) && (options.repo === undefined || row.repo === options.repo) && (options.only === undefined || options.only.has(row.path)));
     let statuses = taskStatuses(store, now());
     const days = options.idle === undefined ? null : idleDays(store);
     let facts = days === null ? { byRef: new Map(), byBranch: new Map() } : idleFacts(store);
-    // The checkouts going for being idle, and since when: judged at every look, so a task coming back drops out.
     const idle = new Map();
     const mayGo = (row) => {
         idle.delete(row.path);
@@ -448,15 +376,11 @@ export async function cleanCheckouts(store, pool, now, options) {
         facts = idleFacts(store); };
     const sizes = new Map();
     const wanted = (row, fresh) => {
-        // Right before a checkout goes, where its task stands is read afresh, and its size taken for the ledger.
-        // `spare`: live work uses it (storage-sweep.ts), asked at both looks.
         if (fresh)
             refresh();
         const go = mayGo(row);
         if (go && fresh) {
             sizes.set(row.path, diskBytes([row.path]).get(row.path) ?? 0);
-            // du can be slow. The reservation excludes a concurrent checkout lease, and this last read also catches
-            // an open run/claim or task change that arrived while size was measured in the sweep child.
             refresh();
             return mayGo(row) && !(idle.has(row.path) && options.idle?.occupied(row.path) === true);
         }
@@ -476,13 +400,7 @@ export async function cleanCheckouts(store, pool, now, options) {
     }
     return { removed, kept: pruned.kept, freed: removed.reduce((sum, one) => sum + one.bytes, 0), ...(pruned.removed.length >= max ? { more: true } : {}) };
 }
-/** Checkouts this process already looked at since they were let go (path and release time): looked at once. */
 const looked = new Set();
-/**
- * A kept checkout (its result waiting for review, or with changes) drops its dependencies and build output once its
- * run has ended; the next run's setup restores them (node_modules only goes where the project has a setup to restore
- * it). Never one in use or a release candidate (a deploy installs from it). Each in the ledger.
- */
 export async function slimKeptCheckouts(store, pool, now, options) {
     const rows = store.listWorktrees().filter(row => row.releasedAt !== null && row.runner === null && (options.repo === undefined || row.repo === options.repo)
         && !looked.has(`${row.path}\u0000${row.releasedAt}`) && existsSync(row.path));
@@ -511,7 +429,6 @@ export async function slimKeptCheckouts(store, pool, now, options) {
     }
     return { slimmed };
 }
-/** Throw away a checkout kept for its changes, on purpose; its branch stays. In the ledger. */
 export async function discardCheckout(store, pool, path, now, actor) {
     const bytes = existsSync(path) ? diskBytes([path]).get(path) ?? 0 : 0;
     const done = await pool.discardChanges(path);
@@ -522,7 +439,6 @@ export async function discardCheckout(store, pool, path, now, actor) {
         detail: `${basename(path)} and its uncommitted changes (about ${bytesWords(bytes)}); branch ${done.row.branch} kept` });
     return { ok: true, bytes };
 }
-/** "Waiting for review", "Has changes" … as a sentence fragment for a person. */
 export function whyWords(item) {
     switch (item.why) {
         case null: return "goes";

package/dist/checkout-proof.js

@@ -1,9 +1,3 @@
-/**
- * A running attempt's checkout, proved to be on this machine (docs/plans/agents-cockpit.md phase E): the run is live
- * under the task's current claim, its worktree row is this machine's runner's and this task's, and the path is its own
- * real path, a directory inside this machine's pool. Used to offer "copy the cd command" and "Show in Finder" — and
- * proved again immediately before Finder is asked to reveal it. Nothing is ever launched in it.
- */
 import { execFile } from "node:child_process";
 import { lstatSync, realpathSync } from "node:fs";
 export function localCheckoutOf(store, runId, local, now) {
@@ -17,12 +11,10 @@ export function localCheckoutOf(store, runId, local, now) {
     const row = store.getWorktree(run.worktree);
     if (row === null || row.taskRef !== run.taskRef)
         return { ok: false, reason: "the checkout isn't where the record says" };
-    // The run, its worktree row and this machine all name the same runner: an inconsistent record fails closed.
     if (run.runner !== local.runner || row.runner !== local.runner)
         return { ok: false, reason: "this attempt runs on another computer" };
     try {
         const real = realpathSync(run.worktree), pool = realpathSync(local.poolRoot);
-        // Strictly inside: the pool directory itself is never a checkout.
         if (real !== run.worktree || !real.startsWith(`${pool}/`) || !lstatSync(real).isDirectory())
             return { ok: false, reason: "the checkout isn't inside this machine's pool" };
         return { ok: true, path: real };
@@ -37,15 +29,13 @@ export function revealInFinder(path, run = (file, args, options, done) => execFi
     return new Promise(resolve => {
         let settled = false;
         let child;
-        // The deadline is a moment on a monotonic clock, not the timer having run: a success that arrives after it (even
-        // ahead of an overdue timer, in a stalled event loop) is "not shown".
         const due = clock() + deadlineMs;
         const finish = (shown) => { if (settled)
             return; settled = true; clearTimeout(timer); resolve(shown); };
         const timer = setTimeout(() => { finish(false); try {
             child?.kill("SIGKILL");
         }
-        catch { /* already gone */ } }, deadlineMs);
+        catch { } }, deadlineMs);
         try {
             child = run(REVEAL_COMMAND, ["-R", path], { cwd: "/", env: { PATH: "/usr/bin:/bin" } }, error => finish(error === null && clock() < due));
         }
@@ -54,9 +44,7 @@ export function revealInFinder(path, run = (file, args, options, done) => execFi
         }
     });
 }
-/** Whether this console can ask Finder at all (a Mac, or a test's own revealer). */
 export const canReveal = (injected) => injected || process.platform === "darwin";
-/** The command to paste into a terminal: `cd` to the path as one single-quoted shell word (a quote inside escaped). */
 export function cdCommandOf(path) {
     return `cd '${path.replaceAll("'", `'\\''`)}'`;
 }

package/dist/child-database.js

@@ -3,11 +3,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { envTwins } from "./names.js";
 export const CHILD_DATABASE_ENV = "TOOLROLL_DB";
-/** Both names, so neither an ambient TOOLROLL_DB nor an older tool reading STANDING_ORDERS_DB reaches the live store. */
 export function childDatabaseEnv(file) {
     return envTwins("DB", file);
 }
-/** Self-hosted agents and project commands must not open their supervisor's store. */
 export function isolatedChildDatabase(label) {
     const dir = mkdtempSync(join(tmpdir(), `toolroll-${label}-`));
     return { dir, file: join(dir, "orders.db") };
@@ -15,7 +13,6 @@ export function isolatedChildDatabase(label) {
 export function removeChildDatabase(dir) {
     rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
 }
-/** Override after environment filtering, even if an ambient override names the live DB. */
 export async function runWithIsolatedDatabase(runner, file, args, options) {
     const isolated = isolatedChildDatabase("check");
     try {