toolroll 0.9.103 → 0.9.105

package/dist/releases.js

@@ -1,31 +1,17 @@
-/**
- * Knowing, calmly, when a newer Toolroll exists.
- *
- * At most once a day one anonymous GET asks the npm registry for the latest
- * version, and one more reads that version's GitHub release notes (the body
- * only). Nothing identifies this installation: no telemetry, no id, no
- * query string. The answer is cached in a small JSON file beside the
- * database; offline or any other failure is silent and changes nothing.
- * TOOLROLL_NO_UPDATE_CHECK=1 or the switch on Settings → Updates turns the
- * check off entirely.
- */
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { envValue } from "./names.js";
 export const RELEASE_CACHE_FILE = "latest-release.json";
-/** Holds "off" while a person has switched the daily check off on Settings → Updates. */
 export const UPDATE_SWITCH_FILE = "update-check";
 export const RUNNER_VERSIONS_FILE = "runner-versions.json";
 export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
 export const CHECK_TIMEOUT_MS = 5_000;
-/** The npm registry `toolroll update` downloads releases from. */
 export const REGISTRY = "https://registry.npmjs.org";
 export const REGISTRY_URL = `${REGISTRY}/toolroll/latest`;
 export const RELEASES_PAGE = "https://github.com/ap9000/toolroll/releases/tag/";
 const NOTES_API = "https://api.github.com/repos/ap9000/toolroll/releases/tags/";
 const NOTES_MAX = 20_000;
 const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,40})?$/;
-/** Off by the environment (it wins) or by the Settings switch. */
 export function updateChecksOff(env, dir) {
     const flag = envValue(env, "NO_UPDATE_CHECK");
     if (flag !== undefined && flag !== "" && flag !== "0")
@@ -40,15 +26,9 @@ export function updateChecksOff(env, dir) {
 export function setUpdateChecks(dir, on) {
     writeAtomic(join(dir, UPDATE_SWITCH_FILE), on ? "on\n" : "off\n");
 }
-/** What the last check found, whenever it ran; null when none has succeeded. Never touches the network. */
 export function cachedRelease(dir) {
     return readCache(dir)?.release ?? null;
 }
-/**
- * The latest published release, checked at most once a day. Returns what the
- * cache knows while it is fresh, asks again once it is a day old, and on any
- * failure keeps what it knew before (null when it knew nothing). Never throws.
- */
 export async function latestRelease(dir, io = {}) {
     const env = io.env ?? process.env;
     if (updateChecksOff(env, dir).off)
@@ -67,24 +47,17 @@ export async function latestRelease(dir, io = {}) {
         }
     }
     catch {
-        // Offline, slow or refused: nothing to say.
     }
-    // The attempt is stamped either way, so a failure does not ask again until tomorrow.
     try {
         writeAtomic(join(dir, RELEASE_CACHE_FILE), `${JSON.stringify({ checkedAt: now.toISOString(), release })}\n`);
     }
     catch {
-        // A read-only folder only means asking again next time.
     }
     return release;
 }
-/** Notes that mention "Security" mark a security release. */
-/** A release marks itself as a security release with a line or heading that starts with "Security" (for example
- * "## Security" or "- **Security fix.**"), not by mentioning the word ("no security changes"). */
 export function isSecurityRelease(notes) {
     return /^\s*(?:#{1,6}\s*|[-*]\s*(?:\*\*)?)?security\b/im.test(notes);
 }
-/** a > b for dotted versions; a pre-release sorts before its release. */
 export function isNewer(a, b) {
     const parse = (value) => {
         const [core = "", pre] = value.replace(/^v/, "").split("-", 2);
@@ -104,20 +77,13 @@ export function isNewer(a, b) {
         return false;
     return left.pre.localeCompare(right.pre, "en", { numeric: true }) > 0;
 }
-/** The release worth mentioning: newer than `current`, else null. */
 export function newerRelease(release, current) {
     return release !== null && isNewer(release.version, current) ? release : null;
 }
-/** The one status line, only when a newer release exists. */
 export function updateLine(release, current, updateCommand) {
     const newer = newerRelease(release, current);
     return newer === null ? null : `${newer.version} is available — ${updateCommand} · ${newer.url}`;
 }
-/**
- * A security release tells each instance operator once per version, through
- * the outbox and addressed to them (like a sign-in pause): only someone at
- * this computer can update it. Returns how many messages were queued.
- */
 export function notifySecurityRelease(store, release, current, updateCommand, now) {
     const newer = newerRelease(release, current);
     if (newer === null || !newer.security)
@@ -147,7 +113,6 @@ export function recordRunnerVersion(dir, runner, version, now) {
         writeAtomic(join(dir, RUNNER_VERSIONS_FILE), `${JSON.stringify(known.sort((a, b) => a.runner.localeCompare(b.runner)))}\n`);
     }
     catch {
-        // The version is a display fact; a failed write only leaves it unknown.
     }
 }
 export function runnerVersions(dir) {
@@ -162,10 +127,6 @@ export function runnerVersions(dir) {
         return [];
     }
 }
-/**
- * The console's background check: at start and then hourly (the daily limit
- * is latestRelease's own), and a security release notifies operators.
- */
 export function startUpdateChecks(store, dir, current, updateCommand, io = {}) {
     let stopped = false;
     const pass = async () => {
@@ -175,7 +136,6 @@ export function startUpdateChecks(store, dir, current, updateCommand, io = {}) {
                 notifySecurityRelease(store, release, current, updateCommand, (io.now ?? (() => new Date()))());
             }
             catch {
-                // A closed store at shutdown: nothing to tell.
             }
         }
     };
@@ -225,8 +185,6 @@ function writeAtomic(file, content) {
     writeFileSync(temporary, content, { mode: 0o600 });
     renameSync(temporary, file);
 }
-/** The latest version, asked of npm now: for an explicit update (the command, Check now), not the once-a-day
- * notice, so neither its cache nor its switch applies. Throws with npm's own reason. */
 export async function latestVersionNow(io = {}) {
     const answer = await (io.fetch ?? fetch)(REGISTRY_URL, { signal: AbortSignal.timeout(10_000), headers: { accept: "application/json" } });
     if (!answer.ok)
@@ -236,8 +194,6 @@ export async function latestVersionNow(io = {}) {
         throw new Error("npm did not name a version");
     return { version };
 }
-/** What a release says about itself in one line ("Release 0.9.9: lighter tests, cleaner status"), when its notes
- * have such a line; null otherwise. */
 export function releaseSummary(notes, version) {
     const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const line = new RegExp(`^\\s*(?:#{1,6}\\s*)?(?:Toolroll\\s+)?(?:Release\\s+)?v?${escaped}\\s*[:—–-]\\s*(.+?)\\s*$`, "im").exec(notes);
@@ -246,11 +202,6 @@ export function releaseSummary(notes, version) {
         return null;
     return summary.length <= 80 ? summary : `${summary.slice(0, 79).replace(/[\s,;:]+\S*$/, "")}…`;
 }
-/**
- * A deploy says one thing in chat: "Toolroll 0.9.9 is live." (with the release's own one-line summary when its
- * notes have one). Once per version, addressed to each instance operator, and only when a worker on this
- * computer last ran an older version: a fresh install is not news. Call before recording this runner's version.
- */
 export function notifyVersionLive(store, dir, version, now) {
     const before = runnerVersions(dir);
     if (!VERSION.test(version) || !before.some(one => isNewer(version, one.version)) || before.some(one => isNewer(one.version, version)))

package/dist/remote-audit.js

@@ -1,21 +1,8 @@
-/**
- * Remote activity (phase 3, docs/plans/remote-team.md): what people did on this server with their API tokens, read
- * from the action history runOperateAs already writes — one `requested` line when a command starts, and a final line
- * (`done`, `refused`, `usage`, `failed`) when it ends or is refused. The history is append-only and sealed, so old
- * words are never rewritten: this projection maps them to `ok`, `refused` and `error` as it reads, and leaves out the
- * `requested` lines. It never shows a line's raw detail; the token's name, an MCP tool and a refusal reason are
- * recovered from it by exact match.
- *
- * Who sees what is decided inside the query, before a page is cut: the machine's owner (a local run) sees everyone;
- * an approver sees everyone within their project ceiling and all of their own lines; a viewer sees only their own.
- * Another person the reader may not see answers exactly like a person who doesn't exist.
- */
 import { IN_RANGE } from "./ledger-chain.js";
 export const AUDIT_SOURCES = ["api", "mcp"];
 export const AUDIT_LIMIT = { default: 20, max: 100 };
 const SINCE_MAX_DAYS = 3650;
 export const OWNER_READER = Object.freeze({ self: null, everyone: true, repos: null, unplaced: true });
-/** The old final words, in the vocabulary people read. Anything unrecognized reads as an error, never as ok. */
 export function auditOutcome(outcome) {
     if (outcome === "requested")
         return null;
@@ -25,7 +12,6 @@ export function auditOutcome(outcome) {
         return "refused";
     return "error";
 }
-/** `7d` → the instant that many days before `now`; null for anything else (no zero, sign, fraction or other unit). */
 export function sinceOf(value, now) {
     const match = /^([1-9][0-9]{0,3})d$/.exec(value);
     if (match === null || Number(match[1]) > SINCE_MAX_DAYS)
@@ -36,11 +22,6 @@ export const cursorOf = (value) => /^[1-9][0-9]{0,15}$/.test(value) && Number.is
 const REASON = /^[a-z][a-z0-9-]{0,40}$/;
 const TOOL = /^[a-z][a-z0-9_]{0,40}$/;
 const COMMAND = "remote command: ";
-/**
- * A line's token, tool and reason. The detail is `token <name>` then ` · `-separated parts: the token name is the
- * longest of this person's token names (or ids, for a line written before the token was proved) that matches up to a
- * separator, since a name may itself contain ` · `. Unmatched text is never echoed.
- */
 export function readDetail(detail, tokens) {
     const none = { token: null, tool: null, reason: null };
     if (detail === null || !detail.startsWith("token "))
@@ -67,10 +48,6 @@ export function readDetail(detail, tokens) {
     }
     return { token, tool, reason };
 }
-/**
- * One page of remote actions, newest first, keyed by entry id so new lines never shift an older page. The reader's
- * visibility and every filter are applied before the page is cut; the token filter is an exact name match.
- */
 export function remoteAudit(store, reader, filters, page = {}) {
     const notFound = { ok: false, reason: "not-found", message: "Not found." };
     const limit = Math.max(1, Math.min(AUDIT_LIMIT.max, Math.trunc(page.limit ?? AUDIT_LIMIT.default)));
@@ -109,7 +86,6 @@ export function remoteAudit(store, reader, filters, page = {}) {
     for (const one of store.apiTokens(null))
         tokens.set(one.account, [...(tokens.get(one.account) ?? []), one]);
     if (filters.token !== null) {
-        // Narrow by every label a line for this name could start with; the exact owner of the line is decided below.
         const labels = [...new Set([...tokens.values()].flat().filter(one => one.name === filters.token).flatMap(one => [one.name, one.id]))];
         if (labels.length === 0)
             return { ok: true, actions: [], nextCursor: null, limit };
@@ -155,7 +131,6 @@ function actionOf(row, tokens) {
         outcome, reason: outcome === "ok" ? null : read.reason ?? (String(row["outcome"]) === "usage" ? "usage" : null),
     };
 }
-/** A token's standing, for People. */
 export function tokenStatus(token, now) {
     return token.revokedAt !== null ? "revoked" : Date.parse(token.expiresAt) <= now.getTime() ? "expired" : "active";
 }

package/dist/remote-command.js

@@ -1,13 +1,5 @@
 import { COMMAND_GUIDE } from './surface.js';
 export const STEP_UP_MESSAGE = 'approve in the console or chat';
-/**
- * Filesystem arguments audited against operate.ts, flows-cli.ts and cli.ts's local dispatchers.
- * Keep this inventory command-specific: --file runs a project executable for scripts, but is a
- * boolean for template apply; --to is a directory for link and a date for ledger export.
- * Project selectors (--repo), scope globs (--touches/--paths) and saved IDs are not input files;
- * their authority belongs to runOperateAs. Local installers' explicit destinations are refused.
- * '*' is reserved for the credentials/database and cli.ts's output redirection, on every command.
- */
 export const REMOTE_PATH_ARGUMENTS = [
     ...['--token', '--token-file', '--token-env', '--db', '-o', '--output'].map(flag => ({ invocation: '*', argument: { flag }, policy: 'refuse' })),
     { invocation: 'flows create', argument: { flag: '--steps' }, policy: 'inline', literal: 'json' },
@@ -15,7 +7,6 @@ export const REMOTE_PATH_ARGUMENTS = [
     { invocation: 'flows script save', argument: { flag: '--body' }, policy: 'inline' },
     { invocation: 'flows script save', argument: { flag: '--file' }, policy: 'refuse' },
     { invocation: 'flows export', argument: { flag: '--out' }, policy: 'refuse' },
-    // Import stats the original path before readInput. Inlining alone cannot prevent that server read.
     { invocation: 'flows import', argument: { position: 0, name: 'file' }, policy: 'refuse', literal: 'url' },
     { invocation: 'flows trigger add', argument: { position: 1, name: 'trigger' }, policy: 'inline', literal: 'json' },
     { invocation: 'task evidence', argument: { flag: '--out' }, policy: 'refuse' },
@@ -35,11 +26,6 @@ export const REMOTE_PATH_ARGUMENTS = [
     ...['repos add', 'repos remove', 'pulls', 'graph', ''].map(invocation => ({ invocation, argument: { position: 0, name: 'path', rest: true }, policy: 'refuse' })),
     { invocation: 'project use', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
 ];
-/**
- * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a
- * file positional. Unknown arity fails closed. File keys and argv stay exactly as typed.
- * All failures describe the argument slot, never a supplied path, credential or other value.
- */
 export function fileArguments(argv, row) {
     const paths = [];
     const rules = REMOTE_PATH_ARGUMENTS.filter(one => one.invocation === '*' || one.invocation === row.invocation);
@@ -57,7 +43,6 @@ export function fileArguments(argv, row) {
             return { problem: `${label} cannot use a server path remotely. Use --local to run it here.`, code: 'server-path' };
         if (value === undefined || value === '')
             return { problem: `${label} needs a file path.`, code: 'missing-file' };
-        // '-' would otherwise read the server's stdin (or a client file literally named '-'). Never prompt.
         if (value === '-')
             return { problem: `${label} needs a file instead of stdin for a remote command.`, code: 'server-path' };
         paths.push(value);
@@ -100,7 +85,6 @@ export function fileArguments(argv, row) {
     }
     return paths;
 }
-/** The longest declared invocation named by the leading words. Missing remote metadata means local only. */
 export const contractRow = argv => {
     const words = [];
     for (const one of argv) {

package/dist/remote-destination.js

@@ -1,16 +1,8 @@
-/**
- * Where a read of a recorded remote really connects, worked out and pinned before git runs (docs/plans/code-map.md §1).
- * remote-main.ts's URL rules look at a host's spelling; a name can still resolve to this machine. Here the name is
- * resolved once, every address is checked, and git is told to use exactly the checked address. Routing is decided from
- * the same environment git gets. Anything that can't be decided or pinned refuses with a reason: there is no fallback to
- * an unpinned read.
- */
 import { lookup as dnsLookup } from "node:dns/promises";
 import { isIP } from "node:net";
 export const lookupAll = async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address);
 const UNDECIDED = "Toolroll can't tell how this connection would be routed";
 const NOT_ALLOWED = "its address isn't one Toolroll connects to";
-/** The eight 16-bit groups of an IPv6 address; null when it isn't one. */
 function hextets(address) {
     let text = address.toLowerCase().replace(/%.*$/, "");
     const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
@@ -36,7 +28,6 @@ const refusedV4 = (address) => {
     return a === 127 || a === 0 || (a === 169 && b === 254);
 };
 const v4Of = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
-/** Whether an address is loopback, unspecified, link-local, or an IPv4-mapped or NAT64 form of these. */
 export function addressRefused(address) {
     const family = isIP(address);
     if (family === 4)
@@ -48,19 +39,17 @@ export function addressRefused(address) {
         return true;
     const top = g.slice(0, 5).every(one => one === 0);
     if (top && g[5] === 0 && g[6] === 0 && (g[7] === 0 || g[7] === 1))
-        return true; // :: and ::1
+        return true;
     if ((g[0] & 0xffc0) === 0xfe80)
-        return true; // fe80::/10
+        return true;
     if (top && g[5] === 0xffff)
-        return refusedV4(v4Of(g[6], g[7])); // ::ffff:a.b.c.d
+        return refusedV4(v4Of(g[6], g[7]));
     if (top && g[5] === 0)
-        return refusedV4(v4Of(g[6], g[7])); // ::a.b.c.d (deprecated compatible form)
+        return refusedV4(v4Of(g[6], g[7]));
     if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every(one => one === 0))
-        return refusedV4(v4Of(g[6], g[7])); // 64:ff9b::/96
+        return refusedV4(v4Of(g[6], g[7]));
     return false;
 }
-/** The host, effective port and scheme a recorded URL connects to; null when it can't be read. The caller has already
- * passed remoteUrlProblem. Node's URL parser normalizes every spelling of a literal host. */
 export function destinationOf(url) {
     const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url)?.[1]?.toLowerCase();
     let host, port;
@@ -104,13 +93,11 @@ async function checkedAddress(host, literal, lookup) {
     }
     if (found.length === 0)
         return { ok: false, why: "its host name couldn't be resolved" };
-    // Every address, not just the first: a name that also answers with this machine isn't connected to.
     if (found.some(addressRefused))
         return { ok: false, why: NOT_ALLOWED };
     return { ok: true, address: found[0] };
 }
 const curlPin = (host, port, address) => ["-c", `http.curloptResolve=${host}:${port}:${isIP(address) === 6 ? `[${address}]` : address}`];
-/** One NO_PROXY entry against a host, as curl compares them; "unknown" for anything Toolroll won't second-guess. */
 function noProxyMatch(entry, host) {
     const raw = entry.replace(/^\[(.*)\]$/, "$1");
     if (raw === "*")
@@ -144,7 +131,6 @@ function noProxyMatch(entry, host) {
     const wanted = host.replace(/\.+$/, "").toLowerCase();
     return name !== "" && (wanted === name || wanted.endsWith(`.${name}`));
 }
-/** Whether curl would skip the proxy for this host; "unknown" when an entry can't be decided. */
 export function noProxyApplies(noProxy, host) {
     let unknown = false;
     for (const entry of noProxy.split(/[,\s]+/).filter(Boolean)) {
@@ -160,8 +146,6 @@ const envOf = (env, lower, upper) => {
     const low = env[lower];
     return low !== undefined && low !== "" ? low : env[upper] ?? "";
 };
-/** The proxy curl would use from `https_proxy`/`HTTPS_PROXY`: http or https schemes only (a SOCKS proxy resolves names
- * on its side, in ways this can't see). */
 function proxyOf(value) {
     const text = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value) ? value : `http://${value}`;
     let parsed;
@@ -180,11 +164,6 @@ function proxyOf(value) {
         return null;
     return { host, port, literal };
 }
-/**
- * Decide the route and pin it. `env` is what git will see (the names remote-main.ts's ENV_ALLOWLIST passes). ssh never
- * uses a proxy. Through a proxy, the proxy's own address is checked and pinned; the operator's proxy then chooses the
- * final destination, and the caller says so.
- */
 export async function pinDestination(url, env, lookup = lookupAll) {
     const target = destinationOf(url);
     if (target === null)

package/dist/remote-exec.js

@@ -1,12 +1,3 @@
-/**
- * Remote CLI, the client half (Phase 1). With an API token saved by `toolroll connect`, a command whose contract row
- * says `remote: "yes"` is sent to the central server's `POST /api/cli` and runs there as you; its stdout, stderr and
- * exit code come back byte for byte. `remote: "no"` runs on this computer exactly as before, and `remote: "step-up"`
- * (approvals, people and policy) is refused here: those stay in the console or chat.
- *
- * Nothing here opens the local database or reads a saved owner login; it never prompts, and an uncertain answer to
- * a mutation is never retried.
- */
 import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -18,8 +9,6 @@ import { TOKEN_REPLACEMENT } from './password-bearer.js';
 import { contractRow, fileArguments, STEP_UP_MESSAGE } from './remote-command.js';
 export { contractRow, STEP_UP_MESSAGE } from './remote-command.js';
 const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
-/** Never sent remotely: `connect` saves the profile itself, the lead's commands are this computer's, and the removed
- * central team and session verbs answer with their removal notice (removed-commands.ts). */
 const TEAM_COMMANDS = new Set(['connect', 'lead', 'conversation', 'chat', 'brief', 'session']);
 const RESPONSE_BYTES = 16 * 1024 * 1024;
 const REQUEST_TIMEOUT_MS = (CLI_WAIT_SECONDS + 35) * 1_000;
@@ -46,7 +35,6 @@ async function bounded(response) {
     }
     return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
 }
-/** One request, never retried. */
 export async function postCli(origin, token, request, options) {
     try {
         const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
@@ -73,7 +61,6 @@ export async function postCli(origin, token, request, options) {
         return { kind: 'unconfirmed' };
     }
 }
-/** The declared file arguments' contents, keyed by the argument exactly as typed. argv is never rewritten. */
 function inlineFiles(argv, row, cwd) {
     const paths = fileArguments(argv, row);
     if ('problem' in paths)
@@ -107,10 +94,6 @@ function inlineFiles(argv, row, cwd) {
     }
     return files;
 }
-/**
- * null: run locally with argv unchanged. `{ local }`: run locally with this argv (`--local` removed).
- * A number: the command ran remotely (or was refused before sending) and this is its exit code.
- */
 export async function maybeRunRemoteCommand(argv, options = {}) {
     const first = argv[0];
     if (first === undefined || first.startsWith('-') || TEAM_COMMANDS.has(first) || first === 'help')
@@ -131,13 +114,11 @@ export async function maybeRunRemoteCommand(argv, options = {}) {
     const profileAt = argv.indexOf('--profile');
     const mode = row?.mode ?? 'no';
     const explicit = profileAt >= 0;
-    // Local commands never read the profile, and their own flags (the scan's --local) stay exactly as typed.
     if (mode === 'no' && !explicit)
         return null;
     if (argv.includes('--local')) {
         if (explicit)
             return refuse('usage', '--local cannot be combined with --profile.', EXIT.usage);
-        // A row declaring --local keeps its own meaning; elsewhere it only means "run here".
         const declared = COMMAND_GUIDE.find(one => one.invocation === row?.invocation)?.flags?.some(flag => flag.name === 'local') ?? false;
         return { local: declared ? [...argv] : argv.filter(one => one !== '--local') };
     }
@@ -150,7 +131,6 @@ export async function maybeRunRemoteCommand(argv, options = {}) {
     catch (error) {
         return refuse('usage', error instanceof UsageError ? error.message : 'The remote profile cannot be read.', EXIT.usage);
     }
-    // No saved token: today's local behaviour. A profile saved with a password serves chat only.
     if (profile === null || !profile.apiToken) {
         if (!explicit)
             return null;
@@ -171,14 +151,13 @@ export async function maybeRunRemoteCommand(argv, options = {}) {
     }
     const deliver = (outcome) => {
         if (outcome.kind === 'answer') {
-            // Byte for byte. --json answers are also captured so -o writes the same envelope a local run would.
             if (json) {
                 try {
                     const parsed = JSON.parse(outcome.answer.stdout);
                     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
                         envelopeJson(parsed);
                 }
-                catch { /* not one envelope */ }
+                catch { }
             }
             if (outcome.answer.stdout)
                 out(outcome.answer.stdout);
@@ -196,10 +175,6 @@ export async function maybeRunRemoteCommand(argv, options = {}) {
         return waitRemotely(sent, files, profile, options, deliver);
     return deliver(await postCli(profile.origin, profile.token, { argv: sent, files }, options));
 }
-/**
- * `task wait` holds the server for at most CLI_WAIT_SECONDS per request; the client keeps asking within the caller's
- * own --timeout (none: until the task settles or the wait is interrupted). The final answer is the server's own.
- */
 async function waitRemotely(argv, files, profile, options, deliver) {
     const at = argv.indexOf('--timeout');
     const given = at < 0 ? null : Number(argv[at + 1]);
@@ -228,7 +203,6 @@ async function waitRemotely(argv, files, profile, options, deliver) {
         if (!timedOut || slice <= 0 || given !== null && remaining - slice <= 0) {
             if (json)
                 return deliver(outcome);
-            // Settled (or out of time): the server renders the final answer in the person's own format.
             return deliver(await postCli(profile.origin, profile.token, { argv: [...base, '--timeout', '0'], files }, options));
         }
         if (signal.aborted)

package/dist/remote-main.js

@@ -1,49 +1,21 @@
-/**
- * The project's main as its recorded remote has it, read by Toolroll's own process. Automatic completion of landed
- * work (landed-cleanup.ts) trusts only this: a build shares the project's .git, so it can move the local main or
- * repoint origin in .git/config, and neither may complete its own task.
- *
- * The remote URL is the one captured on first admission or explicitly supplied by the owner (project-admission.ts), never the repository's
- * config. Each read fetches that URL's main into a fresh, private Git directory under Toolroll's evidence folder (which
- * the agent fence denies to builds), with no system or global config, no includes or URL rewriting, no replace
- * objects, no hooks, no ext or file transport and only an explicit credential helper. The shared repository's objects, refs,
- * replace refs, grafts and shallow state are never read: commits enter only by fetch. A content comparison brings the
- * result's exact recorded commit in by fetch too; git checks every object against its hash.
- *
- * Every doubt fails closed: no recorded remote, a URL that isn't allowed, a failed fetch or a remote without main all
- * read as "not proven", and the task stays for a person.
- */
 import { lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { run } from "./exec.js";
-/** The ref a fetched remote main is kept under, inside the private directory only. */
 const REMOTE_MAIN = "refs/toolroll/remote-main";
 const SHA = /^[0-9a-f]{40}$/;
 const FETCH_TIMEOUT_MS = 120_000;
-/** What the private directory's git may see of this process's environment: nothing that names a repository, an
- * object store or config. The fixed settings below go on top. Teardown git (teardown-git.ts) uses the same. */
 export const ENV_ALLOWLIST = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SSH_AUTH_SOCK", "HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy"];
 export const ENV = {
     GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_NO_REPLACE_OBJECTS: "1", GIT_TERMINAL_PROMPT: "0",
     GIT_ASKPASS: "", SSH_ASKPASS: "", GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
 };
-/** The only credential helper https may use: the system keychain on macOS; elsewhere none, so a private https remote
- * fails closed instead of asking. */
 export const CREDENTIAL_HELPER = process.platform === "darwin" ? "osxkeychain" : "";
-/** Settings for every command in the private directory. The directory's own config is ours and empty. File transport
- * is off for the recorded remote; only the result fetch from the registered project path turns it on. */
 function hardened(helper, file = "never") {
     return ["-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always",
         "-c", `protocol.file.allow=${file}`, "-c", "protocol.ext.allow=never", "-c", "credential.helper=", ...(helper === "" ? [] : ["-c", `credential.helper=${helper}`]),
         "-c", "gc.auto=0", "-c", "maintenance.auto=false", "-c", "fetch.recurseSubmodules=false", "-c", "core.fsmonitor=false",
-        // Never to an address the recorded URL doesn't name: a moved repository is a person's choice to record (MOVED).
         "-c", "http.followRedirects=false"];
 }
-/**
- * A URL Toolroll may fetch remote main from: https or ssh (either form). Local paths, file URLs and loopback hosts
- * (this machine is where builds run) are always refused. Remote helpers (ext::, fd:: and the like), plain http and
- * git:// (no authentication), relative paths, embedded passwords and anything odd are refused.
- */
 export function parseRemoteUrl(url) {
     const refused = { why: "its remote URL isn't one Toolroll fetches from" };
     if (url === "" || url.length > 2048 || /[\x00-\x20\x7f]/.test(url) || url.startsWith("-") || url.includes("\\"))
@@ -64,15 +36,12 @@ export function parseRemoteUrl(url) {
         }
         return { kind: "network", url };
     }
-    // scp-like ssh: [user@]host:path, with no slash before the first colon.
     const colon = url.indexOf(":");
     const host = /^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9.-]+)$/.exec(url.slice(0, colon))?.[1];
     if (colon > 0 && colon < url.length - 1 && host !== undefined && !loopback(host))
         return { kind: "network", url };
     return refused;
 }
-/** localhost (and its subdomains), any IPv4 spelling of 127.0.0.0/8 or 0.0.0.0 (inet_aton accepts 127.1, 0x7f.1 and
- * the like), and ::1, :: or an IPv4-mapped loopback. */
 function loopback(hostname) {
     const host = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.+$/, "");
     if (host === "localhost" || host.endsWith(".localhost"))
@@ -93,24 +62,15 @@ function loopback(hostname) {
         return true;
     }
 }
-/** Why a recorded URL may not be used as the trusted remote; null when it may. */
 export function remoteUrlProblem(url) {
     const parsed = parseRemoteUrl(url);
     return "why" in parsed ? parsed.why : null;
 }
-/** What every reader of a remote main shows when its address redirects. The target is remote-supplied text: it is never
- * shown, stored or followed, and the new remote is never adopted automatically. */
 export const REMOTE_MOVED = "The repository moved: its address now redirects. Update the project's remote in Toolroll (Settings → Projects), then try again.";
-/** git's words for a refused redirect (http.followRedirects=false), read for the status code alone. */
 export function redirected(stderr) {
     return /returned error: 30[12378]\b/.test(stderr);
 }
 const UNREAD = "Toolroll couldn't read the project's remote main";
-/**
- * One pass's reads of recorded remotes. Every `read` fetches again (the pre-teardown re-check is never older than
- * the teardown); a project's private directory lasts until `close`, so a fetch after the first only brings what
- * changed. Close removes every directory.
- */
 export class RemoteMains {
     store;
     runner;
@@ -126,8 +86,6 @@ export class RemoteMains {
     exec(dir, args, file = "never") {
         return this.runner("git", ["--git-dir", dir, ...hardened(this.helper, file), ...args], { cwd: dir, envAllowlist: ENV_ALLOWLIST, env: ENV, timeoutMs: FETCH_TIMEOUT_MS, maxBuffer: 512 * 1024 * 1024 });
     }
-    /** Nothing but fetched objects decides: a private directory that grew alternates, grafts or shallow state is
-     * not trusted. */
     clean(dir) {
         return !["shallow", join("info", "grafts"), join("objects", "info", "alternates"), join("objects", "info", "http-alternates")].some(name => existsSync(join(dir, name)));
     }
@@ -171,7 +129,6 @@ export class RemoteMains {
                 return false;
             if ((await git(["cat-file", "-e", `${head}^{commit}`])).code === 0)
                 return true;
-            // The one local fetch: from the project path Toolroll registered (never a URL), for this exact hash-checked commit.
             if (!isAbsolute(from))
                 return false;
             const got = await this.exec(dir, ["fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--", from, `+${head}:refs/toolroll/results/${head}`], "always");
@@ -184,21 +141,17 @@ export class RemoteMains {
             try {
                 rmSync(dir, { recursive: true, force: true });
             }
-            catch { /* the next pass makes its own */ }
+            catch { }
         }
         this.dirs.clear();
     }
 }
-// ---- the code map's own read: pinned, depth 1, bounded (docs/plans/code-map.md §1) ---------------------------------
 const MAP_MAIN = "refs/toolroll/map-main";
-/** What keeps git's own memory down. index-pack still materializes delta bases, so these reduce; they don't bound. */
 const LOW_MEMORY = ["-c", "pack.threads=1", "-c", "core.deltaBaseCacheLimit=32m", "-c", "core.bigFileThreshold=1m"];
 export const MAP_FETCH_LIMITS = { timeoutMs: 120_000, memoryBytes: 1024 ** 3, diskBytes: 1024 ** 3, fileBytes: 512 * 1024 ** 2, maxStderr: 64 * 1024 };
-/** Git in a private directory under the map's rules: the same hardening as `RemoteMains`, plus the pin. */
 export function mapGitArgs(dir, pin, args, options = {}) {
     return ["--git-dir", dir, ...hardened(options.helper ?? CREDENTIAL_HELPER), ...pin.gitArgs, ...(options.extra ?? []), ...args];
 }
-/** The environment for it: exactly the allowed names, the fixed settings, and the pin's. */
 export function mapGitEnv(pin, from = process.env) {
     const env = {};
     for (const name of ENV_ALLOWLIST) {
@@ -211,7 +164,6 @@ export function mapGitEnv(pin, from = process.env) {
 export function initPrivateDir(dir, bounded) {
     return bounded("git", ["init", "--quiet", "--bare", "--template=", dir], { cwd: dir, env: mapGitEnv({ gitArgs: [], env: {}, proxy: null }), timeoutMs: 30_000, maxStdout: 4096, maxStderr: 4096, label: "code-map-init" });
 }
-/** The commit the recorded remote's main is at, without fetching: null when the remote has no `main`. */
 export async function peekMain(url, dir, pin, bounded, helper) {
     const ran = await bounded("git", mapGitArgs(dir, pin, ["ls-remote", "--", url, "refs/heads/main"], helper === undefined ? {} : { helper }), { cwd: dir, env: mapGitEnv(pin), timeoutMs: 30_000, maxStdout: 64 * 1024, maxStderr: MAP_FETCH_LIMITS.maxStderr, label: "code-map-peek" });
     if (ran.code !== 0 && redirected(ran.stderr))
@@ -224,8 +176,6 @@ export async function peekMain(url, dir, pin, bounded, helper) {
     const commit = line.slice(0, line.indexOf("\t"));
     return SHA.test(commit) ? { ok: true, commit } : { ok: false, why: UNREAD };
 }
-/** A depth-1 private folder is clean when it holds only what the fetch made: a `shallow` file naming exactly the fetched
- * commit, and no grafts or alternates. */
 export function shallowClean(dir, commit) {
     if ([join("info", "grafts"), join("objects", "info", "alternates"), join("objects", "info", "http-alternates")].some(name => existsSync(join(dir, name))))
         return false;
@@ -236,11 +186,9 @@ export function shallowClean(dir, commit) {
         return readFileSync(join(dir, "shallow"), "utf8").trim() === commit;
     }
     catch (error) {
-        // A history of one commit needs no shallow boundary, and git writes none.
         return error.code === "ENOENT";
     }
 }
-/** Fetch main at depth 1 into `dir`, under the map's limits. `onStart` records the spawn for crash cleanup. */
 export async function readShallowMain(url, dir, pin, bounded, onStart, helper) {
     const fetched = await bounded("git", mapGitArgs(dir, pin, ["fetch", "--quiet", "--depth=1", "--no-tags", "--no-write-fetch-head", "--", url, `+refs/heads/main:${MAP_MAIN}`], { extra: LOW_MEMORY, ...(helper === undefined ? {} : { helper }) }), { cwd: dir, env: mapGitEnv(pin), timeoutMs: MAP_FETCH_LIMITS.timeoutMs, maxStdout: 4096, maxStderr: MAP_FETCH_LIMITS.maxStderr, memoryBytes: MAP_FETCH_LIMITS.memoryBytes,
         diskBytes: MAP_FETCH_LIMITS.diskBytes, fileBytes: MAP_FETCH_LIMITS.fileBytes, folder: dir, label: "code-map-fetch", ...(onStart === undefined ? {} : { onStart }) });

package/dist/remote-run.js

@@ -1,10 +1,5 @@
-/**
- * The remote run this code is inside (runOperateAs in operate.ts), if any. A leaf module so the credential
- * checks every command reaches (scope.ts) can honour it without importing the command table.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 const running = new AsyncLocalStorage();
-/** The remote run this code is inside, or null for every local command. */
 export function activeRemote() {
     return running.getStore() ?? null;
 }