toolroll 0.9.104 → 0.9.105

package/dist/probe.js

@@ -1,28 +1,6 @@
-/**
- * Asking an environment whether it has what the work needs.
- *
- * A probe is an operator-authored command line whose exit 0 means "present
- * and alive": `gh auth status`, `test -n "$SUPABASE_KEY"`. It runs through
- * a real shell, deliberately — the design's own examples need expansion and
- * `test` — and that is safe only because of who wrote it: probes are stored
- * by the operator, at `cap add`, with the author recorded. Nothing an agent
- * or a scanned repository writes is ever executed as a probe; the scanner
- * synthesizes probes from a fixed template over validated identifiers or
- * stores none at all.
- *
- * The answer is a claim about one machine at one moment. `verified` carries
- * when and by whom; anything else carries the probe's own words — "exit 1",
- * "timed out", "sh not found" — because collapsing those to a bit discards
- * exactly what tells an operator whether to paste a key or fix a PATH.
- */
 import { run, NOT_FOUND_CODE, OVERFLOW_CODE, TIMEOUT_CODE, } from "./exec.js";
 import {} from "./store.js";
-/** Probes are cheap questions; one that hangs is already an answer. */
 export const PROBE_TIMEOUT_MS = 10_000;
-/**
- * Whether a capability is verified *right now*: a stale yes is not a yes.
- * Presence is not enough, and neither is a verification whose expiry passed.
- */
 export function isVerified(capability, now) {
     if (capability.status !== "verified")
         return false;
@@ -30,12 +8,9 @@ export function isVerified(capability, now) {
         return true;
     return capability.expiresAt > now.toISOString();
 }
-/** Run one capability's probe and record what it said. */
 export async function probeOne(store, capability, by, now, runner = run, env) {
     const { kind, name } = capability;
     if (capability.probe === null) {
-        // Nothing can vouch for it, and nobody may vouch by hand (§3: presence
-        // is not enough — an assertion is even less). It stays a visible gap.
         return { kind, name, status: "unprobed", detail: "no probe — only a probe can verify" };
     }
     const asked = await runner("sh", ["-lc", capability.probe], {
@@ -51,11 +26,6 @@ export async function probeOne(store, capability, by, now, runner = run, env) {
     store.markCapability(capability.repo, kind, name, { status: "failed", by, detail }, now);
     return { kind, name, status: "failed", detail };
 }
-/**
- * Probe a repo's capabilities — all of them, or the named subset. Statuses
- * land in the store as each probe answers; the returned outcomes are for
- * reporting, not the source of truth.
- */
 export async function probeRepo(store, repo, by, now, options = {}) {
     const outcomes = [];
     for (const capability of store.listCapabilities(repo)) {

package/dist/process-custody.js

@@ -1,4 +1,3 @@
-/** Existing append-only ledger; a diagnostic is not exit evidence. */
 export function recordProcessObservationFailure(store, runId, now, failure) {
     const run = store.getRun(runId);
     const ref = run === null ? null : store.refById(run.taskRef);
@@ -6,14 +5,10 @@ export function recordProcessObservationFailure(store, runId, now, failure) {
         taskId: ref?.externalId ?? null, runId, action: "process observation failed", source: "work",
         outcome: JSON.stringify(failure) });
 }
-/** Preserve observed IDs through the existing serialized write boundary. This
- * writes process facts only; it does not declare exit or replay observers. */
 export function preserveObservedProcesses(store, runId, now, rows) {
     const first = rows[0];
     if (!first)
         return false;
-    // Reserve BEFORE waiting for the batch transaction. A crash/rollback leaves
-    // this new guard intact; no old unknown witness is reused or cleared.
     const witness = store.reserveRunProcess(runId, now, first.group);
     store.transact(() => {
         store.recordRunProcess(runId, first.pid, now, first.group, witness);
@@ -22,12 +17,6 @@ export function preserveObservedProcesses(store, runId, now, rows) {
     });
     return true;
 }
-/** Reserve each spawn before the OS call. A crash before its PID is recorded
- * leaves an explicit unknown, even if earlier setup/check processes exited.
- * Only the returning transport can certify that its reserved spawn made no child.
- * Retained PIDs are read-only witnesses, never authority to signal a process.
- * A native OS object (v53) rides the same witness: named at the spawn, and
- * marked empty only when the OS proved it so — never on a transport exit. */
 export function witnessedRunner(store, runId, clock, runner) {
     return async (file, args, options = {}) => {
         const witnesses = [];
@@ -39,8 +28,6 @@ export function witnessedRunner(store, runId, clock, runner) {
                 store.recordRunProcess(runId, pid, clock(), group);
                 options.onDescendant?.(pid, group);
             },
-            // External custody callbacks retain the conservative failure path;
-            // replaying them could repeat non-idempotent side effects.
             onDescendantWriteFailure: rows => options.onDescendant === undefined
                 && preserveObservedProcesses(store, runId, clock(), rows),
             onDescendantExit: (pid, group) => {
@@ -69,8 +56,6 @@ export function witnessedRunner(store, runId, clock, runner) {
                 store.recordRunProcess(runId, pid, clock(), options.processGroup === true, witnesses.at(-1));
                 options.onSpawn?.(pid);
             },
-            // The spawn made no process (ENOENT, EAGAIN, a throw): its reservation
-            // settles as never started now, not only if the transport returns.
             onSpawnFailed: () => {
                 const witness = witnesses.at(-1);
                 if (witness !== undefined)

package/dist/process-liveness.js

@@ -1,14 +1,10 @@
 import { execFileSync } from "node:child_process";
-/** Only the exact UTC millisecond format stored by the writer is evidence. */
 function timestamp(value) {
     if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value))
         return null;
     const ms = Date.parse(value);
     return Number.isFinite(ms) && new Date(ms).toISOString() === value ? ms : null;
 }
-/** A whole `ps` lstart (locale C, UTC) as the earliest moment that process can have started, or null. The displayed
- * second is a lower bound, not a rounded millisecond identity. Never lets Date.parse guess a locale, a timezone or an
- * invalid calendar date. */
 function birthOf(lstart) {
     const match = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{1,2}) (\d{2}:\d{2}:\d{2}) (\d{4})$/.exec(lstart.trim().replace(/ +/g, " "));
     if (match === null)
@@ -27,28 +23,15 @@ function newerMacProcess(pid, witness) {
         const start = birthOf(execFileSync("/bin/ps", ["-p", String(pid), "-o", "lstart="], {
             encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
             stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1024,
-            // Bound only this owned diagnostic child, never an agent or task.
-            // A stalled/oversized lookup throws and leaves the witness occupied.
             timeout: 1_000, killSignal: "SIGKILL",
         }));
-        // Same-second observations are ambiguous. Reservations can precede
-        // spawn, so also require birth AFTER the owning run ended.
         return start !== null && start > Math.max(observed, finished);
     }
     catch {
         return false;
     }
 }
-/** How long a run must have been over before a number its group once held can be read as someone else's. */
 export const REUSED_GROUP_AFTER_MS = 10 * 60_000;
-/**
- * Whether a group whose exit is recorded is now a different group under the same number (macOS; run 3313's pid-less
- * witness waited on three numbers MTLCompilerService and dataaccessd had taken). A recorded group exit was proved when
- * it was written (no member left, a newer process holding the number, or a reboot), so the proof here only has to
- * show that whoever holds the number came later: the run is over and old, and every process now in the group was
- * born after that exit, or after the run ended if the exit was recorded later than that. A member older than that,
- * an empty or unreadable table, or any line that can't be read leaves the group occupied. Nothing is signalled.
- */
 function groupTakenSinceExit(pgid, witness) {
     if (process.platform !== "darwin" || witness === undefined)
         return false;
@@ -81,14 +64,7 @@ function groupTakenSinceExit(pgid, witness) {
         return false;
     }
 }
-/** Read-only checks of retained process witnesses. Saved PIDs authorize no
- * signal. ESRCH or proven macOS PID reuse establishes absence; everything
- * unknown stays occupied. This concerns the historical identity, not whether
- * the numeric PID/PGID is currently populated by unrelated processes. */
 export function processMayBeAlive(pid, group, witness) {
-    // A recorded single-process exit is final: this number can now belong to
-    // someone else, even before the run ends. A leader's exit proves nothing
-    // about its group's remaining members, so groups keep the OS probe.
     if (!group && witness?.exitedAt != null)
         return false;
     if (!Number.isSafeInteger(pid) || pid <= 0)
@@ -105,12 +81,6 @@ export function processMayBeAlive(pid, group, witness) {
             else if (code !== "EPERM")
                 return true;
         }
-        // Darwin's forkproc excludes existing PIDs, PGIDs and session IDs under
-        // proc_list_lock. A proven newer PID EQUAL to the saved PGID therefore
-        // implies the old group ended before allocation, even if a new group now
-        // uses that number. A new member or an absent leader proves nothing,
-        // unless the group's exit is already on record (groupTakenSinceExit).
-        // See docs/assessments/UPDATE_PID_REUSE_2026-09-15.md, recovery attempt 2.
         if (!absent)
             return !newerMacProcess(pid, witness) && !groupTakenSinceExit(pid, witness);
     }
@@ -123,8 +93,6 @@ export function processMayBeAlive(pid, group, witness) {
             return false;
         if (code !== "EPERM")
             return true;
-        // Signal permission and readable birth identity are independent. EPERM
-        // alone proves nothing; a failed/ambiguous ps read still stays occupied.
     }
     return !newerMacProcess(pid, witness);
 }

package/dist/process-tree.js

@@ -2,7 +2,6 @@ import { execFileSync } from "node:child_process";
 import { processMayBeAlive } from "./process-liveness.js";
 const observed = new Map();
 let timer = null;
-/** Read identifiers only: command lines can contain private provider inputs. */
 function snapshot() {
     return execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid="], { encoding: "utf8", timeout: 2000, maxBuffer: 4 * 1024 * 1024 })
         .trim().split("\n").map(line => {
@@ -31,7 +30,6 @@ function remember(child, rows, phase) {
     const tracked = observed.get(child);
     if (!tracked)
         return;
-    // Keep the entire observed set before a persistence callback can throw.
     const fresh = rows.map(row => ({ pid: row.pid, group: row.group === row.pid }))
         .filter(row => !tracked.seen.has(`${row.pid}:${row.group}`));
     for (let index = 0; index < fresh.length; index++) {
@@ -40,8 +38,6 @@ function remember(child, rows, phase) {
             tracked.observer.onDescendant?.(row.pid, row.group);
         }
         catch (error) {
-            // A stop must not signal from a snapshot made stale by waiting for a
-            // fallback write. Preserve its existing conservative failure path.
             if (phase === "stop")
                 throw error;
             const remaining = fresh.slice(index);
@@ -49,7 +45,7 @@ function remember(child, rows, phase) {
             try {
                 preserved = tracked.observer.onDescendantWriteFailure?.(remaining) === true;
             }
-            catch { /* The unknown safeguard remains. */ }
+            catch { }
             if (!preserved)
                 throw error;
             for (const one of remaining)
@@ -68,15 +64,12 @@ function recordExits(child, rows) {
     for (const [key, prior] of tracked.seen) {
         if (pids.has(prior.pid) || (prior.group && groups.has(prior.pid)))
             continue;
-        // A missing ancestry edge proves nothing. Require both the complete
-        // system snapshot and an ESRCH-only probe; no birth inference or signal.
         if (processMayBeAlive(prior.pid, prior.group))
             continue;
         tracked.observer.onDescendantExit?.(prior.pid, prior.group);
-        tracked.seen.delete(key); // The same number can later identify a NEW child.
+        tracked.seen.delete(key);
     }
 }
-// Only fixed error codes survive; error messages/output can contain private data.
 const observationCodes = new Set(["EAGAIN", "EMFILE", "ENFILE", "ETIMEDOUT", "ENOBUFS", "ENOENT", "EPERM", "EACCES", "EIO", "ESRCH", "MALFORMED_SNAPSHOT", "SUPERVISOR_DIAGNOSTIC", "SQLITE_BUSY", "SQLITE_LOCKED", "SQLITE_READONLY", "SQLITE_IOERR", "SQLITE_CORRUPT", "SQLITE_FULL", "SQLITE_CONSTRAINT"]);
 function failed(child, phase, operation, error, identitiesPreserved = false) {
     const tracked = observed.get(child);
@@ -87,9 +80,6 @@ function failed(child, phase, operation, error, identitiesPreserved = false) {
     const sqlite = typeof error === "object" && error !== null && "errcode" in error && Number.isSafeInteger(error.errcode)
         ? sqliteCodes[Number(error.errcode) & 0xff] : undefined;
     const code = sqlite ?? (typeof rawCode === "string" && observationCodes.has(rawCode) ? rawCode : "UNKNOWN");
-    // Exit-only checks retire already-durable identities; they discover no
-    // children. Any failure leaves those witnesses intact for later OS probes.
-    // Discovery and descendant persistence failures can lose an identity.
     const identityUnknown = !identitiesPreserved && phase !== "final-exit" && operation !== "exit-write";
     const key = `${phase}:${operation}:${code}:${identityUnknown}`;
     if (!tracked.failures.has(key)) {
@@ -97,11 +87,9 @@ function failed(child, phase, operation, error, identitiesPreserved = false) {
             tracked.observer.onObservationFailure?.({ phase, operation, code, rootPid: child.pid ?? null, at: new Date().toISOString(), identityUnknown });
             tracked.failures.add(key);
         }
-        catch { /* No diagnostic, but no witness was retired by this callback. */ }
+        catch { }
     }
     if (identityUnknown) {
-        // A failed persistence callback never becomes an uncaught timer error or
-        // permission to release custody. The existing unknown road stays closed.
         try {
             tracked.observer.onUnknown?.();
         }
@@ -122,9 +110,6 @@ function observeRows(child, rows, phase) {
         failed(child, phase, "descendant-write", error);
     }
 }
-/** Capture current descendants before asking an owned process to exit.
- * A cooperative root may exit before the next periodic observation; even
- * a killed tool can retain its PID briefly after its process group is gone. */
 export function sampleProcessTree(child) {
     if (!live(child) || !observed.has(child))
         return;
@@ -138,9 +123,6 @@ export function sampleProcessTree(child) {
     }
     observeRows(child, rows, "sample");
 }
-/** Observe escaped process groups while their ancestry is still provable.
- * Durable witnesses prevent recovery from mistaking a dead harness for a dead
- * shell. They never grant permission to send a signal after worker recovery. */
 export function observeProcessTree(child, observer) {
     if (process.platform === "win32" || observer.onDescendant === undefined)
         return;
@@ -188,11 +170,6 @@ export function observeProcessTree(child, observer) {
     }, 500);
     timer.unref();
 }
-/** Freeze the owned handle, then its live descendants before killing them.
- * Claude's tool shells create new process groups, so killing only -rootPid
- * leaves writers behind. Re-scan after freezing parents to catch a child born
- * during the previous scan. Every target comes from current ancestry of the
- * still-owned handle, never from a saved PID. Unknown ancestry stays blocked. */
 export function stopProcessTree(child) {
     if (process.platform === "win32" || !live(child))
         return false;
@@ -209,7 +186,6 @@ export function stopProcessTree(child) {
             operation = "signal";
             const fresh = rows.filter(row => !stopped.has(row.pid));
             if (fresh.length === 0) {
-                // Parents are frozen, so none can fork between this seal and kill.
                 for (const row of rows.reverse()) {
                     try {
                         process.kill(row.pid, "SIGKILL");
@@ -237,8 +213,6 @@ export function stopProcessTree(child) {
     }
     catch (error) {
         failed(child, "stop", operation, error);
-        // Do not leave any process frozen after a failed observation. The caller
-        // can still stop its known group; unresolved custody prevents Resume.
         for (const pid of stopped) {
             try {
                 process.kill(pid, "SIGCONT");

package/dist/project-access.js

@@ -10,7 +10,6 @@ export function normalizeProjectAccess(value) {
     }
     return [...new Set(value.map(path => canonicalProject(path) ?? resolve(path)))].sort();
 }
-/** Corrupt or missing authority never falls back to instance access. */
 export function readProjectAccess(value) {
     if (value === null)
         return null;
@@ -18,8 +17,6 @@ export function readProjectAccess(value) {
         const parsed = JSON.parse(String(value));
         if (!Array.isArray(parsed) || parsed.length > 100 || parsed.some(path => typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path || path.length > 4096 || /[\x00-\x1f\x7f]/.test(path)))
             return [];
-        // Preserve the granted identity. Re-canonicalizing stored grants after
-        // a symlink changes would transfer access to its new target.
         return parsed;
     }
     catch {
@@ -31,8 +28,6 @@ export function projectAccessAllows(access, repo) {
         return true;
     if (repo === null)
         return false;
-    // A folder the console's gate holds back (folder-gate.ts) is unavailable: access to it is denied, never decided by
-    // its spelling.
     try {
         return access.includes(canonicalProject(repo) ?? resolve(repo));
     }
@@ -42,10 +37,5 @@ export function projectAccessAllows(access, repo) {
         throw error;
     }
 }
-/** SQL: projectAccessAllows for an `approver` row (`alias`) and a project path expression, for the dispatch belts. A
- * null list reaches every project; an unreadable one reaches none. */
 export const accountReachesSql = (alias, repo) => `(${alias}.projects_json IS NULL OR (json_valid(${alias}.projects_json) AND EXISTS (SELECT 1 FROM json_each(${alias}.projects_json) WHERE json_each.value = ${repo})))`;
-/** A server-proved resource, never an unchecked header or submitted path.
- * CLI ceremonies must pass their resource explicitly; global ceremonies
- * without a project refuse project-scoped credentials. */
 export const projectAuthority = new AsyncLocalStorage();

package/dist/project-admission.js

@@ -1,15 +1,3 @@
-/**
- * Adding and removing projects: the ONE road for the command line, the lead
- * and the console's own "Add a project". A project is admitted when its
- * folder is proved to be a Git repository, canonicalized to its checkout
- * root, saved in the store's project list, and enrolled in the machine's
- * locked project registry; a running `up` adopts it from there without a
- * restart. Each change is one ledger row naming who made it and from where.
- *
- * Removing is reversible: the project leaves the lists and the builder, and
- * its tasks, results and settings stay saved. Deleting everything Toolroll
- * holds for a project is project-delete.ts, behind its own confirmation.
- */
 import { statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -24,12 +12,10 @@ const ADMISSION_GIT = {
 };
 export const PROJECT_ADDED = "project added";
 export const PROJECT_REMOVED = "project removed";
-/** The checkout root a folder belongs to, canonical; never a shell. */
 export async function proveProjectRoot(path, exec = run, resolveFolder) {
     if (path.trim() === "" || path.length > 4096 || /[\x00-\x1f]/.test(path)) {
         return { ok: false, reason: "unavailable", message: "Choose a valid project folder." };
     }
-    // The console resolves both folders off its thread (project-identity.ts resolveNow): its thread never waits on one.
     const canon = async (one) => resolveFolder === undefined ? canonicalProject(one) : resolveFolder(one);
     const didntAnswer = (one) => ({ ok: false, reason: "unavailable", message: `${one} didn't answer. It may be on a drive that's disconnected, or waiting on macOS; try again in a moment.` });
     const canonical = await canon(path);
@@ -46,7 +32,6 @@ export async function proveProjectRoot(path, exec = run, resolveFolder) {
         return { ok: false, reason: "not-git", message: `${path} isn't a Git repository. Run git init there first, or choose a folder inside one.` };
     return { ok: true, repo };
 }
-/** Read only on first CLI admission; never rediscover trust from an existing project's config. */
 async function originOf(repo, exec) {
     const read = await exec("git", ["config", "--local", "--no-includes", "--get", "remote.origin.url"], { cwd: repo, timeoutMs: 5_000, ...ADMISSION_GIT });
     const url = read.code === 0 ? read.stdout.trim() : "";
@@ -55,7 +40,6 @@ async function originOf(repo, exec) {
     const problem = remoteUrlProblem(url);
     return problem === null ? { url, why: null } : { url: null, why: problem };
 }
-/** Registry first, then the project and its audit records in one transaction. Re-adds preserve trust. */
 export async function admitProject(store, input) {
     const proved = await proveProjectRoot(input.path, input.exec, input.resolveFolder);
     if (!proved.ok)
@@ -90,7 +74,6 @@ export async function admitProject(store, input) {
         registryHad = had;
     }
     const added = store.transact(() => {
-        // Re-asked with the write; a refusal writes nothing here and takes back the registry line this call added below.
         if (!allowed())
             return null;
         const rowHad = store.listProjects().some(one => one.path === repo);
@@ -113,16 +96,7 @@ export async function admitProject(store, input) {
     }
     return { ok: true, repo, name: projectName(repo), added, remote };
 }
-/**
- * Remove one project from the lists and the builder. Its tasks, results and
- * settings stay saved; adding it again brings it back. A path that isn't a
- * saved project changes nothing.
- */
 export async function releaseProject(store, input) {
-    // Removing only narrows: a folder the console's gate holds back (folder-gate.ts) is removed by its exact saved path,
-    // and matches no other spelling.
-    // Latched for the whole removal: once its folder was unavailable, a later answer (during an await below) never
-    // widens it to other spellings.
     const unavailable = (error) => error instanceof FolderUnavailable;
     let asked, exactOnly = false;
     try {
@@ -168,16 +142,9 @@ export async function releaseProject(store, input) {
     });
     return { ok: true, repo, name: projectName(repo), removed: true };
 }
-/** The registry `up` watches: beside the database, so an isolated database never enrolls into another's list. */
 export function registryBeside(databaseFile) {
     return join(dirname(databaseFile), "repos.json");
 }
-/**
- * Who is adding from the command line. Running it on this computer against
- * a database this user owns is the owner's authority; a lead token acts as
- * `lead for <owner>`, and only for an owner who may manage every project.
- * Any other credential is refused rather than read as the owner.
- */
 export function commandLineActor(store, input) {
     if (input.leadToken !== undefined) {
         const lead = store.leadFor(input.leadToken);
@@ -195,20 +162,13 @@ export function commandLineActor(store, input) {
     }
     return { label: input.user ?? userInfo().username, origin: "cli" };
 }
-/** Whether a builder is running now (its heartbeat is a minute apart), so an addition is in the console within seconds. */
 export function consoleRunning(store, now) {
     return store.listRunners().some(one => one.retiredAt === null && now.getTime() - Date.parse(one.heartbeatAt) < 3 * 60_000);
 }
-/** The one plain line after an addition: where the project is now. */
 export function addedWords(name, added, running) {
-    const where = running ? "it is in the console now" : "it will be in the console when Toolroll starts (toolroll up)";
+    const where = running ? "it is in the console now" : "run `toolroll` to start working on it";
     return added ? `Added ${name}; ${where}.` : `${name} was already added; ${where}.`;
 }
-/**
- * Whether a registry entry carries an admission this boundary recorded:
- * its project row. `up` adopts a project added after it started only with
- * this record, so a hand-edited registry line is not authority by itself.
- */
 export function admissionRecorded(store, repo) {
     return store.listProjects().some(one => one.path === repo);
 }

package/dist/project-cli.js

@@ -1,5 +1,3 @@
-/** Local convenience only: a selected project and optional credential reference.
- * Every action still authenticates against the current database. */
 import { lstatSync, readFileSync, writeFileSync, renameSync, mkdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
@@ -93,8 +91,6 @@ export async function runProjectCommand(positional, flags, context) {
         const refused = profile.tokenFile === null ? null : scopedCredentialRefusal(context.store, profile.tokenFile, profile.repo);
         if (refused)
             return fail(refused.reason, refused.message);
-        // Like assignment brief, an uncredentialed local database read has the
-        // local operator's access. A saved scoped credential is always re-proved.
         const result = projectOutcomes(context.store, profile.repo, context.now ?? new Date(), { principal: 'operator', repos: [profile.repo] });
         context.write(context.json ? envelopeJson({ ok: true, command, result }) : JSON.stringify(result, null, 2));
         return 0;
@@ -103,8 +99,6 @@ export async function runProjectCommand(positional, flags, context) {
     context.write(context.json ? envelopeJson({ ok: true, command, result }) : profile === null ? 'No project selected. Use project use <saved checkout path>.' : `${profile.repo}${result.saved ? '' : ' (no longer saved)'}\n${profile.tokenFile === null ? 'Uses your existing local sign-in for operator actions.' : `Scoped credential reference: ${profile.tokenFile}`}`);
     return 0;
 }
-/** Only known credential-aware adapters consume the remembered reference.
- * Explicit credentials always win; no legacy action gains implicit authority. */
 export function applyProjectProfile(command, positional, flags, databaseFile) {
     const scoped = command === 'assignment' || command === 'knowledge' || (command === 'brief' && !flags.has('history')) ||
         (command === 'task' && ['complete', 'revise'].includes(positional[0] ?? ''));

package/dist/project-concurrency.js

@@ -1,26 +1,13 @@
-/**
- * How many tasks of one project the service builds at once, and which
- * project gets a free slot when several are waiting.
- *
- * The number is a per-project setting an approver changes (Settings →
- * Projects, or `toolroll project concurrency <n> --repo <p>`), kept in a
- * small file beside the database and recorded in the ledger as before →
- * after. A project without a saved number builds up to two at once. The
- * worker's own capacity always caps the total: a project's number above
- * it means "as many as the worker has".
- */
 import { lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
 import { RUNNER_CAPACITY_MAX } from "./runner.js";
 export const PROJECT_CONCURRENCY_DEFAULT = 2;
 export const projectConcurrencyPath = (databaseFile) => join(dirname(databaseFile), "project-concurrency.json");
-/** A number as typed: a whole number from 1 to RUNNER_CAPACITY_MAX, or null. */
 export function parseProjectConcurrency(value) {
     const n = Number(value.trim());
     return value.trim() !== "" && Number.isInteger(n) && n >= 1 && n <= RUNNER_CAPACITY_MAX ? n : null;
 }
-/** Every saved number, by canonical project path. An unreadable file reads as none saved. */
 export function savedProjectConcurrency(databaseFile) {
     const saved = new Map();
     const file = projectConcurrencyPath(databaseFile);
@@ -38,15 +25,12 @@ export function savedProjectConcurrency(databaseFile) {
         }
     }
     catch {
-        // A damaged file never stops building: every project falls back to the default.
     }
     return saved;
 }
-/** The project's own number: saved, or the default. */
 export function projectConcurrency(databaseFile, repo) {
     return savedProjectConcurrency(databaseFile).get(repo) ?? PROJECT_CONCURRENCY_DEFAULT;
 }
-/** Save one project's number atomically; returns the number before and after. */
 export function saveProjectConcurrency(databaseFile, repo, n) {
     const saved = savedProjectConcurrency(databaseFile);
     const before = saved.get(repo) ?? PROJECT_CONCURRENCY_DEFAULT;
@@ -58,21 +42,12 @@ export function saveProjectConcurrency(databaseFile, repo, n) {
     renameSync(temp, file);
     return { before, after: n };
 }
-/** What a project actually gets on one worker: its number, never above the worker's capacity. */
 export function effectiveConcurrency(setting, capacity) {
     return Math.max(1, Math.min(setting, capacity));
 }
-/**
- * The in-process record of when each project's builder last finished a
- * pass, shared by every project loop of one service. A project that yields
- * a free slot to another waits only until that project has had a pass to
- * take it: a waiting project that cannot use the slot (a missing tool, a
- * paused provider) never holds a busy one back for long.
- */
 export class ProjectPasses {
     finished = new Map();
     tick = 0;
-    /** A monotonic stamp, so ordering never depends on the wall clock. */
     stamp() {
         return ++this.tick;
     }
@@ -83,16 +58,6 @@ export class ProjectPasses {
         return this.finished.get(repo) ?? 0;
     }
 }
-/**
- * May a build lane of `repo` start one more task now?
- *
- * - never past the project's own number (capped by the worker's capacity);
- * - never past the worker's capacity;
- * - fair share: a project already building yields a free slot to any other
- *   project with ready work that is building fewer, until that project has
- *   had a pass to take it. A project building nothing never yields, so every
- *   project with work gets its first build ahead of another's second.
- */
 export function maySlotTake(facts) {
     const here = facts.running.get(facts.repo) ?? 0;
     const total = [...facts.running.values()].reduce((sum, n) => sum + n, 0);