toolroll 0.9.104 → 0.9.105

package/dist/console-instance.js

@@ -1,19 +1,3 @@
-/**
- * THE RUNNING CONSOLE, PROVED LIVE (docs/plans/agents-cockpit.md B1).
- *
- * Bare `toolroll` in a repository attaches to a console already running for this installation instead of starting a
- * second one. Build agents run as the operator's own user, so nothing the filesystem says can tell the operator from
- * an agent: the console's Unix socket is DISCOVERY ONLY. It answers one verb, `hello`, with facts an agent could learn
- * anyway, and changes nothing.
- *
- * What proves the console is real is a fresh random instance secret, minted at each start of `up` and written to the
- * database (behind the agent fence) with its pid, build and port. The CLI reads it from the database it opens itself,
- * then makes the LIVE console answer two fresh challenges with it: over the socket (HMAC of "socket:" + challenge),
- * and over the advertised HTTP listener (HMAC of "http:" + challenge + " " + address + " " + port, where the address and
- * port are what the console itself saw as the receiving end of that very connection). The CLI requires those to be
- * 127.0.0.1 and the recorded port, so a relay on 127.0.0.1 forwarding to the console's other address is refused, as are
- * a replayed hello, a stale record with a recycled pid, and another process now on that port.
- */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { lstatSync, mkdirSync, realpathSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
@@ -28,12 +12,6 @@ CREATE TABLE IF NOT EXISTS console_instance (
   socket     TEXT NOT NULL,
   started_at TEXT NOT NULL
 );`;
-/**
- * The socket's own owner-only directory beside the database's REAL file (a symlinked database resolves to the one
- * folder every spelling shares). Each console start binds a socket of its own, under a fresh random name recorded
- * with its secret: no console ever needs to remove — or can remove — another console's socket.
- */
-/** Toolroll's own name, so it never collides with a project or worktree that happens to sit beside the database. */
 export const INSTANCE_DIR = ".toolroll-run";
 export function instanceRunDir(databaseFile) {
     let file = databaseFile;
@@ -44,18 +22,15 @@ export function instanceRunDir(databaseFile) {
         try {
             file = join(realpathSync(dirname(databaseFile)), basename(databaseFile));
         }
-        catch { /* not there yet: as given */ }
+        catch { }
     }
     return join(dirname(file), INSTANCE_DIR);
 }
 const SOCKET_NAME = /^[0-9a-f]{16}\.sock$/;
-/** The longest Unix socket path the platform binds without truncating (sun_path less its NUL). */
 const SOCKET_PATH_MAX = process.platform === "darwin" ? 103 : 107;
-/** The console's own answer to a challenge over HTTP (an edge route, no sign-in: it reveals nothing). */
 export const INSTANCE_PATH = "/__instance";
 const CHALLENGE = /^[0-9a-f]{32,128}$/;
 const LINE_CAP = 4096;
-/** The record as stored: none, one this build can't read (never taken for none), or the record. */
 export function readInstanceState(store) {
     const row = store.handle.prepare("SELECT secret, pid, port, build, socket, started_at FROM console_instance WHERE id = 1").get();
     if (row === undefined)
@@ -69,31 +44,22 @@ export function readInstance(store) {
     const read = readInstanceState(store);
     return read.state === "ok" ? read.record : null;
 }
-/** v147: the key epoch the running console recorded with its claim (easy-start C2), or null: none recorded. */
 export function instanceKeyEpoch(store) {
     const row = store.handle.prepare("SELECT key_epoch FROM console_instance WHERE id = 1").get();
     return row === undefined || row["key_epoch"] == null ? null : String(row["key_epoch"]);
 }
-/** A stopping console forgets itself — only its own record, never a newer start's. */
 export function clearInstance(store, secret) {
     store.handle.prepare("DELETE FROM console_instance WHERE id = 1 AND secret = ?").run(secret);
 }
 export const socketProof = (secret, challenge) => createHmac("sha256", secret).update(`socket:${challenge}`).digest("hex");
 export const httpProof = (secret, challenge, address, port) => createHmac("sha256", secret).update(`http:${challenge} ${address} ${port}`).digest("hex");
 const PROOF = /^[0-9a-f]{64}$/;
-/** Constant-time comparison of two proofs, each first required to be exactly 64 hex characters. */
 const same = (a, b) => typeof a === "string" && PROOF.test(a) && PROOF.test(b) && timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
-/** The HTTP answer: bound to the address and port THIS connection was received on, as the console saw them. */
 export function instanceHttpAnswer(secret, challenge, local) {
     if (challenge === null || !CHALLENGE.test(challenge) || local.address === undefined || local.port === undefined)
         return { status: 400, body: JSON.stringify({ error: "challenge" }) };
     return { status: 200, body: JSON.stringify({ proof: httpProof(secret, challenge, local.address, local.port) }) };
 }
-/**
- * The run directory must be private to this user: a real, canonical directory owned by this user with no access for
- * anyone else (0700), inside a canonical directory owned by this user that nobody else can write. Checked before any
- * change is made, and before connecting or binding.
- */
 export function runDirProblem(dir, uid = process.getuid?.() ?? -1, mustExist = true) {
     const parent = dirname(dir);
     let above;
@@ -131,12 +97,11 @@ export function runDirProblem(dir, uid = process.getuid?.() ?? -1, mustExist = t
         lstatSync(join(dir, ".git"));
         return `${dir} holds a repository, not Toolroll's sockets`;
     }
-    catch { /* as it should be */ }
+    catch { }
     if ((info.mode & 0o077) !== 0)
         return `${dir} is open to other users — Toolroll uses it only when it is yours alone (chmod 700)`;
     return null;
 }
-/** A socket path that binds exactly (no truncation), named as a console names its own. */
 export function socketPathProblem(path) {
     if (!SOCKET_NAME.test(basename(path)))
         return `${path} isn't a console socket`;
@@ -144,10 +109,6 @@ export function socketPathProblem(path) {
         return `${path} is too long for a socket here`;
     return null;
 }
-/**
- * `up`: the run directory, made 0700 if it isn't there. An existing one is used only as it is (never chmodded): one
- * that isn't private to this user is refused. Everything is checked before anything is created.
- */
 export function prepareRunDir(dir, uid = process.getuid?.() ?? -1) {
     const before = runDirProblem(dir, uid, false);
     if (before !== null)
@@ -161,7 +122,6 @@ export function prepareRunDir(dir, uid = process.getuid?.() ?? -1) {
     }
     return runDirProblem(dir, uid, true);
 }
-/** Ask a socket one question; null when nobody is listening (or it said nothing usable in time). */
 export function askSocket(socketPath, request, timeoutMs = 2_000, connect = path => createConnection(path)) {
     return new Promise(resolve => {
         let settled = false, buffer = "";
@@ -190,18 +150,6 @@ export function askSocket(socketPath, request, timeoutMs = 2_000, connect = path
         socket.on("end", () => done({ none: "no-answer" }));
     });
 }
-/**
- * The console's discovery socket: one line in, one line out. `hello` (with a challenge) answers the public facts and
- * the socket proof; every other verb is refused. It reads nothing else and changes nothing. Bound under a fresh name
- * no other process has, so it never clears or replaces anything; its own listener removes it on close.
- *
- * Easy start D: the one other verb is `link`, and only when the console passes `link`. The console answers with a fresh
- * challenge of its own; the asker must answer it with HMAC(secret, "link:" + challenge) — the secret is in the database
- * (behind the agent fence), so only a process that read it can — and then gets one local owner's one-time sign-in path.
- * Each challenge is spent by the first answer on its own connection, right or wrong; the "link:" domain keeps a hello or
- * HTTP proof from ever counting here. The request names no account: what the link signs in as is the console's own
- * decision (`link` returns null unless local mode is on).
- */
 export async function openInstanceSocket(databaseFile, facts, secret, link) {
     const dir = instanceRunDir(databaseFile);
     const problem = prepareRunDir(dir);
@@ -213,7 +161,6 @@ export async function openInstanceSocket(databaseFile, facts, secret, link) {
         return { ok: false, problem: pathProblem };
     const server = createServer(socket => {
         let buffer = "";
-        // The link challenge this connection was given, until its one answer arrives.
         let challenged = null;
         let done = false;
         socket.setEncoding("utf8");
@@ -230,7 +177,6 @@ export async function openInstanceSocket(databaseFile, facts, secret, link) {
             const field = (key) => asked !== null && typeof asked === "object" && !Array.isArray(asked) ? asked[key] : undefined;
             const key = secret();
             if (challenged !== null) {
-                // The one answer to this connection's challenge: spent now, whatever it says.
                 const expected = key === null ? null : linkProof(key, challenged);
                 challenged = null;
                 if (expected === null || field("verb") !== "link-proof" || !same(field("proof"), expected))
@@ -269,20 +215,13 @@ export async function openInstanceSocket(databaseFile, facts, secret, link) {
             }
         });
     });
-    // A Unix bind never replaces an existing path (EADDRINUSE).
     const listening = await new Promise(resolve => { server.once("error", () => resolve(false)); server.listen(socketPath, () => resolve(true)); });
     if (!listening)
         return { ok: false, problem: `couldn't listen on ${socketPath}` };
     return { ok: true, name, close: () => { server.close(); } };
 }
-/** The `link` verb's answer to the console's challenge: bound to this verb, so no other proof ever counts for it. */
 export const linkProof = (secret, challenge) => createHmac("sha256", secret).update(`link:${challenge}`).digest("hex");
 const LINK_PATH = /^\/login\/once\/[A-Za-z0-9_-]{16,128}$/;
-/**
- * Ask the console on `socketPath` for a local owner's one-time sign-in path with the record's secret: `link`, the
- * console's challenge, then the proof. Null when it gives none (local mode off, a wrong or late answer, anything
- * malformed). The caller proves the console live first (proveLiveConsole) and opens the path on its proved address.
- */
 export function askLink(socketPath, secret, timeoutMs = 5_000, connect = path => createConnection(path)) {
     return new Promise(resolve => {
         let settled = false, buffer = "", sentProof = false;
@@ -324,11 +263,6 @@ export function askLink(socketPath, secret, timeoutMs = 5_000, connect = path =>
         socket.on("end", () => done(null));
     });
 }
-/**
- * A local owner's one-time sign-in address from this installation's live console (easy start D, `toolroll open`): the
- * console is proved live on both channels first, then asked over its socket with the record's secret. The address is
- * always the proved console's own; null when there is no proved console or it gives no link.
- */
 export async function requestLocalLink(databaseFile, store, build, seams = {}) {
     const proof = await proveLiveConsole(databaseFile, store, build, seams);
     if (!proof.ok)
@@ -341,11 +275,6 @@ export async function requestLocalLink(databaseFile, store, build, seams = {}) {
         return { ok: false, message: "the console gave no sign-in link (local mode is off, or it is still starting)" };
     return { ok: true, url: new URL(path, proof.url).toString(), console: proof.url };
 }
-/**
- * A record's console: "live" (its socket answers a fresh challenge with the record's secret and pid), "gone" (nobody
- * is listening on its socket, or the socket isn't there), or "unknown" (anything else: slow, malformed, a wrong proof).
- * Only "gone" lets another start take the record.
- */
 export async function recordLiveness(databaseFile, record, ask = askSocket) {
     const socketPath = join(instanceRunDir(databaseFile), record.socket);
     if (socketPathProblem(socketPath) !== null)
@@ -356,16 +285,9 @@ export async function recordLiveness(databaseFile, record, ask = askSocket) {
         return asked.none === "no-listener" ? "gone" : "unknown";
     return asked.answer["pid"] === record.pid && same(asked.answer["proof"], socketProof(record.secret, challenge)) ? "live" : "unknown";
 }
-/**
- * `up` claims the record for its socket — unless a live console already holds it (another start on the same
- * database, by any spelling of its path). The write is a compare-and-set on the record it checked: two starts racing
- * can't both win. Null: not claimed (this console runs, but `toolroll` won't attach to it).
- */
 export async function claimInstance(store, databaseFile, facts, now, liveness = record => recordLiveness(databaseFile, record)) {
     const rawSecret = () => { const row = store.handle.prepare("SELECT secret FROM console_instance WHERE id = 1").get(); return row === undefined ? null : String(row["secret"]); };
     const checked = rawSecret();
-    // Taken only from nobody, or from a console confirmed gone: never on a check that merely failed, and never over a
-    // record this build can't read.
     const current = readInstanceState(store);
     if (current.state === "invalid")
         return null;
@@ -373,24 +295,15 @@ export async function claimInstance(store, databaseFile, facts, now, liveness =
         return null;
     const secret = randomBytes(32).toString("hex");
     return store.transact(() => {
-        // Exactly the record that was checked (or none): anything else is another start's newer claim.
         if (rawSecret() !== checked)
             return null;
-        // v147: the start's key epoch (easy-start C2) is recorded with its claim; a claim without one records none.
         store.handle.prepare("INSERT INTO console_instance (id, secret, pid, port, build, socket, started_at, key_epoch) VALUES (1, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (id) DO UPDATE SET secret = excluded.secret, pid = excluded.pid, port = excluded.port, build = excluded.build, socket = excluded.socket, started_at = excluded.started_at, key_epoch = excluded.key_epoch")
             .run(secret, facts.pid, facts.port, facts.build, facts.socket, now.toISOString(), facts.keyEpoch ?? null);
         return secret;
     });
 }
-/**
- * Prove the console this installation's database names is live, on both channels, before anything is shown or
- * opened. "none": no console runs (no record, or nobody on the socket); "refused": something answers that can't
- * prove it is the console (or a different build) — the person restarts it.
- */
 export async function proveLiveConsole(databaseFile, store, build, seams = {}) {
     const restart = "stop it and run `toolroll up` again";
-    // No record: nothing is running here (a console that couldn't claim one isn't offered). One this build can't read
-    // isn't "nothing": it is refused.
     const read = readInstanceState(store);
     if (read.state === "none")
         return { ok: false, state: "none", message: "no console is running" };
@@ -408,7 +321,6 @@ export async function proveLiveConsole(databaseFile, store, build, seams = {}) {
             return { ok: false, state: "refused", message: `the console's socket can't be trusted: ${socketPath} isn't this user's socket` };
     }
     catch (error) {
-        // Only "not there" means nothing is running; a socket the system won't show can't be checked.
         if (error.code === "ENOENT")
             return { ok: false, state: "none", message: "no console is running" };
         return { ok: false, state: "refused", message: `the console's socket can't be checked — ${restart}` };
@@ -417,7 +329,6 @@ export async function proveLiveConsole(databaseFile, store, build, seams = {}) {
     const first = challenge();
     const asked = await (seams.ask ?? askSocket)(socketPath, { verb: "hello", challenge: first });
     if ("none" in asked) {
-        // Stale (a console that died): nobody is listening, so nothing is running. Discovery removes nothing.
         if (asked.none === "no-listener")
             return { ok: false, state: "none", message: "no console is running" };
         return { ok: false, state: "refused", message: `the console's socket didn't answer — ${restart}` };

package/dist/container-state.js

@@ -1,4 +1,3 @@
-/** Read-only kernel evidence. Recorded names never authorize signals. */
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { readFileSync, readlinkSync, realpathSync, statfsSync, statSync } from "node:fs";
@@ -36,9 +35,6 @@ export function cgroupEmptiness(container, identity) {
                 return "unknown";
         }
         catch (error) {
-            // Only the original, still-mounted parent may prove removal. Linux
-            // refuses rmdir while a cgroup has members; an unmounted hierarchy,
-            // another namespace, a replaced directory or an ordinary file cannot.
             return error.code === "ENOENT" ? "empty" : "unknown";
         }
         return parseCgroupEvents(readFileSync(join(container, "cgroup.events"), "utf8"));

package/dist/containment.js

@@ -1,36 +1,3 @@
-/**
- * OS process containment (docs/PROCESS_CONTAINMENT_PLAN.md).
- *
- * The stop contract before this module was OBSERVATIONAL: a provider's
- * tree is scanned every 500 ms, and a double fork can reparent between
- * scans. This module adds an OS boundary where the OS has one, and says
- * exactly what it has where it has none:
- *
- *   linux   a delegated cgroup v2 directory per spawn. The target is
- *           placed in it BEFORE it executes (the `sh` prelude below writes
- *           its own pid, then execs the target with argv verbatim), so a
- *           setsid/double-fork helper is born inside and dies with
- *           `cgroup.kill`. Emptiness is the kernel's own `cgroup.events`
- *           populated flag — never a transport exit. A detached janitor
- *           kills the cgroup when this worker dies.
- *   win32   a Job Object with kill-on-close and no breakaway, owned by a
- *           PowerShell helper OUTSIDE the job that creates the target
- *           suspended, assigns it, then resumes it. The helper's death —
- *           including this worker's death, which closes its stdin — closes
- *           the handle and the job kills everything in it.
- *   darwin  nothing. There is no supported cgroup/Job Object equivalent;
- *           NOTE_TRACK/NOTE_CHILD have been unsupported since 10.5 and
- *           launchd's AbandonProcessGroup only covers a process group. The
- *           observational mode stays, is reported as exactly that, and a
- *           REQUIRED policy refuses before any target executes.
- *
- * Three policies: `observed` (the behaviour every existing installation
- * has), `preferred` (native when this machine can, observed — and said
- * so — when it cannot), `required` (native or a refusal; never a silent
- * downgrade). The policy is decided ONCE per controller process from the
- * operator's flag or environment and pinned; nothing a child supplies and
- * no corrupt value can weaken a pinned requirement.
- */
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmdirSync, writeFileSync } from "node:fs";
@@ -41,14 +8,7 @@ import { fileURLToPath } from "node:url";
 import { envValue } from "./names.js";
 import { sleep } from "./sleep.js";
 export const CONTAINMENT_POLICIES = ["observed", "preferred", "required"];
-/** The environment name the controller reads when no flag names a policy. */
 export const CONTAINMENT_ENV = "TOOLROLL_CONTAINMENT";
-/**
- * Parse an operator's policy word. Absent means `observed` — every
- * existing installation keeps its behaviour. Anything present must be
- * one of the three words exactly: a corrupt value is a refusal, never a
- * quiet fall back to observed (which would turn a requirement off).
- */
 export function parseContainmentPolicy(raw) {
     if (raw === undefined || raw === null)
         return { ok: true, policy: "observed", source: "default" };
@@ -62,7 +22,6 @@ export function parseContainmentPolicy(raw) {
     };
 }
 const DARWIN_DETAIL = "macOS has no supported cgroup or Job Object equivalent (kqueue NOTE_TRACK/NOTE_CHILD have been unsupported since 10.5; launchd AbandonProcessGroup covers only a process group) — containment stays observational here; for native containment run this runner on a Linux VM or Linux runner with a delegated cgroup v2 (or on Windows)";
-/** The cgroup path of this process from /proc/self/cgroup (`0::/path`). */
 export function ownCgroupPath(selfCgroup) {
     for (const line of selfCgroup.split("\n")) {
         const match = /^0::(\/.*)$/.exec(line.trim());
@@ -71,14 +30,6 @@ export function ownCgroupPath(selfCgroup) {
     }
     return null;
 }
-/**
- * What this machine can do, established by DOING it: on Linux, a child
- * cgroup is created and removed inside this process's own cgroup; a
- * mount that is not v2, a cgroup that is not delegated to this user, or
- * an unreadable /proc all answer unavailable with the reason. Nothing
- * here can be overridden by an environment variable into a claim the OS
- * did not make.
- */
 export function probeContainmentCapability(options = {}) {
     const platform = options.platform ?? process.platform;
     if (platform === "linux")
@@ -126,8 +77,6 @@ function probeCgroup2(options) {
         rmdirSync(probe);
     }
     catch {
-        // A probe cgroup that cannot be removed is empty and harmless; the
-        // capability is still real. It is named so a person can remove it.
     }
     return {
         platform,
@@ -165,7 +114,6 @@ function findPowershell() {
             return candidate;
     return null;
 }
-/** The truthful composition of what was asked and what the OS offers. */
 export function effectiveContainment(policy, capability) {
     if (policy === "observed")
         return { policy, capability, mode: "observed", downgraded: false, refusal: null };
@@ -181,7 +129,6 @@ export function effectiveContainment(policy, capability) {
         refusal: `native process containment is required but unavailable on this ${capability.platform} runner: ${capability.detail}. No provider, setup or check process runs until containment is available or the policy is set to observed/preferred explicitly`,
     };
 }
-/** One-line status words for `daemon status`, `up`, and the certificate. */
 export function describeContainment(effective) {
     const backend = effective.capability.backend ?? "none";
     if (effective.refusal !== null)
@@ -192,16 +139,11 @@ export function describeContainment(effective) {
         return `containment: observed (preferred native, ${backend} unavailable) — ${effective.capability.detail}`;
     return `containment: observed (${effective.policy}) — ${effective.capability.detail}`;
 }
-/** The one sentence a person reads at start when agents on Linux run
- * without native containment that the machine could offer once set up;
- * null when there is nothing a person needs to read. The exact
- * `describeContainment` line stays in --verbose and in a service log. */
 export function containmentNotice(effective) {
     if (effective.refusal !== null || effective.mode !== "observed" || effective.capability.platform !== "linux" || effective.capability.available)
         return null;
     return "Agents run without Linux process containment on this machine (it needs a delegated cgroup). That's fine for trying Toolroll; see docs/guide/linux.md to turn it on.";
 }
-/** The status envelope's shape: no paths a person did not already know, no secrets. */
 export function containmentStatus(effective) {
     return {
         policy: effective.policy,
@@ -213,13 +155,7 @@ export function containmentStatus(effective) {
         detail: effective.capability.detail,
     };
 }
-// ---- the pinned policy --------------------------------------------------------
 let pinned = null;
-/**
- * Pin this process's containment ONCE, from the operator's own word. A
- * second pin may only tighten: once `required` stands nothing pins it
- * weaker — the only way down is a new process started with a new word.
- */
 export function pinContainment(effective) {
     if (pinned !== null && rank(effective.policy) < rank(pinned.policy)) {
         throw new Error(`containment is pinned at ${pinned.policy} for this process; ${effective.policy} would weaken it`);
@@ -230,37 +166,24 @@ export function pinContainment(effective) {
 function rank(policy) {
     return policy === "required" ? 2 : policy === "preferred" ? 1 : 0;
 }
-/**
- * Resolve the policy from a flag word, then the environment, then the
- * default, and pin it. A corrupt word is a refusal to start, never a
- * default: the caller reports `problem` and exits.
- */
 export function resolveContainment(flagWord, env = process.env) {
     const parsed = parseContainmentPolicy(flagWord ?? envValue(env, "CONTAINMENT"));
     if (!parsed.ok)
         return parsed;
     return { ok: true, effective: pinContainment(effectiveContainment(parsed.policy, probeContainmentCapability())) };
 }
-/** What every containable spawn consults. Unpinned = observed, exactly as before this module. */
 export function currentContainment() {
     if (pinned === null)
         pinned = effectiveContainment("observed", probeContainmentCapability());
     return pinned;
 }
-/** Tests only. */
 export function resetContainmentForTests() {
     pinned = null;
 }
 let factoryOverride = null;
-/** Tests: substitute the OS object (a scripted or file-backed stand-in). */
 export function overrideContainerFactoryForTests(factory) {
     factoryOverride = factory;
 }
-/**
- * Make the OS object for one spawn, or say why not. `null` when the
- * effective mode is observed; a `refused` when native containment was
- * demanded and this spawn cannot have it — the caller must not spawn.
- */
 export function createContainer(effective, label) {
     if (effective.refusal !== null)
         return { refused: effective.refusal };
@@ -279,13 +202,7 @@ export function createContainer(effective, label) {
         return { refused: `native containment could not be established for this spawn (${error instanceof Error ? error.message : String(error)}) — nothing ran` };
     }
 }
-/**
- * The cgroup2 prelude: join, confirm on fd 3, close it, exec the target
- * with argv exactly as given (positional parameters, never re-parsed).
- * A join that fails exits 126 before the target can run.
- */
 export const CGROUP2_PRELUDE = 'echo "$$" > "$1/cgroup.procs" || exit 126\nprintf "attached\\n" >&3 || exit 126\nIFS= read -r permit <&3 || exit 126\n[ "$permit" = go ] || exit 126\nexec 3>&-\nshift\nexec "$@"';
-/** The janitor: waits for this worker's pipe to close, then kills and removes the cgroup. */
 export const CGROUP2_JANITOR = [
     'd="$1"',
     'printf "ready\\n"',
@@ -301,7 +218,6 @@ export const CGROUP2_JANITOR = [
 export function safeContainerLabel(label) {
     return label.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "run";
 }
-/** A cgroup v2 leaf under the delegated root. Exported for the native test's direct use. */
 export function cgroup2Container(capability, label, mountOverride) {
     const root = mountOverride ?? capability.cgroupRoot;
     if (root === undefined)
@@ -311,7 +227,6 @@ export function cgroup2Container(capability, label, mountOverride) {
     let identity;
     try {
         identity = captureCgroupIdentity(dir);
-        // Exercise the exact kernel operation while the object is still empty.
         writeFileSync(join(dir, "cgroup.kill"), "1");
     }
     catch (error) {
@@ -354,7 +269,6 @@ export function cgroup2Container(capability, label, mountOverride) {
         id: dir,
         identity,
         limit({ memoryBytes, pids }) {
-            // The controllers exist here only if the delegated parent enabled them for its children.
             try {
                 writeFileSync(join(dir, "memory.max"), String(memoryBytes));
                 writeFileSync(join(dir, "pids.max"), String(pids));
@@ -404,8 +318,6 @@ export function cgroup2Container(capability, label, mountOverride) {
                                         settle({ ok: false, detail: "containment cleanup guardian unavailable" });
                                         return;
                                     }
-                                    // onSpawn already durably recorded custody. EOF before this
-                                    // authorization leaves the target unexecuted inside the cgroup.
                                     channel.write("go\n", error => settle(error ? { ok: false, detail: String(error) } : { ok: true }));
                                 });
                         });
@@ -426,23 +338,14 @@ export function cgroup2Container(capability, label, mountOverride) {
             try {
                 rmdirSync(dir);
             }
-            catch { /* still populated: the janitor or recovery finishes it */ }
+            catch { }
             try {
                 janitor?.stdin?.end();
             }
-            catch { /* already gone */ }
+            catch { }
         },
     };
 }
-/**
- * A Windows Job Object owned by a PowerShell helper outside the job. The
- * helper connects to a named pipe this process listens on and reports
- * `attached` only after CreateProcess(CREATE_SUSPENDED) + AssignProcess
- * ToJobObject + ResumeThread; `failed <detail>` means the target never
- * ran. `kill` asks for TerminateJobObject over the same pipe and waits
- * for the helper's `empty` reply. Physical Windows is where this runs;
- * the CI windows job exercises it.
- */
 export function jobObjectContainer(capability, label) {
     if (capability.helper === undefined || capability.powershell === undefined)
         throw new Error("the Job Object capability names no helper");
@@ -489,9 +392,6 @@ export function jobObjectContainer(capability, label) {
                     state = "attached";
                 else if (line === "empty") {
                     state = "empty";
-                    // The helper may have a pending control read. Close now, on its
-                    // kernel empty proof, so .NET disposal never waits for an EOF that
-                    // transport `close` would otherwise delay until after helper exit.
                     socket.destroy();
                 }
                 else if (line.startsWith("failed "))
@@ -536,7 +436,6 @@ export function jobObjectContainer(capability, label) {
                 args: ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", capability.helper, "-Pipe", pipe, "-Encoded", Buffer.from(JSON.stringify([file, ...args]), "utf8").toString("base64"), "-JobName", id, ...(memoryLimit > 0 ? ["-MemoryLimit", String(memoryLimit)] : [])],
                 extraStdio: [],
                 async attach(child) {
-                    // Called only after the durable onSpawn callback succeeded.
                     helperChild = child;
                     authorized = true;
                     authorize();
@@ -561,8 +460,6 @@ export function jobObjectContainer(capability, label) {
             }
             if (await waitEmpty(timeoutMs))
                 return true;
-            // A nonresponsive helper is still our own ChildProcess. Closing its
-            // actual handle triggers KILL_ON_JOB_CLOSE; saved IDs remain query-only.
             if (helperChild && helperChild.exitCode === null && helperChild.signalCode === null)
                 helperChild.kill("SIGKILL");
             state = "lost";

package/dist/contract-changes.js

@@ -4,12 +4,6 @@ const trimmed = (text) => {
     const t = text.trim();
     return t === "" ? null : t;
 };
-/**
- * Every addition, change, and removal between the filed contract and a
- * proposed one. Whitespace at the ends and touch/evidence order do not
- * count (the scope digest ignores them too); everything else does,
- * including the advisory `how`, because the operator wrote it.
- */
 export function contractChangesOf(filed, proposed) {
     const changes = [];
     if (filed.goal.trim() !== proposed.goal.trim()) {

package/dist/contracts/acceptance-terms.js

@@ -1,15 +1,8 @@
-/**
- * The acceptance rubric's vocabulary and limits: the evidence kinds a criterion may require, and how many criteria
- * and bytes a rubric may hold. A leaf with no imports but TEXT_LIMITS, because the plan contract (src/contracts/plan.ts)
- * reads these through scope.ts while scope.ts reads the plan contract's criterion: kept here, both load in either order.
- */
 import { TEXT_LIMITS } from "../text-limits.js";
 export const EVIDENCE_KINDS = ["check", "screenshot", "changed-path", "manual-review"];
 export const ACCEPTANCE_LIMITS = {
     criteria: 12,
     id: TEXT_LIMITS.acceptanceIdBytes,
-    // A statement is one testable outcome; three hundred bytes forced people to
-    // drop the qualifying clause that made it testable.
     statement: TEXT_LIMITS.acceptanceStatementBytes,
     how: TEXT_LIMITS.acceptanceHowBytes,
     evidenceKinds: EVIDENCE_KINDS.length,