toolroll 0.9.103 → 0.9.105

package/dist/runner.js

@@ -1,24 +1,3 @@
-/**
- * A machine that may be given work.
- *
- * Auth is here from the first commit, and that is a deliberate ordering rather
- * than diligence for its own sake. A control plane that dispatches work to
- * unauthenticated runners for six months grows six months of code that assumes
- * the caller is whoever it says it is, and retrofitting identity into that is
- * how the retrofit gets a hole in it. It costs almost nothing to do now.
- *
- * **The token is never stored.** Registration mints one, prints it once, and
- * keeps only a hash. There is no command that recovers it, because a control
- * plane able to hand back a runner's credential is one whose database is worth
- * stealing — and because the same rule governs secrets everywhere else in this
- * design: the control plane holds metadata, the runner holds values.
- *
- * Liveness is separate from a lease expiring, and the distinction matters at
- * 3am. A lease expires because time passed; a runner is dead because it
- * stopped saying otherwise. Reaping on the first tells you a task is free
- * again. Reaping on the second tells you a *machine* is gone, and everything
- * it was holding — claims and worktrees alike — needs recovering together.
- */
 import { mintSecret } from "./secret-mint.js";
 import { isAcpProvider } from "./acp-agents.js";
 import { verifyLaunch } from "./acp-attest.js";
@@ -29,41 +8,20 @@ import { canonicalProject } from "./project.js";
 import { lifecycleOf, reportLifecycle } from "./store.js";
 import { ALL_CREDENTIAL_ENV, PROVIDER_IDS, inspectionOf } from "./provider.js";
 import { attestationOf, versionInRange } from "./attest.js";
-/** A runner's repo binding, in the same canonical form task filing uses —
- * the claim gate compares these by equality, so both sides must resolve
- * through one convention (MCP gateway spec v6, the runner tuple). */
+import { IDENTITY_FAILED_PROBE, LOGIN_PROBE, PATH_PROBE } from "./phase-routing.js";
+import { homedir } from "node:os";
+import { readAuthMode } from "./keys.js";
+import { signInFacts } from "./provider-connection.js";
 export function canonicalRepos(repos) {
     return repos.map(repo => canonicalProject(repo) ?? resolve(repo));
 }
-/** v101: a runner's token lasts a year from its registration; registering again (every start does) renews it. */
 export const RUNNER_TOKEN_MS = 365 * 86_400_000;
-/**
- * How long a runner may go quiet before it is presumed gone.
- *
- * Four heartbeats (RUNNER_HEARTBEAT_MS): one slow check-in never declares a busy
- * machine dead, and a machine that really is gone holds its name for a minute,
- * not three (docs/plans/actors-lessons.md). A clean stop doesn't wait even that
- * long: a draining or stopped holder never blocks the next start
- * (registerRunnerIfIdle).
- */
 export const DEFAULT_LIVENESS_MS = 60_000;
-/** How often a live runner says so: `up`'s runner heartbeat and every watch lease renewal. */
 export const RUNNER_HEARTBEAT_MS = 15_000;
-/** The longest a watch lease may be taken or renewed for (durable-actors' MAX_HOST_LEASE_DURATION_MS): a crashed
- * holder's projects are free within a minute. The store clamps every ttl to it. */
 export { MAX_WATCH_LEASE_MS } from "./store.js";
 export function register(store, options) {
     const { name, host, capacity = 1, repos = [], agents = [], now, newToken = mintToken, mutation = {}, } = options;
     const token = newToken();
-    /**
-     * Anything the previous holder of this name still had is taken back first.
-     *
-     * Registering under a name is a new process saying it exists; whatever the
-     * last one was holding, it is not holding now. Skipping this is worse than
-     * it sounds: the fresh `heartbeat_at` makes the old identity look alive
-     * again, so the reaper walks straight past its abandoned claims and
-     * worktrees and they are stranded for good.
-     */
     const previous = store.getRunner(name);
     const reclaimed = previous === null
         ? null
@@ -82,12 +40,7 @@ export function register(store, options) {
         heartbeatAt: now.toISOString(),
         retiredAt: null,
     };
-    // The store assigns the incarnation while holding its write transaction.
-    // Doing it from the `previous` snapshot above is racy: two registrars can
-    // read the same predecessor and otherwise mint the same generation.
     const runner = store.saveRunner(proposed, hashToken(token), mutation);
-    // v137: this registration is started; its lifecycle row is bound to it by registered_at, so an earlier holder's
-    // drain or stop never describes it.
     reportLifecycle(store, workerComponent(name), "started", runner.registeredAt, now);
     return {
         runner,
@@ -97,14 +50,6 @@ export function register(store, options) {
             : null,
     };
 }
-/**
- * Whether this caller is who it says it is.
- *
- * Compared in constant time. The comparison is between hashes rather than
- * secrets, so the practical risk is slight — but a timing-variable equality on
- * a credential path is the kind of thing that gets copied into somewhere it
- * matters, and there is no reason to leave the example lying around.
- */
 export function authenticate(store, name, token) {
     const found = store.getRunner(name);
     if (found === null)
@@ -117,13 +62,6 @@ export function authenticate(store, name, token) {
         ? { ok: true, runner: found.runner }
         : { ok: false, reason: "bad-token" };
 }
-/**
- * "I am still here." Authenticated AND ATOMIC (arc 2 findings 25/33): the
- * hash is verified and the heartbeat stamped in one write transaction, so
- * a takeover that rotates the credential between the check and the touch
- * cannot receive a stale incarnation's pulse — after rotation commits, the
- * very next heartbeat refuses, and the caller must treat that as fatal.
- */
 export function heartbeat(store, name, token, now) {
     return store.transact(() => {
         const auth = authenticate(store, name, token);
@@ -133,14 +71,6 @@ export function heartbeat(store, name, token, now) {
         return { ok: true, runner: { ...auth.runner, heartbeatAt: now.toISOString() } };
     });
 }
-/**
- * Extend a live runner's project binding using that runner's own credential.
- *
- * `up` owns both the credential and the registry watcher, so a project the
- * operator admitted through its console can join without a second operator
- * ceremony or a restart. Authentication and the additive write share one
- * transaction: a replaced process cannot widen its successor's binding.
- */
 export function addRunnerReposAuthed(store, args, now) {
     return store.transact(() => {
         const auth = authenticate(store, args.name, args.token);
@@ -157,11 +87,6 @@ export function addRunnerReposAuthed(store, args, now) {
         };
     });
 }
-/**
- * Narrow a live runner's binding when a project is removed, under the same
- * credential and transaction as addRunnerReposAuthed. `up` calls it only
- * after that project's watch has stopped admitting work.
- */
 export function removeRunnerRepoAuthed(store, args, now) {
     return store.transact(() => {
         const auth = authenticate(store, args.name, args.token);
@@ -173,14 +98,8 @@ export function removeRunnerRepoAuthed(store, args, now) {
         return { ok: true, runner: { ...auth.runner, repos: bound.repos } };
     });
 }
-/**
- * The one runner-name rule (arc 2 finding 13): nonempty, control-free, at
- * most 60 characters — the console form's rule, now shared by every door.
- */
 export const RUNNER_NAME_MAX = 60;
-/** The most tasks one worker may be set to run at once (the console's register form says the same). */
 export const RUNNER_CAPACITY_MAX = 64;
-/** A capacity as typed; changing an existing worker may use zero to drain it. */
 export function parseRunnerCapacity(value, { allowZero = false } = {}) {
     const capacity = Number(value.trim());
     return value.trim() !== "" && Number.isInteger(capacity) && capacity >= (allowZero ? 0 : 1) && capacity <= RUNNER_CAPACITY_MAX ? capacity : null;
@@ -195,9 +114,6 @@ export function validRunnerName(name) {
     }
     return true;
 }
-/** A generated base name: lowercase [a-z0-9-], collapsed, trimmed. The
- * suffix budget (finding 24) is the CALLER's arithmetic — truncate the
- * base to `RUNNER_NAME_MAX - suffix.length` before appending. */
 export function normalizeRunnerName(raw) {
     const collapsed = raw
         .toLowerCase()
@@ -206,24 +122,13 @@ export function normalizeRunnerName(raw) {
         .replace(/^-|-$/g, "");
     return (collapsed === "" ? "worker" : collapsed).slice(0, RUNNER_NAME_MAX);
 }
-/**
- * The atomic take-or-refuse door (arc 2 findings 1/15/16/26/31): ONE write
- * transaction that proves the name is free — absent, retired, or dead by
- * the same predicate recovery uses, with NO unexpired watch lease — then
- * finishes every open run the dead holder left (requeueing what no newer
- * live claim owns), reclaims, and rotates. Two racers serialize: one wins,
- * the other gets the typed refusal.
- */
 export function registerRunnerIfIdle(store, options) {
     const { name, now, previousGone, ...registration } = options;
     return store.transact(() => {
         let existing = store.getRunner(name);
-        // The protection against two live holders stands: only a holder whose every process is proved gone, or whose own
-        // drain has ended (its stop bound passed, or it reported stopped), is signed off.
         let signedOff = null;
         const blocked = existing !== null && ((existing.runner.retiredAt === null && isAlive(existing.runner, now)) || store.liveWatchLeaseOf(name, now) !== null);
         const drain = existing === null ? null : drainOf(store, existing.runner, now);
-        // A scheduled drain deadline is not proof that its timer ran or its children exited.
         if (blocked && existing !== null && previousGone !== undefined) {
             const proof = previousGone(existing);
             if (proof.gone) {
@@ -235,7 +140,6 @@ export function registerRunnerIfIdle(store, options) {
                 existing = store.getRunner(name);
             }
         }
-        // A live draining holder remains exclusive even if its advertised deadline has passed.
         if (existing !== null && drain !== null && (isAlive(existing.runner, now) || store.liveWatchLeaseOf(name, now) !== null)) {
             return { ok: false, reason: "runner-draining", until: drain.until, detail: `Toolroll is restarting (draining): ${name} is still stopping (scheduled by ${drain.until})` };
         }
@@ -254,31 +158,16 @@ export function registerRunnerIfIdle(store, options) {
                 detail: `${name} holds a live watch lease on ${lease.repo} until ${lease.until}`,
             };
         }
-        // Recovery BEFORE reclaim (finding 16): the open-run evidence must be
-        // read while it still exists; register()'s releaseClaimsOf would
-        // otherwise hide it from every later recovery.
         const recoveredRuns = existing === null ? 0 : store.recoverRunnerWork(name, now).runs.length;
-        // A restart keeps the capacity an operator set; only an explicit one changes it.
         const registered = register(store, { ...registration, name, now, capacity: options.capacity ?? existing?.runner.capacity ?? 1 });
         return { ok: true, ...registered, recoveredRuns, signedOff };
     });
 }
-/**
- * The authenticated lease door (arc 2 findings 15/26): credential verified
- * and lease acquired/renewed in the SAME transaction — after a takeover
- * rotates the hash, a stale incarnation can neither acquire nor renew. A
- * takeover of an expired lease recovers the superseded incarnation INSIDE
- * this transaction, so no crash can separate "B owns the lease" from "A
- * was recovered".
- */
 export function acquireWatchLeaseAuthed(store, args, now) {
     return store.transact(() => {
         const auth = authenticate(store, args.runner, args.token);
         if (!auth.ok)
             return { ok: false, reason: auth.reason };
-        // Watching a repo is a runner road like any other (MCP spec v6,
-        // round-4 finding 1): membership is proven in the same transaction
-        // as the lease, before any repo activity rides it.
         if (!auth.runner.repos.includes(canonicalProject(args.repo) ?? resolve(args.repo))) {
             return { ok: false, reason: "unauthorized-repo" };
         }
@@ -289,9 +178,6 @@ export function acquireWatchLeaseAuthed(store, args, now) {
         return { ok: true, generation: got.generation, superseded: got.superseded, recovered };
     });
 }
-/** The renewal, equally authenticated: a false answer is FATAL to the
- * caller — a loop that keeps admitting work after losing its lease or its
- * credential is the exact hole the doors exist to close. */
 export function heartbeatWatchLeaseAuthed(store, args, now) {
     return store.transact(() => {
         const auth = authenticate(store, args.runner, args.token);
@@ -303,19 +189,12 @@ export function heartbeatWatchLeaseAuthed(store, args, now) {
         return renewed;
     });
 }
-/**
- * Retirement fenced by THIS holder's credential (arc 2 finding 28): a
- * successor that already rotated makes the predecessor's cleanup a typed
- * no-op instead of retiring the winner.
- */
 export function retireRunnerIfCurrent(store, name, token, now) {
     return store.transact(() => {
         const auth = authenticate(store, name, token);
         if (!auth.ok)
             return { ok: false, reason: auth.reason };
         store.retireRunner(name, now);
-        // Stopped is retired: its leases lapse now, so the next start or watch takes its projects over (recovering whatever
-        // this incarnation left) without waiting for them to run out.
         store.expireWatchLeasesOf(name, now);
         reportLifecycle(store, workerComponent(name), "stopped", auth.runner.registeredAt, now);
         return { ok: true };
@@ -329,58 +208,23 @@ export function isAlive(runner, now, livenessMs = DEFAULT_LIVENESS_MS) {
         return false;
     return now.getTime() - last < livenessMs;
 }
-/** Runners that have stopped saying they are there. */
 export function deadRunners(store, now, livenessMs = DEFAULT_LIVENESS_MS) {
     return store.listRunners().filter(runner => !isAlive(runner, now, livenessMs));
 }
-/** Whether a pass found anything at all to take back. */
 export function recoveredAnything(one) {
     return one.claims.length > 0 || one.worktrees.length > 0 || one.runs.length > 0 || one.requeued.length > 0;
 }
-/**
- * Take back everything a dead runner was holding.
- *
- * Claims, open runs, and worktrees together, in one pass, because they are
- * halves of the same fact: the machine is gone. Recovering one and not the
- * others leaves a task dispatchable with its working copy still checked out
- * to a process that no longer exists — which fails later, further away, and
- * looks like a git problem rather than a scheduling one — or a run record
- * that stays open forever after its lease was released and a successor
- * finished the work (P0.1a: the real run 1501).
- *
- * Runs settle through the same transactional walk the takeover door uses
- * (`recoverRunnerWork`), AFTER this runner's claims are released: the walk
- * finishes every open run recorded against the runner outside a live held
- * session as failed/interrupted, and requeues its task only when no newer
- * live lease owns it. A finished outcome is never rewritten; a successor's
- * claim, run, worktree, and task state are somebody else's rows and stay
- * exactly as they were.
- *
- * Worktrees are handed back **unverified**. Nobody watched what the dead
- * process was doing when it stopped, so the directory on disk is a claim about
- * the past rather than a description of the present, and something has to look
- * before it is reused.
- */
 export function recoverDead(store, now, livenessMs = DEFAULT_LIVENESS_MS) {
     const recovered = [];
     for (const candidate of deadRunners(store, now, livenessMs)) {
-        // Death is re-proved inside the transaction that acts on it. The snapshot
-        // above is a survey of a moving world: a runner whose pulse lands between
-        // the survey and the release is alive, and releasing its claims anyway
-        // would take work from a machine that just said "still here" — the exact
-        // loss the heartbeat exists to prevent.
         const recovery = store.transact(() => {
             const fresh = store.getRunner(candidate.name);
             if (fresh === null || isAlive(fresh.runner, now, livenessMs))
                 return null;
-            // Claims and worktrees first, so the report names every path handed
-            // back; the run walk's own per-task worktree release then finds
-            // nothing left to do here.
             const requeued = [];
             const claims = store.releaseClaimsOf(candidate.name, now, requeued);
             const worktrees = store.releaseWorktreesOf(candidate.name, now);
             const settled = store.recoverRunnerWork(candidate.name, now);
-            // Only what recovery left in the queue: a vanished build it stopped for a person isn't requeued (vanished-retry.ts).
             return { runner: candidate.name, claims, worktrees, runs: settled.runs, requeued: [...new Set([...requeued, ...settled.requeued])].filter(id => store.getTask(id)?.state === "queued") };
         });
         if (recovery !== null)
@@ -388,7 +232,6 @@ export function recoverDead(store, now, livenessMs = DEFAULT_LIVENESS_MS) {
     }
     return recovered;
 }
-/** 32 bytes of randomness, urlsafe, so it survives being pasted anywhere. */
 function mintToken() {
     return mintSecret(32);
 }
@@ -398,22 +241,14 @@ export function hashToken(token) {
 function sameDigest(left, right) {
     const a = Buffer.from(left, "utf8");
     const b = Buffer.from(right, "utf8");
-    // timingSafeEqual throws on a length mismatch, which is itself a leak of
-    // sorts; equal-length hex digests make that unreachable in practice, and the
-    // guard keeps it from throwing if one is ever malformed.
     return a.length === b.length && timingSafeEqual(a, b);
 }
 const READINESS_PROBE_TIMEOUT_MS = 5_000;
-export async function observeProviderReadiness(probe, env = process.env, providers = PROVIDER_IDS, 
-/** An ACP agent's live check on this runner (store.acpAttestationFor), when the caller can read one. */
-acpChecked) {
+export async function observeProviderReadiness(probe, env = process.env, providers = PROVIDER_IDS, acpChecked, claudeMode = () => readAuthMode("claude", homedir())) {
     return Promise.all(providers.map(async (provider) => {
-        // An ACP agent is looked at, never run, outside the gateway (acp-inspect.ts). It is ready only once its
-        // conformance check passed on this computer; until then it says so.
         if (isAcpProvider(provider)) {
             const checked = acpChecked?.(provider) ?? null;
             if (checked !== null) {
-                // Ready only while every file its check bound is still the one that passed.
                 const verified = verifyLaunch(checked.launch);
                 return verified.ok
                     ? { provider, state: "ready", reason: `${checked.agent.name} ${checked.agent.version}, checked ${checked.recordedAt.slice(0, 10)}`, probe: "version" }
@@ -427,7 +262,7 @@ acpChecked) {
         const facts = inspectionOf(provider);
         const version = await probe(facts.binary, ["--version"], { timeoutMs: READINESS_PROBE_TIMEOUT_MS, omitEnv: ALL_CREDENTIAL_ENV });
         if (version.notFound) {
-            return { provider, state: "unavailable", reason: `\`${facts.binary}\` is not installed on this runner's PATH`, probe: "version" };
+            return { provider, state: "unavailable", reason: `\`${facts.binary}\` is not installed on this runner's PATH`, probe: PATH_PROBE };
         }
         if (version.timedOut || version.code !== 0) {
             return { provider, state: "unavailable", reason: `\`${facts.binary} --version\` ${version.timedOut ? "timed out" : `exited ${version.code}`}`, probe: "version" };
@@ -440,29 +275,30 @@ acpChecked) {
         if (facts.requiresEnv !== null && (env[facts.requiresEnv] ?? "") === "") {
             return { provider, state: "unavailable", reason: `${facts.requiresEnv} is absent from this runner's environment`, probe: "key" };
         }
-        // A key-driven provider (openrouter rides the codex harness on an API
-        // key) is ready on key PRESENCE — presence, never authorization — and
-        // needs no harness login. A login-driven one asks the harness.
         if (facts.requiresEnv !== null) {
             return { provider, state: "ready", reason: `installed (${installed}); ${facts.requiresEnv} present (presence, not authorization)`, probe: "key" };
         }
         if (facts.identityProbe !== null) {
             const identity = await probe(facts.binary, [...facts.identityProbe], { timeoutMs: READINESS_PROBE_TIMEOUT_MS, omitEnv: ALL_CREDENTIAL_ENV });
+            const asked = `\`${facts.binary} ${facts.identityProbe.join(" ")}\``;
+            if (!identity.timedOut && identity.code === 1 && /not logged in/i.test(`${identity.stdout}\n${identity.stderr}`)) {
+                return { provider, state: "unavailable", reason: `${asked} says not logged in`, probe: "identity" };
+            }
             if (identity.code !== 0) {
-                return { provider, state: "unavailable", reason: `\`${facts.binary} ${facts.identityProbe.join(" ")}\` says not logged in`, probe: "identity" };
+                return { provider, state: "unavailable", reason: `${asked} ${identity.timedOut ? "timed out" : `exited ${identity.code}`}`, probe: IDENTITY_FAILED_PROBE };
             }
             const who = identity.stdout.trim().split("\n")[0] ?? "";
             return { provider, state: "ready", reason: `installed (${installed}); ${who === "" ? "logged in" : who}`, probe: "identity" };
         }
+        if (provider === "claude" && claudeMode() === "subscription") {
+            const status = await probe(facts.binary, ["auth", "status", "--json"], { timeoutMs: READINESS_PROBE_TIMEOUT_MS, omitEnv: ALL_CREDENTIAL_ENV });
+            if (signInFacts("claude", status).state === "signed-out") {
+                return { provider, state: "unavailable", reason: "`claude auth status` says not logged in", probe: LOGIN_PROBE };
+            }
+        }
         return { provider, state: "unknown", reason: `installed (${installed}); no non-spending login check exists — a real run is the proof`, probe: "version" };
     }));
 }
-/**
- * Record a runner's observations under its OWN authenticated name: the
- * credential is verified and the rows written in one transaction, so a
- * replaced incarnation cannot report for its successor, and no caller can
- * report for a machine it does not hold the token of.
- */
 export function reportProviderReadinessAuthed(store, args, now) {
     return store.transact(() => {
         const auth = authenticate(store, args.name, args.token);
@@ -472,13 +308,7 @@ export function reportProviderReadinessAuthed(store, args, now) {
         return auth;
     });
 }
-// ---- v137 lifecycle (docs/plans/actors-lessons.md): last in the file, so the reviewed function positions stay ----
-/** A worker's lifecycle row (service_lifecycle). */
 export const workerComponent = (name) => `worker:${name}`;
-/**
- * The stop begins (durable-actors' draining report), fenced by this holder's credential: from now this runner takes
- * no new work (claim.ts acquire refuses). `until` is a schedule, never proof that the holder exited.
- */
 export function drainRunnerIfCurrent(store, name, token, now, until) {
     return store.transact(() => {
         const auth = authenticate(store, name, token);
@@ -487,8 +317,6 @@ export function drainRunnerIfCurrent(store, name, token, now, until) {
         return reportLifecycle(store, workerComponent(name), "draining", auth.runner.registeredAt, now, { drainUntil: until });
     });
 }
-/** A runner's drain as its own lifecycle row reports it (only the current registration's row counts): null when it
- * isn't draining; ended once its bound passed or it reported stopped. */
 export function drainOf(store, runner, now) {
     const row = lifecycleOf(store, workerComponent(runner.name));
     if (row === null || row.holder !== runner.registeredAt)

package/dist/sample-project.js

@@ -1,20 +1,9 @@
-/**
- * The sample project the welcome offers ("Try a sample project"): a small real git repository — a README, one function
- * and its test — made in the project folder, so a first task has something true to change. It is registered like any
- * other project by its caller (project-admission.ts).
- *
- * The folder is claimed with an exclusive mkdir; a folder already there is used again only when it is ours (a real
- * directory, not a link, holding our marker inside its .git), and refused otherwise: nothing in someone else's folder
- * is touched. Git runs hardened (no system or global config, no hooks or hook templates, no fsmonitor, no signing, no
- * prompts, an allowlisted environment), and a folder this call made is removed again when making it fails.
- */
 import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { run } from "./exec.js";
 import { SAMPLE_PROJECT_NAME } from "./first-run.js";
 import { ENV, ENV_ALLOWLIST } from "./remote-main.js";
 import { TEARDOWN_FLAGS } from "./teardown-git.js";
-/** Inside the sample's .git: says the folder is the one this made (never tracked, so the work tree stays clean). */
 const MARKER = "toolroll-sample";
 const MARKER_TEXT = "Made by Toolroll's welcome as the sample project.\n";
 const FILES = {
@@ -46,7 +35,6 @@ test("takes the discount off the price", () => {
 `,
     ".gitignore": "node_modules/\n",
 };
-/** Git for the sample: fixed settings first, an allowlisted environment with no system or global config. */
 const SAMPLE_FLAGS = [
     ...TEARDOWN_FLAGS, "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false", "-c", "init.templateDir=",
     "-c", "user.name=Toolroll", "-c", "user.email=sample@toolroll.invalid", "-c", "core.autocrlf=false",
@@ -60,7 +48,6 @@ function kindOf(path) {
         return error.code === "ENOENT" ? "missing" : "other";
     }
 }
-/** Ours: a real folder whose .git is a real folder holding our marker, a regular file with our words. */
 function isOurs(target) {
     if (kindOf(target) !== "dir" || kindOf(join(target, ".git")) !== "dir")
         return false;
@@ -73,7 +60,6 @@ function isOurs(target) {
         return false;
     }
 }
-/** Make (or find again) the sample project in `root`, the folder projects go in. */
 export async function createSampleProject(root, git = run) {
     if (root === null || root === "" || !isAbsolute(root) || kindOf(root) !== "dir") {
         return { ok: false, reason: "no-root", message: "There's no project folder to put the sample in." };
@@ -82,7 +68,7 @@ export async function createSampleProject(root, git = run) {
     if (isOurs(target))
         return { ok: true, path: target, created: false };
     try {
-        mkdirSync(target); // the claim: exclusive, and never through a link
+        mkdirSync(target);
     }
     catch {
         return { ok: false, reason: "exists", message: `A folder named ${SAMPLE_PROJECT_NAME} is already there, so nothing was changed.` };
@@ -91,7 +77,7 @@ export async function createSampleProject(root, git = run) {
         try {
             rmSync(target, { recursive: true, force: true });
         }
-        catch { /* left for a person to remove */ }
+        catch { }
         return { ok: false, reason: "failed", message: "The sample project couldn't be made. Nothing was added." };
     };
     try {
@@ -113,20 +99,9 @@ export async function createSampleProject(root, git = run) {
     }
     return { ok: true, path: target, created: true };
 }
-/** The sample's own check: its one test file, run by Node's test runner. Fixed here; never anyone's input. */
 export const SAMPLE_CHECK_COMMAND = "node --test";
 const SAMPLE_CHECK_TIMEOUT_MS = 60_000;
-/** Who the sample's check is recorded as approved by: Toolroll itself, never the person who clicked (no step-up). */
 export const SAMPLE_CHECK_ACTOR = "toolroll";
-/**
- * The sample project's check, set as part of making it, so its first result reads checked: the fixed command above,
- * recorded as Toolroll's (SAMPLE_CHECK_ACTOR), with the person who added the sample named in the ledger line. Only
- * for a sample this request just made (the caller passes createSampleProject's `created: true`; a folder found again
- * is never armed), only for the folder this made (our marker in its .git), and only while the project has never had
- * a check at all (no verify_command row, live or revoked, for it or its quick check): a check someone cleared stays
- * cleared, and one someone approved is never replaced. It takes no command: this is not a way to set a project's
- * check. True when it set one now.
- */
 export function registerSampleCheck(store, made, repo, addedBy, now) {
     if (!made.created || !isAbsolute(repo) || !isOurs(repo))
         return false;

package/dist/sandbox-launch.js

@@ -1,20 +1,8 @@
-/**
- * The Linux launch helper (sandbox-runtime.ts): `node sandbox-launch.js`, handed one launch in its environment
- * (TOOLROLL_SANDBOX_LAUNCH). It changes into the launch's folder (Anthropic's sandbox-runtime anchors its mandatory
- * write denies there), starts the runtime's network relays to this run's proxy when the network is confined, asks the
- * runtime for the bubblewrap + seccomp command, runs it (setting it up again, from a fresh look, if the sandbox failed
- * before the launch itself started), passes on the signals it gets, and when the command ends removes the mount points
- * the runtime made and stops the relays. It exits with the command's status. Nothing runs if
- * the runtime refuses: the helper exits 126 with the reason.
- */
 import { spawn } from "node:child_process";
 import { checkLinuxDependencies, cleanupBwrapMountPoints, getLinuxDependencyStatus, initializeLinuxNetworkBridge, wrapCommandWithSandboxLinux } from "@anthropic-ai/sandbox-runtime/dist/sandbox/linux-sandbox-utils.js";
 import { SANDBOX_LAUNCH_SPEC, shellQuote, withRuntimeTemp } from "./sandbox-runtime.js";
 const REFUSED = 126;
-/** The status a launch stopped before it ran ends with (128 + SIGTERM). */
 const STOPPED = 143;
-/** Why the runtime can't sandbox here now (bubblewrap, socat or its seccomp helper gone), or null: asked again before
- * each attempt, never remembered from an earlier look. */
 function missing() {
     const checked = checkLinuxDependencies();
     if (checked.errors.length > 0)
@@ -30,18 +18,15 @@ async function main() {
     }
     const spec = JSON.parse(raw);
     process.chdir(spec.cwd);
-    // A stop at any point: what is running is passed it, and nothing starts after it.
     let stopping = false;
     let child = null;
     for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
         process.on(signal, () => { stopping = true; try {
             child?.kill(signal);
         }
-        catch { /* gone */ } });
+        catch { } });
     const network = spec.terms.network;
     let bridge = null;
-    // The relays share the launch's process group: they are waited for (SIGKILL after a moment), so when the helper exits
-    // nothing of the launch is left in it to read as the agent's leftover.
     const stopBridge = async () => {
         await Promise.all([bridge?.httpBridgeProcess, bridge?.socksBridgeProcess].map(one => new Promise(done => {
             if (one === undefined || one.exitCode !== null || one.signalCode !== null) {
@@ -51,7 +36,7 @@ async function main() {
             const force = setTimeout(() => { try {
                 one.kill("SIGKILL");
             }
-            catch { /* gone */ } }, 1_000);
+            catch { } }, 1_000);
             one.once("exit", () => { clearTimeout(force); done(); });
             try {
                 one.kill("SIGTERM");
@@ -65,17 +50,12 @@ async function main() {
     try {
         if (network.kind === "proxy")
             bridge = await initializeLinuxNetworkBridge(network.httpPort, network.socksPort ?? network.httpPort);
-        // The runtime reads the temp folder it gives the command when it builds it (withRuntimeTemp, sandbox-runtime.ts).
         if (spec.temp !== undefined)
             process.env["CLAUDE_CODE_TMPDIR"] = spec.temp;
         else
             withRuntimeTemp(undefined, () => undefined);
-        // The command first says it started, on a descriptor of its own (3), before anything of the launch runs. A sandbox
-        // whose setup failed (bubblewrap couldn't mount over a path another launch removed after the runtime looked)
-        // never ran the launch, so it is set up again from a fresh look, a few times; one that started is never re-run.
         const started = `printf 1 >&3 || exit 125; exec 3>&-; exec ${shellQuote([spec.file, ...spec.args])}`;
         for (let attempt = 1;; attempt++) {
-            // Stopped during setup or between attempts: nothing starts.
             if (stopping)
                 return STOPPED;
             const gone = missing();
@@ -92,7 +72,6 @@ async function main() {
                 readConfig: spec.terms.readConfig,
                 writeConfig: spec.terms.writeConfig,
             });
-            // bubblewrap, and the runtime's seccomp filter inside it: anything less is not this sandbox.
             if (!/\bbwrap\b/.test(command) || !command.includes("apply-seccomp"))
                 throw new Error("the sandbox runtime returned a command without its sandbox or its seccomp filter");
             if (stopping)
@@ -126,7 +105,7 @@ async function main() {
             try {
                 cleanupBwrapMountPoints();
             }
-            catch { /* the next look is fresh either way */ }
+            catch { }
             await new Promise(done => setTimeout(done, 50 * attempt));
         }
     }
@@ -141,7 +120,7 @@ async function main() {
         try {
             cleanupBwrapMountPoints();
         }
-        catch { /* best effort: the runtime's own exit handler retries */ }
+        catch { }
         await stopBridge();
     }
 }