toolroll 0.9.93 → 0.9.94

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.94 — 2026-11-07
+
+- **Small tasks start in one step.** For small work you start yourself, New
+  task shows the exact terms and **Build** is your approval. If the change
+  grows past small, Toolroll stops and asks you to approve it to keep it.
+  In the terminal: `toolroll task new "<what should change>" --repo <project>`.
+- **Start a task from a GitHub issue or pull request.** Paste the link in New
+  task, or use `toolroll task new --from <url>`. Toolroll quotes the text as
+  written outside Toolroll, and you read it before filing it.
+- **Needs you now holds only what needs you.** Things that are simply waiting
+  say what they wait for, and the task page, chat, the terminal and pings all
+  say the same sentence. Pings are one line with one button ("#41 is ready to
+  review").
+- **Fewer pages and fewer words.** Home has Needs you, Running and Waiting;
+  Tasks is the one list. Old links still land in the right place. A result has
+  Accept, Send back and Retry; a plan has Approve, Request changes and Reject.
+  One set of keyboard shortcuts works in the console and the terminal.
+- **"Can I merge?"** One checklist on each task: plan, build, checks,
+  requirements, pull request, review comments and release check.
+- **A code map for each project.** `/projects/<name>/map` and `toolroll map`
+  show the areas, files and exports of your main branch, generated by Toolroll
+  itself with no agent or model. Builds and the lead can read it, and the page
+  reports how builds with the map compare to builds without it. Turn it off
+  per project in its settings.
+- **Flaky tests**: each project lists tests with mixed outcomes under recorded
+  conditions, from local checks and GitHub CI re-runs, with history and one
+  action, "Make a task to fix it". `toolroll flaky list|show`. Read only:
+  nothing is rerun and no check changes.
+- **Lesson notes**: when a revision passes a test that failed, Toolroll
+  proposes a note with what was recorded. You put it in your own words and
+  accept it as a decision, then see how often that test fails afterwards.
+- **Last included in a run** on lessons, references and decisions, and
+  decisions now reach runs in projects with no other knowledge.
+- **Clean up** in Settings → Knowledge proposes retiring, merging or settling
+  memory entries. Nothing changes until you accept, and restore and undo merge
+  are there when you change your mind. `toolroll memory tidy|restore|unmerge`.
+- **Toolroll cleans up task folders nobody is using.** A task idle for 14
+  days now loses its working folder even if its result is still waiting for
+  review or the task never finished, as long as nothing would be lost: no
+  uncommitted changes, every commit on its branch, nothing running in it.
+  Reviewing, Accept, Send back, Run checks, Retry and Resume all keep working;
+  the next run makes the folder again from its branch. Choose 7, 14 or 30
+  days or never in Settings → Storage, or with
+  `toolroll storage cleanup idle <days>`. `toolroll storage` shows what the
+  next sweep would free.
+- **Folders with uncommitted changes are listed, never removed.** Settings →
+  Storage and `toolroll storage` now show them so you can decide. Storage
+  calls these "task folders" now.
+- **Builds that vanish recover on their own, within limits.** A lost build
+  counts once and retries up to three times. Past that, or with no budget left,
+  the task stops and says why.
+- **A missing check verdict gets one automatic recheck** of that exact commit,
+  with no agent, instead of waiting for you.
+- **The builder comes back after a crash.** Toolroll restarts it only if you
+  left it on and it can prove the old process is gone. If you turned it off, it
+  stays off.
+- **A changed route is one Approve.** When a task's model route changed since
+  you approved, you see one line saying what changed and approve once.
+- **One release command.** `toolroll release <branch>` works out the next step,
+  picks up what a stopped deploy left, and updates a branch that is behind main.
+- **Toolroll knows which computer it is on, even if the network renames it.**
+  A release no longer waits forever on "the computer that ran build #N".
+- **Checks say how they ran.** Each check launch records its sandbox, and the
+  result page and release card show it. A check with no record reads unknown and
+  is never carried forward as sandboxed.
+
 ## 0.9.93 — 2026-11-06
 
 - **Approve a release with one tap.** When a release is ready for your yes,

package/dist/activity-line.d.ts

@@ -3,9 +3,10 @@
  * 40 s ago". Pure and shared: the server sends the facts, and each page words
  * them against its own clock, so the age keeps counting between reads.
  *
- * After five minutes with no word the line turns amber and says so; a worker
- * whose heartbeat stopped says that instead, because a quiet agent and a
- * machine that went away need different help.
+ * After five minutes with no word the line says when it last heard, in the
+ * same quiet secondary text (a quiet agent isn't something a person must do;
+ * amber is for what needs you). A worker whose heartbeat stopped says that
+ * instead, and that one is marked: the builder going away needs a person.
  */
 /** The facts behind the line: our own words for the last thing done (never a tool's arguments), when, and whether
  * the worker running it still answers. */
@@ -19,8 +20,10 @@ export declare const QUIET_AFTER_MS: number;
 export declare const ACTIVITY_WORDS: Readonly<Record<string, string>>;
 /** "just now", "40 s ago", "3 min ago", "2 h ago". */
 export declare function agoWords(ms: number): string;
-/** The line itself, and whether it is quiet (amber): silent five minutes or more, or the worker is offline. */
+/** The line itself. `quiet` (marked): the worker is offline, which needs a person. `stale`: silent five minutes or
+ * more, said in the same neutral words as any other update. */
 export declare function activityLine(activity: RunActivity, now: number): {
     text: string;
     quiet: boolean;
+    stale: boolean;
 };

package/dist/activity-line.js

@@ -3,9 +3,10 @@
  * 40 s ago". Pure and shared: the server sends the facts, and each page words
  * them against its own clock, so the age keeps counting between reads.
  *
- * After five minutes with no word the line turns amber and says so; a worker
- * whose heartbeat stopped says that instead, because a quiet agent and a
- * machine that went away need different help.
+ * After five minutes with no word the line says when it last heard, in the
+ * same quiet secondary text (a quiet agent isn't something a person must do;
+ * amber is for what needs you). A worker whose heartbeat stopped says that
+ * instead, and that one is marked: the builder going away needs a person.
  */
 export const QUIET_AFTER_MS = 5 * 60_000;
 /** The words for each fixed activity kind (live.ts's vocabulary) and for a progress checkpoint. */
@@ -35,13 +36,14 @@ export function agoWords(ms) {
         return `${minutes} min ago`;
     return `${Math.floor(minutes / 60)} h ago`;
 }
-/** The line itself, and whether it is quiet (amber): silent five minutes or more, or the worker is offline. */
+/** The line itself. `quiet` (marked): the worker is offline, which needs a person. `stale`: silent five minutes or
+ * more, said in the same neutral words as any other update. */
 export function activityLine(activity, now) {
     const at = Date.parse(activity.at);
     const since = Number.isNaN(at) ? 0 : Math.max(0, now - at);
     if (activity.worker === "offline")
-        return { text: `Worker offline · last word ${agoWords(since)}`, quiet: true };
+        return { text: `Worker offline · last word ${agoWords(since)}`, quiet: true, stale: false };
     if (since >= QUIET_AFTER_MS)
-        return { text: `No word for ${Math.floor(since / 60_000)} min`, quiet: true };
-    return { text: `${activity.what} · ${agoWords(since)}`, quiet: false };
+        return { text: `Last update ${agoWords(since)}`, quiet: false, stale: true };
+    return { text: `${activity.what} · ${agoWords(since)}`, quiet: false, stale: false };
 }

package/dist/agent-fence.d.ts

@@ -90,6 +90,8 @@ export type FenceGrants = {
     pool?: CheckoutPool;
     network?: NetworkFence;
     writes?: WriteAllowlist;
+    /** Which `readable` entries are one exact file: read with no listing of its folder, so a sibling stays denied. */
+    exactFiles?: string[];
     /** Policy v1: the home configuration names denied by name, present or not (TaskBoundary.homeNames). */
     homeNames?: string[];
     /** macOS: the project's sealed mach services beyond the runtime's baseline (its `allowMachLookup`). */
@@ -359,6 +361,8 @@ export type FenceKind = "build" | "command" | "check" | "flow" | "tool-server";
  * with no checkout), so no caller forgets one; every path comes from Toolroll's own records, never from the checkout.
  */
 export type FenceContext = {
+    /** One exact file read back inside the fence (a build's code map), or null. */
+    exactFile?: string | null;
     databaseFile: string | null;
     worktree: string | null;
     boundary: TaskBoundary | null;

package/dist/agent-fence.js

@@ -1006,7 +1006,7 @@ export function srtTermsOf(fence, grants = NO_GRANTS) {
     const denyRead = new Set(fence.map(real));
     // A readable grant's own folder is read too: bundlers (esbuild) find node_modules by listing it. The runtime can't
     // grant a listing without the folder's files, so the shared copy's folder is read whole (its ready note among them).
-    const allowRead = new Set(grants.readable.flatMap(path => [real(path), real(dirname(path))]));
+    const allowRead = new Set(grants.readable.flatMap(path => grants.exactFiles?.includes(path) === true ? [real(path)] : [real(path), real(dirname(path))]));
     const denyWrite = new Set([...fence, ...grants.readOnly].map(real));
     for (const path of grants.writeDenies ?? [])
         denyWrite.add(path);
@@ -1180,9 +1180,12 @@ export function fenceFor(kind, ctx) {
     // launches: rewriting the code that fences a build would switch the fence off.
     const made = { ...found, readOnly: [...new Set([...found.readOnly, ...toolrollInstall(ctx.worktree, ctx.home ?? homedir(), ctx.binding?.main ?? null)])].sort() };
     const written = ctx.writes ?? null;
+    const exact = ctx.exactFile ?? null;
     const grants = {
         ...made,
         ...(written === null ? {} : { writes: written.writes, readOnly: [...new Set([...made.readOnly, ...written.readOnly])].sort() }),
+        // One exact file, granted as the shared dependencies are, and never written (Claude's Edit rules read `readOnly`).
+        ...(exact === null ? {} : { readable: [...made.readable, exact], exactFiles: [exact], readOnly: [...new Set([...made.readOnly, ...(written?.readOnly ?? []), exact])].sort() }),
         ...(ctx.network === undefined ? {} : { network: ctx.network }),
         ...(ctx.machLookup === undefined || ctx.machLookup.length === 0 ? {} : { machLookup: [...ctx.machLookup] }),
         // A project's checks may drive a browser (Playwright's Chromium), and so may a flow's script zone whose browser use

package/dist/approval-authority.d.ts

@@ -1,7 +1,13 @@
 /** SQL over a `task_scope` alias and a repo expression: whether that row's approval authority stands at `now` (an SQL
- * expression, used exactly three times: the mode and grant clauses, and the release's expiry). It never asks whether the row is approved.
+ * expression, used exactly four times: the mode and grant clauses, the release's expiry and a fast start's window). It never asks whether the row is approved.
  * COALESCE: a NULL basis would make the OR chain NULL, and NOT NULL reads as "not dead"; NULL stands on nothing. */
 export declare function authorityStandsSql(scope: string, repo: string, now: string): string;
+/**
+ * SQL, conjunctive with every alternative above (plain-toolroll.md P2.4): narrow only. A fast start's seal dispatches only
+ * inside its start window, and only as what it claims to be: a person's own ceremony yes to these exact bytes, proved at
+ * the seal's instant. Losing the marker leaves an ordinary person approval; nothing here grants anything.
+ */
+export declare function fastStartStandsSql(scope: string, now: string): string;
 /**
  * SQL, conjunctive with every alternative above (results routing slice 3): a task whose sealed route tries a cheaper
  * model (its build leg's selection is a trial) stands only on a PERSON's own yes to these exact bytes — the ceremony

package/dist/approval-authority.js

@@ -18,7 +18,7 @@ import { autoSealSql } from "./release-authority.js";
 /** The proofs a person gives (src/person-proof.ts), as an SQL list. */
 const PERSON_PROOFS = "('password-now', 'sso-now', 'fresh-password', 'fresh-sso', 'session', 'cli-login', 'chat', 'passkey', 'local-owner')";
 /** SQL over a `task_scope` alias and a repo expression: whether that row's approval authority stands at `now` (an SQL
- * expression, used exactly three times: the mode and grant clauses, and the release's expiry). It never asks whether the row is approved.
+ * expression, used exactly four times: the mode and grant clauses, the release's expiry and a fast start's window). It never asks whether the row is approved.
  * COALESCE: a NULL basis would make the OR chain NULL, and NOT NULL reads as "not dead"; NULL stands on nothing. */
 export function authorityStandsSql(scope, repo, now) {
     return `COALESCE((((COALESCE(${scope}.approval_basis, '') IN ('password', 'chat') AND NOT ${machineSealSql(scope)}
@@ -31,9 +31,18 @@ export function authorityStandsSql(scope, repo, now) {
     OR (${scope}.approval_basis = 'grant' AND ${grantStandsSql(`${scope}.mode_digest`, now, repo)})
     OR (${scope}.approval_basis = 'schedule' AND ${approverStandsSql(scope, repo)})
     OR (${scope}.approval_basis IN ('auto-check', 'auto-green') AND ${autoSealSql(scope, repo)} AND ${approverStandsSql(scope, repo)}))
-    AND ${releaseStandsSql(scope, now)} AND ${localSealStandsSql(scope, repo)}
+    AND ${releaseStandsSql(scope, now)} AND ${localSealStandsSql(scope, repo)} AND ${fastStartStandsSql(scope, now)}
     AND (instr(COALESCE(${scope}.approved_route_json, ''), '"trial"') = 0 OR ${trialSealStandsSql(scope)})), 0)`;
 }
+/**
+ * SQL, conjunctive with every alternative above (plain-toolroll.md P2.4): narrow only. A fast start's seal dispatches only
+ * inside its start window, and only as what it claims to be: a person's own ceremony yes to these exact bytes, proved at
+ * the seal's instant. Losing the marker leaves an ordinary person approval; nothing here grants anything.
+ */
+export function fastStartStandsSql(scope, now) {
+    return `NOT EXISTS (SELECT 1 FROM task_ref fsr WHERE fsr.backend = 'built-in' AND fsr.external_id = ${scope}.task_id AND fsr.fast_start_until IS NOT NULL
+      AND (fsr.fast_start_until <= ${now} OR COALESCE(${scope}.approval_basis, '') <> 'password' OR ${machineSealSql(scope)} OR NOT ${personSealSql(scope)}))`;
+}
 /**
  * SQL, conjunctive with every alternative above (results routing slice 3): a task whose sealed route tries a cheaper
  * model (its build leg's selection is a trial) stands only on a PERSON's own yes to these exact bytes — the ceremony

package/dist/approval-password.d.ts

@@ -0,0 +1,31 @@
+import type { Scope } from "./scope.js";
+import type { Store } from "./store.js";
+export type ApprovalPasswordField = {
+    field: "none";
+    why: "passwordless" | "local-owner";
+} | {
+    field: "remembered";
+    since: string;
+} | {
+    field: "required";
+} | {
+    field: "local-refused";
+    message: string;
+    href: string;
+    action: string;
+};
+export type ApprovalPasswordFacts = {
+    /** The approver. */
+    name: string;
+    taskId: string;
+    scope: Scope;
+    /** Passwordless is on for this browser session (html.ts passwordlessRendering). */
+    passwordless: boolean;
+    /** The request is this laptop's local owner (easy-start C5). */
+    localOwner: boolean;
+    /** When a password was last typed on this session, if it may still stand (scope.ts freshnessFor), else null. */
+    freshAt: number | null;
+    /** Where a refused local owner goes back to. */
+    returnTo: string;
+};
+export declare function approvalPasswordField(store: Store, facts: ApprovalPasswordFacts): ApprovalPasswordField;

package/dist/approval-password.js

@@ -0,0 +1,26 @@
+/** When an approval form asks for a password (docs/plans/plain-toolroll.md P1.3): one function every approve form reads,
+ * so the task page, the focused chat and the shared-action review never disagree. It only decides what a form shows;
+ * approve() proves the person, the freshness, the local owner and the digest again inside its own transaction, with
+ * the same two rules this reads (freshlyApprovable, localApprovalEligible).
+ *
+ * - `none`: Passwordless is on for this session, or this computer's local owner may approve this exact work.
+ * - `remembered`: a password typed on this session in the last fifteen minutes may stand for these terms; the field
+ *   shows, and may be left empty.
+ * - `required`: a password typed now: protected or escalated work, terms an agent wrote, or nothing remembered.
+ * - `local-refused`: a local owner who can't approve this here, with where to go instead. */
+import { freshlyApprovable, localApprovalEligible } from "./scope.js";
+import { localOwnerRefusal } from "./local-owner.js";
+export function approvalPasswordField(store, facts) {
+    if (facts.localOwner) {
+        if (localApprovalEligible(store, facts.name, facts.taskId).ok)
+            return { field: "none", why: "local-owner" };
+        return { field: "local-refused", ...localOwnerRefusal(store.accountOf(facts.name)?.passwordSet === true, facts.returnTo) };
+    }
+    if (facts.passwordless)
+        return { field: "none", why: "passwordless" };
+    if (facts.freshAt === null)
+        return { field: "required" };
+    const gate = store.approvalGate(facts.taskId, facts.name, "person");
+    return freshlyApprovable(store, facts.taskId, facts.scope, gate.verdict === "seal" && !gate.protectedWork)
+        ? { field: "remembered", since: new Date(facts.freshAt).toISOString() } : { field: "required" };
+}

package/dist/assignment-ui.js

@@ -63,7 +63,7 @@ export function assignmentAttemptsOf(assignment) {
 export function assignmentAttemptsHtml(assignment) {
     if (assignment.attempts.length === 0)
         return html ``;
-    return html `<details class="assignment-attempts"><summary>Attempts <span class="meta">${assignment.attempts.length}</span></summary><ol>${assignmentAttemptsOf(assignment).map(attempt => html `<li data-attempt-task="${attempt.taskId}" data-history-version="${attempt.taskId}"><a href="${attempt.href}">${attempt.label}</a>${attempt.runId === null ? '' : html ` <a href="/r/${attempt.runId}">Run #${attempt.runId}</a>`}${attempt.detail === null ? '' : html `<p class="meta">${attempt.detail}</p>`}</li>`)}</ol>${assignment.owner === null ? '' : html `<p class="meta">Lead: ${assignment.owner.label}${assignment.owner.active ? '' : ' · access ended'}</p>`}<p class="work-meta work-id">Task <span class="mono">${assignment.rootId}</span></p></details>`;
+    return html `<details class="assignment-attempts"><summary>Attempts <span class="meta">${assignment.attempts.length}</span></summary><ol>${assignmentAttemptsOf(assignment).map(attempt => html `<li data-attempt-task="${attempt.taskId}" data-history-version="${attempt.taskId}"><a href="${attempt.href}">${attempt.label}</a>${attempt.runId === null ? '' : html ` <a href="/r/${attempt.runId}">Build #${attempt.runId}</a>`}${attempt.detail === null ? '' : html `<p class="meta">${attempt.detail}</p>`}</li>`)}</ol>${assignment.owner === null ? '' : html `<p class="meta">Lead: ${assignment.owner.label}${assignment.owner.active ? '' : ' · access ended'}</p>`}<p class="work-meta work-id">Task <span class="mono">${assignment.rootId}</span></p></details>`;
 }
 /** Only recognized storage limits and explicitly identified older records are
  * secondary. Unknown findings and damaged current material stay in view. */

package/dist/assignment.js

@@ -1,6 +1,7 @@
 /** One assignment follows the existing task family. It owns no execution,
  * approval or proof state. Lead ownership and exact receipt acknowledgments
  * are append-only actions; handoffs use the existing durable outbox. */
+import { fastCompletionProblem } from "./fast-start.js";
 import { createHash } from "node:crypto";
 import { currentActor, withActor } from "./actor.js";
 import { replacedWords } from "./task-status.js";
@@ -496,6 +497,10 @@ function acknowledgeCurrent(store, current, receiptDigest, actor, now, root, acc
     // token, a remote API run) that may complete ordinary work but is never the second person on protected work.
     const person = actor.startsWith("operator:") && !machineActing() ? actor.slice("operator:".length) : null;
     const marked = actor.startsWith("operator:") ? (person === null ? COMPLETION_BY_MACHINE : COMPLETION_BY_PERSON) : null;
+    // A fast start's Accept backstop (fast-start.ts): a person only, and only a change that stayed small.
+    const grown = fastCompletionProblem(store, receipt.taskId, receipt.runId, person);
+    if (grown !== null)
+        return { ok: false, reason: "not-ready", message: grown };
     if (current.state !== "complete") {
         // The one readiness guard: a failed or missing required check, an unresolved requirement or HIGH finding refuses.
         const blockers = current.readiness?.blockers ?? [];

package/dist/boot-identity.d.ts

@@ -48,10 +48,11 @@ export declare function injectBootIdentity(identity: BootIdentity | null): void;
 export type BootWitness = {
     host: string;
     bootId: string | null;
+    machineId?: string | null;
 };
 /**
  * THE ONE RULE (plan §login/reboot recovery): a witnessed process is
- * proven dead by boot change only when the witness names THIS host, the
+ * proven dead by boot change only when the witness names THIS machine (isThisMachine), the
  * witness carries a well-formed boot id, this host's current boot id is
  * well-formed and known, and the two differ. Same boot, a legacy witness
  * without an id, a foreign host, an unknown or malformed current id — each

package/dist/boot-identity.js

@@ -21,7 +21,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { hostname } from "node:os";
+import { isThisMachine } from "./machine-identity.js";
 /** RFC 4122 shape, any case; the kernel tokens are exactly this. */
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Normalize a candidate token: exactly one UUID, lower-cased; anything else is malformed. */
@@ -79,15 +79,17 @@ export function injectBootIdentity(identity) {
 }
 /**
  * THE ONE RULE (plan §login/reboot recovery): a witnessed process is
- * proven dead by boot change only when the witness names THIS host, the
+ * proven dead by boot change only when the witness names THIS machine (isThisMachine), the
  * witness carries a well-formed boot id, this host's current boot id is
  * well-formed and known, and the two differ. Same boot, a legacy witness
  * without an id, a foreign host, an unknown or malformed current id — each
  * answers false, and the caller keeps its PID probe or its refusal.
  */
 export function provenDeadByBootChange(witness, current = { bootId: currentBootId() }) {
-    const host = current.host ?? hostname();
-    if (witness.host !== host)
+    // A caller naming the host compares exactly (restart certification, tests); otherwise THIS machine is decided by
+    // its stable id, or for a witness without one by this machine's own names (machine-identity.ts), never by the
+    // network hostname alone: a boot id from another machine always differs from ours.
+    if (current.host !== undefined ? witness.host !== current.host : !isThisMachine(witness))
         return false;
     if (witness.bootId === null || current.bootId === null)
         return false;

package/dist/bounded-spawn.d.ts

@@ -0,0 +1,57 @@
+export type BoundedStart = {
+    pid: number;
+    pgid: number;
+    startedAt: string | null;
+};
+export type BoundedOptions = {
+    cwd: string;
+    /** The child's whole environment. */
+    env: Record<string, string>;
+    label: string;
+    stdin?: Buffer;
+    timeoutMs: number;
+    /** Past this the tree is killed (`killed: "output"`). */
+    maxStdout: number;
+    /** Kept to this many bytes; more is dropped. */
+    maxStderr: number;
+    memoryBytes?: number;
+    diskBytes?: number;
+    /** The largest file any process may write (RLIMIT_FSIZE). */
+    fileBytes?: number;
+    /** The folder whose total `diskBytes` bounds. */
+    folder?: string;
+    onStart?: (started: BoundedStart) => void;
+    sampleMs?: number;
+};
+export type BoundedResult = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: Buffer;
+    stderr: string;
+    killed: "time" | "memory" | "disk" | "output" | null;
+    enforced: "system" | "checked";
+    peakBytes: number;
+};
+export type BoundedRunner = (file: string, args: readonly string[], options: BoundedOptions) => Promise<BoundedResult>;
+/** Tests: forget the probed machine. */
+export declare function resetBoundedContainmentForTests(): void;
+/** A process's own start time, as `ps` reports it: what tells a live process from a reused pid. */
+export declare function processStartedAt(pid: number): string | null;
+/** The folder's total size, without following a link. */
+export declare function folderBytes(folder: string): number;
+export declare const boundedRun: BoundedRunner;
+export type SpawnRecord = {
+    pid: number | null;
+    pgid: number | null;
+    startedAt: string | null;
+    folder: string | null;
+};
+/**
+ * What a crashed build left: its group is killed only if the leader is still the process recorded (the pid and its start
+ * time, so a reused pid isn't killed), and its folder goes if it sits under `root`. On Linux the cgroup janitor has
+ * done this already.
+ */
+export declare function cleanupLeftover(record: SpawnRecord, root: string): {
+    killed: boolean;
+    removed: boolean;
+};

package/dist/bounded-spawn.js

@@ -0,0 +1,220 @@
+/**
+ * One bounded child process tree, for work on a repository's untrusted bytes (docs/plans/code-map.md §1). What is
+ * guaranteed depends on the platform, and the result says which:
+ *
+ *   Linux with a delegated cgroup, Windows   the OS object (containment.ts, policy `preferred`) holds the memory limit,
+ *                                            and dies with the worker. `enforced: "system"`.
+ *   macOS, Linux without a cgroup            no hard memory or descendant bound exists. Memory and disk are sampled every
+ *                                            250 ms; a burst between samples can pass the limit before the kill, and a
+ *                                            helper that left the process group can survive it. `enforced: "checked"`.
+ *
+ * `RLIMIT_FSIZE` applies to every POSIX spawn. The whole group is killed with SIGKILL on any limit, and again when the
+ * root exits, so nothing the root started outlives it.
+ */
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { lstatSync, readdirSync, rmSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { createContainer, effectiveContainment, probeContainmentCapability } from "./containment.js";
+const SAMPLE_MS = 250;
+const PIDS = 64;
+/** Applies the file-size limit (bash counts it in 1024-byte blocks, POSIX shells in 512), then becomes the target with
+ * argv untouched. */
+const PRELUDE = 'if [ "$1" != none ]; then if [ -n "$BASH_VERSION" ]; then b=$(($1/1024)); else b=$(($1/512)); fi; ulimit -f "$b" 2>/dev/null || exit 126; fi\nshift\nexec "$@"';
+let containment = null;
+const preferred = () => containment ??= effectiveContainment("preferred", probeContainmentCapability());
+/** Tests: forget the probed machine. */
+export function resetBoundedContainmentForTests() { containment = null; }
+/** A process's own start time, as `ps` reports it: what tells a live process from a reused pid. */
+export function processStartedAt(pid) {
+    if (process.platform === "win32")
+        return null;
+    try {
+        return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function processGroupOf(pid) {
+    if (process.platform === "win32")
+        return null;
+    try {
+        const group = Number(execFileSync("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim());
+        return Number.isInteger(group) && group > 1 ? group : null;
+    }
+    catch {
+        return null;
+    }
+}
+function groupRss(pgid) {
+    return new Promise(done => {
+        execFile("ps", ["-A", "-o", "pgid=,rss="], { encoding: "utf8", timeout: 2_000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
+            if (error !== null) {
+                done(null);
+                return;
+            }
+            let kilobytes = 0;
+            for (const line of stdout.split("\n")) {
+                const [group, rss] = line.trim().split(/\s+/);
+                if (Number(group) === pgid)
+                    kilobytes += Number(rss) || 0;
+            }
+            done(kilobytes * 1024);
+        });
+    });
+}
+/** The folder's total size, without following a link. */
+export function folderBytes(folder) {
+    let total = 0;
+    const walk = (dir) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(dir, name);
+            try {
+                const held = lstatSync(path);
+                if (held.isDirectory())
+                    walk(path);
+                else
+                    total += held.size;
+            }
+            catch { /* a temporary pack gone between the list and the look */ }
+        }
+    };
+    walk(folder);
+    return total;
+}
+const killGroup = (pgid) => { try {
+    process.kill(-pgid, "SIGKILL");
+}
+catch { /* gone */ } };
+export const boundedRun = async (file, args, options) => {
+    const windows = process.platform === "win32";
+    const effective = preferred();
+    const made = createContainer(effective, options.label);
+    const container = "container" in made ? made.container : null;
+    let enforced = "checked";
+    if (container !== null && options.memoryBytes !== undefined && container.limit?.({ memoryBytes: options.memoryBytes, pids: PIDS }) === true)
+        enforced = "system";
+    const target = windows ? { file, args: [...args] } : { file: "/bin/sh", args: ["-c", PRELUDE, "so-bounded", options.fileBytes === undefined ? "none" : String(options.fileBytes), file, ...args] };
+    const launch = container?.launch(target.file, target.args) ?? null;
+    const child = spawn(launch?.file ?? target.file, launch?.args ?? target.args, {
+        cwd: options.cwd, env: options.env, shell: false, windowsHide: true, detached: !windows,
+        stdio: ["pipe", "pipe", "pipe", ...(launch?.extraStdio ?? [])],
+    });
+    const stdout = [];
+    let stdoutBytes = 0, stderr = "", killed = null, peakBytes = 0, sampling = false;
+    const pid = child.pid;
+    const kill = (why) => {
+        killed ??= why;
+        if (pid !== undefined && !windows)
+            killGroup(pid);
+        if (container !== null)
+            void container.kill();
+        else if (windows) {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { /* gone */ }
+        }
+    };
+    if (pid !== undefined) {
+        try {
+            options.onStart?.({ pid, pgid: pid, startedAt: processStartedAt(pid) });
+        }
+        catch (error) {
+            kill("time");
+            throw error;
+        }
+        if (launch !== null) {
+            const attached = await launch.attach(child);
+            if (!attached.ok)
+                kill("time");
+        }
+    }
+    child.stdout?.on("data", (chunk) => {
+        stdoutBytes += chunk.length;
+        if (stdoutBytes > options.maxStdout) {
+            kill("output");
+            return;
+        }
+        stdout.push(chunk);
+    });
+    child.stderr?.on("data", (chunk) => { if (stderr.length < options.maxStderr)
+        stderr += chunk.toString("utf8").slice(0, options.maxStderr - stderr.length); });
+    child.stdin?.on("error", () => { });
+    child.stdin?.end(options.stdin);
+    const timer = setTimeout(() => kill("time"), options.timeoutMs);
+    const sampler = setInterval(() => {
+        if (sampling || pid === undefined)
+            return;
+        sampling = true;
+        void (async () => {
+            try {
+                if (options.memoryBytes !== undefined && enforced === "checked" && !windows) {
+                    const rss = await groupRss(pid);
+                    if (rss !== null) {
+                        peakBytes = Math.max(peakBytes, rss);
+                        if (rss > options.memoryBytes)
+                            kill("memory");
+                    }
+                }
+                if (options.diskBytes !== undefined && options.folder !== undefined && folderBytes(options.folder) > options.diskBytes)
+                    kill("disk");
+            }
+            finally {
+                sampling = false;
+            }
+        })();
+    }, options.sampleMs ?? SAMPLE_MS);
+    const finished = await new Promise(done => {
+        let settled = false;
+        const settle = (code, signal) => { if (!settled) {
+            settled = true;
+            done({ code, signal });
+        } };
+        child.once("error", () => settle(127, null));
+        child.once("close", (code, signal) => settle(code, signal));
+        // A helper that left the group can hold the pipes open past the root's exit: the root's exit is the answer.
+        child.once("exit", (code, signal) => {
+            if (pid !== undefined && !windows)
+                killGroup(pid);
+            setTimeout(() => { child.stdout?.destroy(); child.stderr?.destroy(); settle(code, signal); }, 2_000).unref?.();
+        });
+    });
+    clearTimeout(timer);
+    clearInterval(sampler);
+    if (container !== null) {
+        await container.kill(2_000);
+        container.release();
+    }
+    return { code: finished.code, signal: finished.signal, stdout: Buffer.concat(stdout), stderr, killed, enforced, peakBytes };
+};
+/**
+ * What a crashed build left: its group is killed only if the leader is still the process recorded (the pid and its start
+ * time, so a reused pid isn't killed), and its folder goes if it sits under `root`. On Linux the cgroup janitor has
+ * done this already.
+ */
+export function cleanupLeftover(record, root) {
+    let killed = false, removed = false;
+    if (record.pid !== null && record.pgid !== null && record.startedAt !== null && processStartedAt(record.pid) === record.startedAt && processGroupOf(record.pid) === record.pgid) {
+        killGroup(record.pgid);
+        killed = true;
+    }
+    if (record.folder !== null) {
+        const inner = relative(root, record.folder);
+        if (inner !== "" && !inner.startsWith("..") && !isAbsolute(inner)) {
+            try {
+                rmSync(record.folder, { recursive: true, force: true });
+                removed = true;
+            }
+            catch { /* the next takeover tries again */ }
+        }
+    }
+    return { killed, removed };
+}