toolroll 0.9.103 → 0.9.105

package/dist/doctor.js

@@ -1,20 +1,3 @@
-/**
- * `toolroll doctor`: whether Toolroll's own service holds a credential a build could read.
- *
- * A build runs as the operator's own user. Where no OS fence stops it (any build on Linux, where hidepid hides nothing
- * from the same user; a Codex build anywhere, whose profile can't deny KERN_PROCARGS2; a Claude build without the
- * macOS sandbox) it can read another process's launch arguments and environment: KERN_PROCARGS2 on macOS,
- * /proc/<pid>/environ on Linux. Toolroll's own service is such a process, so its environment must hold no key:
- * provider keys belong in Toolroll's key file (`toolroll keys set`), a tool's secrets on its Tools page, the runner
- * token in its 0600 file.
- *
- * The doctor only reads: each installed service definition (a launchd plist; a systemd unit, its drop-ins and
- * environment files), what `daemon install` would write, the environment a service inherits from its manager
- * (`launchctl getenv`, `systemctl --user show-environment`), and the environment of each running service process.
- * It reports names and where they are, never a value, with the exact steps for the owner. It never edits a unit,
- * moves a key into a file or restarts anything. A key exported in the terminal that starts `toolroll up` keeps
- * working (the ambient fallback); the doctor names it so the owner can choose.
- */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -26,16 +9,10 @@ import { run as runCommand } from "./exec.js";
 import { OWN_KEY_ENV } from "./keys.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 import { SANDBOX_RUNTIME, sandboxRuntimeProblem, sandboxRuntimeWords } from "./sandbox-runtime.js";
-/** Names that say they hold a credential. */
 const CREDENTIAL_NAME = /(?:^|_)(?:API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|SECRET|SECRET_?KEY|TOKEN|AUTH_?TOKEN|PASSWORD|PASSWD|CREDENTIALS?|PAT)(?:_|$)/i;
-/** Names that only point at one: a path, a socket, an address. */
 const POINTER_NAME = /(?:_FILE|_PATH|_DIR|_SOCK|_URL|_HOST)$/i;
-/** Launch flags whose next argument (or `=value`) is a credential. */
 const CREDENTIAL_FLAG = /^--?(?:token|api-?key|key|secret|password|auth-token)$/i;
-/** Toolroll's own launchd labels, current and from before the rename. */
 const LABEL = /^(?:com\.toolroll|com\.standing-orders)\.[A-Za-z0-9._-]+$/;
-/** The names among `pairs` that hold a credential: a provider key, a credential-looking name, or a key-shaped value.
- * Values are only tested here and never leave. */
 export function credentialNames(pairs) {
     const found = new Set();
     for (const [name, value] of pairs) {
@@ -46,7 +23,6 @@ export function credentialNames(pairs) {
     }
     return [...found].sort();
 }
-/** The flags of a launch command that carry a credential inline (`--token <value>`), and arguments that look like a key. */
 function commandCredentials(args) {
     const found = new Set();
     args.forEach((arg, index) => {
@@ -59,14 +35,12 @@ function commandCredentials(args) {
     return [...found].sort();
 }
 const unxml = (text) => text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
-/** A plist's EnvironmentVariables and ProgramArguments. */
 function plistParts(content) {
     const dict = /<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/.exec(content)?.[1] ?? "";
     const env = [...dict.matchAll(/<key>([^<]*)<\/key>\s*<string>([^<]*)<\/string>/g)].map(match => [unxml(match[1] ?? ""), unxml(match[2] ?? "")]);
     const args = [...(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(content)?.[1] ?? "").matchAll(/<string>([^<]*)<\/string>/g)].map(match => unxml(match[1] ?? ""));
     return { env, args };
 }
-/** A systemd line's words, its "quotes" undone. */
 function systemdWords(line) {
     return (line.match(/"(?:[^"\\]|\\.)*"|'[^']*'|\S+/g) ?? []).map(word => word.startsWith('"') ? word.slice(1, -1).replace(/\\(.)/g, "$1") : word.startsWith("'") ? word.slice(1, -1) : word);
 }
@@ -74,12 +48,10 @@ const assignment = (word) => {
     const at = word.indexOf("=");
     return at <= 0 ? null : [word.slice(0, at), word.slice(at + 1)];
 };
-/** `NAME=value` lines (an EnvironmentFile, `show-environment`), comments and blanks skipped. */
 function envLines(text) {
     return text.split("\n").map(line => line.trim()).filter(line => line !== "" && !line.startsWith("#") && !line.startsWith(";"))
         .flatMap(line => { const pair = assignment(line.replace(/^export\s+/, "")); return pair === null ? [] : [[pair[0], pair[1].replace(/^(["'])(.*)\1$/, "$2")]]; });
 }
-/** A systemd unit's (or drop-in's) Environment= assignments, ExecStart words and EnvironmentFile= paths. */
 function systemdParts(content) {
     const env = [];
     const files = [];
@@ -103,8 +75,6 @@ function systemdParts(content) {
     }
     return { env, args, files };
 }
-/** Only understood options may enter remediation. Free-form values are never reflected, even when they
- * look like paths or runner names: any one could actually contain a credential. */
 function reinstallCommand(args) {
     const at = args.indexOf("watch");
     if (at < 0)
@@ -124,7 +94,6 @@ function reinstallCommand(args) {
         const flag = equal < 0 ? arg : arg.slice(0, equal);
         const value = equal < 0 ? args[index + 1] : arg.slice(equal + 1);
         const known = freeform.has(flag) || numeric.has(flag) || Object.hasOwn(enums, flag);
-        // A credential's value is the next argument even when it starts with "-" (random base64url can).
         if (equal < 0 && value !== undefined && (CREDENTIAL_FLAG.test(flag) || (known && !value.startsWith("-"))))
             index += 1;
         if (flag === "--token") {
@@ -151,9 +120,7 @@ function reinstallSteps(command) {
         "Save provider keys with `toolroll keys set` and project tool secrets on the project's Tools page before reinstalling. Review the completed command, then run it yourself; nothing has been changed.",
     ];
 }
-/** One shell word, quoted when it needs to be. */
 const quote = (part) => /^[A-Za-z0-9@%+=:,./_-]+$/.test(part) ? part : `'${part.replace(/'/g, "'\\''")}'`;
-/** Where a provider key goes instead, per provider, or the general home for any other secret. */
 function keySteps(names) {
     const providers = [...new Set(names.flatMap(name => Object.entries(OWN_KEY_ENV).filter(([, env]) => env.includes(name)).map(([provider]) => provider)))].sort();
     return [
@@ -162,7 +129,6 @@ function keySteps(names) {
             ? ["Set a project tool's secret on that project's Tools page; anything else the service doesn't need can simply go."] : []),
     ];
 }
-/** Toolroll's installed service definitions on this computer, current and older names alike. */
 function installedServices(platform, home) {
     const dir = platform === "darwin" ? join(home, "Library", "LaunchAgents") : join(home, ".config", "systemd", "user");
     const suffix = platform === "darwin" ? ".plist" : ".service";
@@ -176,8 +142,6 @@ function installedServices(platform, home) {
     return names.filter(name => name.endsWith(suffix) && LABEL.test(name.slice(0, -suffix.length))).sort()
         .flatMap(name => { const one = installedServiceDefinition({ label: name.slice(0, -suffix.length), platform, home }); return one === null ? [] : [one]; });
 }
-/** A running process's environment names (never values) that hold a credential: macOS through `ps -E`, which reads
- * KERN_PROCARGS2; Linux from /proc/<pid>/environ. */
 export async function processCredentialNames(pid, deps) {
     if (deps.platform === "linux") {
         try {
@@ -202,10 +166,6 @@ export async function processCredentialNames(pid, deps) {
         const tail = whole.slice(command.length).trimStart();
         if (tail === "")
             return { ok: true, names: [] };
-        // ps separates entries with spaces and doesn't quote, so a value with spaces can look like more entries. Read it
-        // names-only: every NAME= at the start or after a space is a candidate (a few may be text inside a value, which
-        // only ever adds a name to report), each candidate's value runs to the next one, and the whole tail is also scanned
-        // for key-shaped text so a secret inside a value is never missed. Fail closed only when nothing parses.
         if (!/^[A-Za-z_][A-Za-z0-9_]*=/.test(tail)) {
             return { ok: false, problem: "ps returned an environment Toolroll couldn't parse" };
         }
@@ -218,7 +178,6 @@ export async function processCredentialNames(pid, deps) {
     }
     return { ok: false, problem: `Toolroll can't read a process's environment on ${deps.platform}` };
 }
-/** Audit what Toolroll's service holds. Reads only; the report names variables, never their values. */
 export async function auditServiceEnvironment(deps = {}) {
     const platform = deps.platform ?? process.platform;
     const home = deps.home ?? homedir();
@@ -227,8 +186,6 @@ export async function auditServiceEnvironment(deps = {}) {
     const report = { ok: true, checked: [], findings: [], unreadable: [], notes: [] };
     const find = (where, names, steps) => { if (names.length > 0)
         report.findings.push({ where, names, steps }); };
-    // The ambient fallback: a key in this terminal keeps working for a Toolroll started here, and the owner should know
-    // that Toolroll would then hold it.
     const ambient = credentialNames(Object.entries(deps.env ?? process.env).filter((pair) => ALL_CREDENTIAL_ENV.includes(pair[0]) && typeof pair[1] === "string"));
     if (ambient.length > 0) {
         report.notes.push(`This terminal exports ${ambient.join(", ")}. A Toolroll started from here still uses it when no key is saved, and holds it where a build without the macOS sandbox could read it. ${keySteps(ambient).join(" ")} Then remove the export from your shell profile.`);
@@ -239,7 +196,6 @@ export async function auditServiceEnvironment(deps = {}) {
         report.ok = false;
         return report;
     }
-    // What `daemon install` writes: planned exactly as install plans it, from this process's own environment.
     const planned = planDaemon({ platform, bin: process.execPath, binArgs: [], runner: "runner", repo: home, configDir: join(home, ".toolroll"), watchFlags: [], home });
     if (!("error" in planned)) {
         const parts = platform === "darwin" ? plistParts(planned.unitContent) : systemdParts(planned.unitContent);
@@ -248,12 +204,10 @@ export async function auditServiceEnvironment(deps = {}) {
     }
     const services = installedServices(platform, home);
     report.checked.push(services.length === 0 ? "No Toolroll service is installed." : `Installed services: ${services.map(one => one.label).join(", ")}.`);
-    // The environment every service of this login inherits from its manager.
     if (platform === "darwin") {
         const inherited = [];
         let failed = null;
         for (const name of ALL_CREDENTIAL_ENV) {
-            // An unset name answers exit 0 and nothing; any other exit is a read that didn't happen.
             const answer = await run("launchctl", ["getenv", name]);
             if (answer.code !== 0)
                 failed ??= answer.code;
@@ -385,7 +339,6 @@ export async function auditServiceEnvironment(deps = {}) {
     report.ok = report.findings.length === 0 && report.unreadable.length === 0;
     return report;
 }
-/** The report as the owner reads it: one state, then each finding with its steps; detail after. */
 export function doctorLines(report) {
     const lines = [];
     if (report.git?.problem != null)
@@ -426,7 +379,6 @@ export async function runDoctorCommand(argv, write, deps = {}) {
     }
     const report = await auditServiceEnvironment(deps);
     report.sandbox = { engine: SANDBOX_RUNTIME.name, version: SANDBOX_RUNTIME.version, problem: sandboxRuntimeProblem() };
-    // A git older than the floor: named here too, and the console and worker won't start on it.
     report.git = { floor: GIT_FLOOR_WORDS, problem: deps.gitFloorProblem === undefined ? installedGitFloorProblem() : deps.gitFloorProblem };
     if (report.git.problem !== null)
         report.ok = false;

package/dist/easy-start-args.js

@@ -1,24 +1,24 @@
-/** Which invocations are an easy start (easy-start.ts), kept apart so the CLI's entry decides without loading it. */
-/** The flags bare `toolroll` takes at a terminal (--web, --project-root <dir>), or null: not an easy start. */
 export function easyStartArgs(argv) {
-    let web = false, projectRoot = null;
+    let web = false, projectRoot = null, port = null;
     for (let index = 0; index < argv.length; index += 1) {
         const one = argv[index];
         if (one === "--web" && !web)
             web = true;
-        else if (one === "--project-root" && projectRoot === null) {
+        else if ((one === "--project-root" && projectRoot === null) || (one === "--port" && port === null)) {
             const value = argv[index + 1];
             if (value === undefined || value === "" || value.startsWith("-"))
                 return null;
-            projectRoot = value;
+            if (one === "--port")
+                port = value;
+            else
+                projectRoot = value;
             index += 1;
         }
         else
             return null;
     }
-    return { web, projectRoot };
+    return { web, projectRoot, port };
 }
-/** Whether this invocation is an easy start: only those flags, a person at a terminal, no coding agent. */
 export function easyStartApplies(argv, facts) {
     return facts.stdin && facts.stdout && !facts.agent && easyStartArgs(argv) !== null;
 }

package/dist/easy-start.js

@@ -1,45 +1,31 @@
-/**
- * EASY START (easy-start plan A, D, E): bare `toolroll` at a terminal, and `toolroll open`.
- *
- * At a person's terminal (stdin and stdout a TTY, no --json, not under a coding agent), bare `toolroll` makes sure this
- * computer's Toolroll is running and opens the terminal UI on it:
- *
- * - The console is proved live first (console-instance.ts, both channels). When it isn't running: the background
- *   service, if installed, is started through its supervisor; otherwise `up --laptop` starts as an ORDINARY child of
- *   this process, so quitting the screen ends it through `up`'s own parent-death drain (today's foreground semantics).
- * - With local mode on, the terminal UI opens in this process as the local owner (runAsLocalOwner): reads in-process,
- *   writes through `runOperate`, refused wherever the local owner is. `--web` opens the browser instead, signed in
- *   through the console's socket `link` verb (or, with nothing running, runs `up --laptop` in the foreground, which
- *   opens it).
- * - With local mode off (an install with passwords), nothing in the terminal writes: today's flow opens the browser,
- *   where the person signs in with their password.
- *
- * Every outside effect is a seam; `defaultEasyStartSeams` gives the real ones. Under an agent, without a terminal or
- * with --json, cli.ts never comes here: those keep exactly the behaviour they had (quick-start.ts and the scan).
- */
 import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { requestLocalLink } from "./console-instance.js";
 import { backgroundInstalled, backgroundOn, startInstalledService } from "./laptop-background.js";
 import { proveConsoleReadOnly } from "./quick-start.js";
-import { backgroundAsked, localModeOf, openStore, openStoreReadOnly, recordBackgroundAsked } from "./store.js";
+import { backgroundAsked, localModeCandidate, localModeOf, openStore, openStoreReadOnly, recordBackgroundAsked } from "./store.js";
+import { underAgent } from "./prompt.js";
 export { easyStartApplies, easyStartArgs } from "./easy-start-args.js";
-const EXIT = { ok: 0, failed: 1, refused: 3 };
-/**
- * Bare `toolroll` ("start") or `toolroll open` ("open") at a person's terminal. Resolves with the exit code once the
- * screen (or the foreground `up`, or the browser hand-off) is done.
- */
+const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
 export async function runEasyStart(mode, args, seams) {
     const { write } = seams;
-    const rootArgs = args.projectRoot === null ? [] : ["--project-root", args.projectRoot];
+    const port = args.port === undefined || args.port === null ? null : Number(args.port);
+    if (port !== null && (!/^[0-9]{1,5}$/.test(args.port) || port < 1 || port > 65_535)) {
+        write("--port is a whole number from 1 to 65535.");
+        return EXIT.usage;
+    }
+    const rootArgs = [...(args.projectRoot === null ? [] : ["--project-root", args.projectRoot]), ...(port === null ? [] : ["--port", String(port)])];
+    const elsewhere = (proof) => {
+        if (port !== null && proof.ok && proof.port !== port)
+            write(`Toolroll is already set up on port ${proof.port}, so it opens there.`);
+    };
     const sleep = seams.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
     const first = await seams.prove();
     if (!first.ok && first.state === "refused") {
         write(`Toolroll can't open: ${first.message}.`);
         return EXIT.refused;
     }
-    // Attaching to a console already running: this folder's repository joins it, as bare `toolroll` always did.
     const joinRepo = async () => {
         if (mode !== "start")
             return EXIT.ok;
@@ -50,26 +36,29 @@ export async function runEasyStart(mode, args, seams) {
         try {
             repo = realpathSync(found);
         }
-        catch { /* as found */ }
+        catch { }
         return (await seams.enrolled(repo)) ? EXIT.ok : seams.admit(repo);
     };
-    // An install with passwords: today's flow, in the browser, where the person signs in. Nothing here writes.
-    if (seams.localMode() === "off") {
+    let local = seams.localMode();
+    if ((local === "candidate" || local === "absent") && !first.ok && first.state === "none" && await seams.initLocal())
+        local = "on";
+    if (local === "candidate")
+        local = "off";
+    if (local === "off") {
         if (!first.ok)
             return seams.runUpForeground(rootArgs);
         const joined = await joinRepo();
         if (joined !== EXIT.ok)
             return joined;
+        elsewhere(first);
         write(`Toolroll is on ${first.url}`);
         await seams.openBrowser(first.url);
         return EXIT.ok;
     }
-    // --web with nothing running and no service: `up --laptop` in this terminal opens the browser itself, signed in.
     if (args.web && !first.ok && !seams.serviceInstalled())
         return seams.runUpForeground(["--laptop", ...rootArgs]);
     let owned = null;
     const upArgs = ["--laptop", "--no-open", ...rootArgs];
-    /** Start our own `up` and wait until its console proves live (or it ends, or the wait runs out). */
     const startOwned = async () => {
         const child = seams.spawnUp(upArgs);
         owned = child;
@@ -103,8 +92,8 @@ export async function runEasyStart(mode, args, seams) {
         if (joined !== EXIT.ok)
             return joined;
     }
+    elsewhere(proof);
     const url = proof.url;
-    /** The `up` this process owns, while it runs. */
     const ownedNow = () => (owned !== null && owned.running() ? owned : null);
     const waitOwned = async () => {
         const child = ownedNow();
@@ -114,7 +103,6 @@ export async function runEasyStart(mode, args, seams) {
         await child.exited;
         return EXIT.ok;
     };
-    // No local mode here (a new install on a computer with no sandbox): the browser, with the password `up` saved.
     if (seams.localMode() !== "on") {
         write(`Toolroll is on ${url}. Sign in with your password.`);
         await seams.openBrowser(url);
@@ -131,12 +119,10 @@ export async function runEasyStart(mode, args, seams) {
         await seams.openBrowser(link.url);
         return waitOwned();
     }
-    /** Move to the background service, handing over from our own `up` (background on stops it and proves it gone). */
     const handoff = async () => {
         const child = ownedNow();
         const result = await seams.backgroundOn(child === null ? null : {
             controllerPid: child.pid,
-            // The service didn't take over: our own `up` starts again, as before.
             restart: async () => { const again = await startOwned(); if (!again.ok)
                 throw Error(again.message); },
         });
@@ -175,14 +161,12 @@ export async function runEasyStart(mode, args, seams) {
     }
     return EXIT.ok;
 }
-/** `up` as an ordinary child of this process: its output kept (last lines, for a failed start), never on the screen. */
 export function spawnOwnedUp(args, options) {
     const entry = options.entry ?? process.argv[1];
     if (entry === undefined)
         throw Error("can't find Toolroll's own command to start it");
     const child = spawn(process.execPath, [...process.execArgv, entry, "up", ...args, "--db", options.databaseFile], {
         cwd: options.cwd,
-        // An IPC channel: if this process ends without stopping it, `up` sees its parent go and drains (operate.ts).
         stdio: ["ignore", "pipe", "pipe", "ipc"],
     });
     const lines = [];
@@ -203,7 +187,6 @@ export function spawnOwnedUp(args, options) {
     return { pid: child.pid ?? -1, exited, running: () => running, stop: () => { if (running)
             child.kill("SIGTERM"); }, tail: () => [...lines] };
 }
-/** The real seams, for this installation's database. */
 export function defaultEasyStartSeams(options) {
     const file = options.databaseFile;
     const cwd = options.cwd ?? process.cwd();
@@ -213,6 +196,10 @@ export function defaultEasyStartSeams(options) {
         write: options.write,
         prove: () => proveConsoleReadOnly(file, options.build),
         localMode: () => localModeRead(file),
+        initLocal: async () => (await import("./operate.js")).easyStartInitLocalMode(file, {
+            stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true, agent: underAgent(process.env), json: false,
+            remote: (await import("./local-owner.js")).localOwnerRequested(),
+        }),
         serviceInstalled: () => backgroundInstalled(),
         startService: async () => {
             const store = openStore(file);
@@ -252,7 +239,6 @@ export function defaultEasyStartSeams(options) {
         backgroundOn: async (foreground) => {
             const store = openStore(file);
             try {
-                // At this terminal, but the screen owns its input: another service on this database is refused, not asked.
                 const on = await backgroundOn(store, file, null, { terminal: false, ...(foreground === null ? {} : { foreground }) });
                 if (on.ok)
                     return { ok: true, message: `Toolroll now runs in the background at ${on.url}. It starts when you log in.` };
@@ -264,7 +250,6 @@ export function defaultEasyStartSeams(options) {
         },
         backgroundAsked: () => {
             const store = openStoreReadOnly(file);
-            // Unreadable: never ask on the strength of a database this build can't read.
             if (store === null)
                 return true;
             try {
@@ -296,15 +281,12 @@ export function defaultEasyStartSeams(options) {
         admit: options.admit,
     };
 }
-/** The terminal UI bundle (dist/tui.js, built from src/tui/entry.tsx), loaded only when the screen opens. */
 async function loadTui() {
     const bundled = new URL("./tui.js", import.meta.url);
     if (existsSync(bundled))
         return await import(bundled.href);
-    // From source (`npm run dev`): the entry itself.
     return await import(pathToFileURL(new URL("./tui/entry.tsx", import.meta.url).pathname).href);
 }
-/** Local mode as saved, read only: "absent" with no database yet; an older database has none ("off"). */
 export function localModeRead(file) {
     if (file !== ":memory:" && !existsSync(file))
         return "absent";
@@ -312,7 +294,12 @@ export function localModeRead(file) {
     if (store === null)
         return "off";
     try {
-        return localModeOf(store)?.enabled === true ? "on" : "off";
+        if (localModeOf(store)?.enabled === true)
+            return "on";
+        return localModeCandidate(store) ? "candidate" : "off";
+    }
+    catch {
+        return "off";
     }
     finally {
         store.close();

package/dist/egress.js

@@ -1,15 +1,3 @@
-/**
- * What a build may reach on the network (docs/plans/agent-baseline-hardening.md, arc 1).
- *
- * A run's network is part of its sealed execution profile: the hosts it may reach are resolved once, when the scope
- * is written (the provider's own hosts, the package registries the project's own checkout names,
- * and the project's added hosts), and that snapshot is what the approval binds and the launch enforces. Nothing at
- * launch re-derives it from settings changed since or from files the agent wrote.
- *
- * The launch enforces it at the operating system (Anthropic's sandbox-runtime: its Seatbelt network rules on macOS, a
- * network namespace on Linux with the proxy relayed in) and reaches the world through one proxy of its own (startEgressProxy), which admits only the
- * snapshot's hosts. The proxy never decrypts TLS: it restricts where a build connects, not what it sends there.
- */
 import { createServer, request as httpRequest } from "node:http";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { isIP } from "node:net";
@@ -19,25 +7,16 @@ import { basename, join } from "node:path";
 import { connectFirst, isPublicAddress } from "./scout-net.js";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { folderAnswers } from "./folder-gate.js";
-/** The policy's shape version: a worker enforces the versions it knows and refuses any other. */
 export const NETWORK_POLICY_VERSION = 1;
 export const PROJECT_NETWORK_DEFAULT = { mode: "allowlist", hosts: [], loopback: "proxy-only" };
-/** At most this many hosts a project adds (a list longer than this is a different policy: open). */
 export const MAX_NETWORK_HOSTS = 200;
-/** At most this many in a sealed snapshot: the project's, plus its provider's and every registry's. */
 export const MAX_SNAPSHOT_HOSTS = MAX_NETWORK_HOSTS + 100;
-/**
- * A host as a policy names it: lowercase ASCII (an international name in its punycode form), no trailing dot, at
- * least two labels, each 1–63 letters, digits or hyphens; or `*.` and such a name, for every name under it. Never an
- * IP address, a port, a path or a bare top-level name. Null when it is none of these.
- */
 export function normalizeHost(input) {
     const trimmed = input.trim().toLowerCase().replace(/\.$/, "");
     const wildcard = trimmed.startsWith("*.");
     const bare = wildcard ? trimmed.slice(2) : trimmed;
     if (bare === "" || bare.length > 253 || isIP(bare.replace(/^\[|\]$/g, "")) !== 0)
         return null;
-    // Nothing of a URL's other parts: the converter below would quietly cut a name at a slash or a colon.
     if (/[\s/\\:@?#%[\]*,;]/.test(bare))
         return null;
     const ascii = domainToASCII(bare);
@@ -48,23 +27,16 @@ export function normalizeHost(input) {
         return null;
     if (!labels.every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
         return null;
-    // A name whose last label is all digits reads as an address to too many resolvers.
     if (/^\d+$/.test(labels.at(-1)))
         return null;
     return wildcard ? `*.${ascii}` : ascii;
 }
-/** Whether `host` (as a client named it) is one a policy's list admits: an exact name, or a name under a `*.` entry. */
 export function hostAllowed(host, hosts) {
     const name = normalizeHost(host);
     if (name === null || name.startsWith("*."))
         return false;
     return hosts.some(entry => entry === name || (entry.startsWith("*.") && name.endsWith(entry.slice(1))));
 }
-/**
- * Each provider's own hosts (catalog version 1): its model API and the sign-in refresh its CLI needs. Codex starts
- * its harness outside its command sandbox, so its hosts matter only to what its commands may reach. An ACP agent
- * talks to whatever model service it was set up with; its row names the hosts its own service uses.
- */
 export const PROVIDER_HOSTS = {
     claude: ["api.anthropic.com", "console.anthropic.com", "platform.claude.com"],
     codex: ["api.openai.com", "chatgpt.com", "auth.openai.com"],
@@ -74,7 +46,6 @@ export const PROVIDER_HOSTS = {
     cursor: ["*.cursor.sh", "*.cursor.com"],
     cline: ["api.cline.bot"],
     qwen: ["chat.qwen.ai", "dashscope.aliyuncs.com", "dashscope-intl.aliyuncs.com"],
-    // Goose talks to whatever model service it is set up with: a project using it adds that service's host.
     goose: [],
 };
 export const REGISTRY_HOSTS = {
@@ -85,7 +56,6 @@ export const REGISTRY_HOSTS = {
     ruby: ["rubygems.org", "index.rubygems.org"],
     jvm: ["repo.maven.apache.org", "repo1.maven.org", "plugins.gradle.org", "services.gradle.org", "downloads.gradle.org"],
 };
-/** The files that name each ecosystem, by file name wherever they are in the tree. */
 const ECOSYSTEM_FILES = {
     "package.json": "npm", "package-lock.json": "npm", "npm-shrinkwrap.json": "npm", "yarn.lock": "npm", "pnpm-lock.yaml": "npm", "bun.lock": "npm", "bun.lockb": "npm",
     "pyproject.toml": "python", "requirements.txt": "python", "pipfile": "python", "pipfile.lock": "python", "poetry.lock": "python", "uv.lock": "python", "setup.py": "python", "setup.cfg": "python",
@@ -94,7 +64,6 @@ const ECOSYSTEM_FILES = {
     "gemfile": "ruby", "gemfile.lock": "ruby",
     "pom.xml": "jvm", "build.gradle": "jvm", "build.gradle.kts": "jvm", "settings.gradle": "jvm", "settings.gradle.kts": "jvm",
 };
-/** The ecosystems a list of repository paths names (requirements-*.txt counts as Python). */
 export function ecosystemsOf(paths) {
     const found = new Set();
     for (const path of paths) {
@@ -105,18 +74,9 @@ export function ecosystemsOf(paths) {
     }
     return [...found].sort();
 }
-/** How deep and how wide the walk for ecosystem files goes (a monorepo names its ecosystems near its root). */
 const WALK_DEPTH = 3, WALK_LIMIT = 5_000;
 const WALK_SKIP = new Set(["node_modules", "vendor", "target", "dist", "build", "venv", "__pycache__"]);
-/**
- * The ecosystems the project's own checkout names: its files a few folders deep, read straight from the folder the
- * plane registered (which no build can write: agent-fence.ts taskBoundary), never a build's worktree. No process is
- * started and nothing in the repository runs. An unreadable folder names none: its builds reach the provider and the
- * project's own hosts only.
- */
 export function repositoryEcosystems(repo) {
-    // In the console, a folder that hasn't answered a look lately is not walked on its thread (folder-gate.ts): it names
-    // none, as an unreadable folder does.
     if (!folderAnswers(repo))
         return [];
     const paths = [];
@@ -140,7 +100,6 @@ export function repositoryEcosystems(repo) {
     walk(repo, 0);
     return ecosystemsOf(paths);
 }
-/** The network a new scope is written with: the project's setting, its provider's hosts and its ecosystems' registries. */
 export function resolveNetwork(provider, project, ecosystems) {
     if (project.mode === "open")
         return { version: NETWORK_POLICY_VERSION, mode: "open", hosts: [], loopback: project.loopback };
@@ -151,19 +110,12 @@ export function resolveNetwork(provider, project, ecosystems) {
     ]);
     return { version: NETWORK_POLICY_VERSION, mode: "allowlist", hosts: [...hosts].sort(), loopback: project.loopback };
 }
-/** The network of a launch nothing sealed one for (a planner, a check): its provider's own hosts and nothing else. */
 export function providerOnlyNetwork(provider) {
     return { version: NETWORK_POLICY_VERSION, mode: "allowlist", hosts: [...new Set(PROVIDER_HOSTS[provider] ?? [])].sort(), loopback: "proxy-only" };
 }
-/**
- * The network an approval sealed before network policies existed runs under: a deliberate narrowing (provider hosts
- * and the repository's registries, nothing the project added since, local services of this Mac out of reach). Never
- * widened by a setting changed after it was approved.
- */
 export function legacyNetwork(provider, ecosystems) {
     return { ...resolveNetwork(provider, { mode: "allowlist", hosts: [], loopback: "proxy-only" }, ecosystems) };
 }
-/** Strict re-hydration (scope.ts profileFromJson): exactly the keys this code writes, every host normalized, or null. */
 export function networkFromValue(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -191,7 +143,6 @@ export function networkFromValue(value) {
         return null;
     return { version: NETWORK_POLICY_VERSION, mode: v["mode"], hosts, loopback: v["loopback"] };
 }
-/** A project setting as saved (store.ts project_network), or null when it isn't one this code wrote. */
 export function projectNetworkFromValue(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -205,7 +156,6 @@ export function projectNetworkFromValue(value) {
         return null;
     return { mode: v["mode"], hosts: [...new Set(hosts)].sort(), loopback: v["loopback"] };
 }
-/** The network in plain words, for an approval card and a run's record. */
 export function networkWords(network) {
     if (network === null)
         return "Network: approved before network rules (provider and package registries only)";
@@ -220,7 +170,6 @@ export function networkWords(network) {
 }
 const REGISTRY_NAMES = { npm: "npm", python: "PyPI", rust: "crates.io", go: "the Go proxy", ruby: "RubyGems", jvm: "Maven and Gradle" };
 const HOST_LIMIT = 50;
-/** A stored record read back strictly: anything this code didn't write reads as none. */
 export function runNetworkFromValue(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -256,22 +205,14 @@ export function runNetworkFromValue(value) {
     }
     return out;
 }
-/** Every proxy setting a program might read, both cases, so none falls back to a direct connection the OS refuses. */
 export function proxyEnv(proxy, loopback) {
     const local = loopback === "proxy-only" ? "" : "localhost,127.0.0.1,::1";
     return {
         HTTPS_PROXY: proxy.url, https_proxy: proxy.url, HTTP_PROXY: proxy.url, http_proxy: proxy.url, ALL_PROXY: proxy.url, all_proxy: proxy.url,
         NO_PROXY: local, no_proxy: local,
-        // Node's own fetch reads the proxy variables only when told to (Node 24 and later; earlier versions ignore it).
         NODE_USE_ENV_PROXY: "1",
     };
 }
-/**
- * Start one run's proxy on loopback. Only a client presenting this run's credentials is served (another run's agent
- * on the same machine can't borrow it). CONNECT goes only to port 443 and plain HTTP only to port 80, only to a host
- * the run's list admits (matched by name before it is resolved), only to public addresses (the proxy resolves the
- * name itself and connects to exactly the addresses it checked). A plain HTTP request's Host must be the URL's host.
- */
 export async function startEgressProxy(options) {
     const addressAllowed = options.addressAllowed ?? isPublicAddress;
     const upstreamPort = options.upstreamPort ?? ((port) => port);
@@ -303,10 +244,8 @@ export async function startEgressProxy(options) {
         try {
             options.decided?.(key, allowed, why);
         }
-        catch { /* a listener's trouble is not the build's */ }
+        catch { }
     };
-    /** Basic credentials whose password is this run's secret, whatever the user name (the sandbox runtime puts its own
-     * attribution there). */
     const authorized = (incoming) => {
         const header = String(incoming.headers["proxy-authorization"] ?? "");
         const basic = /^Basic ([A-Za-z0-9+/=]+)$/.exec(header)?.[1];
@@ -317,7 +256,6 @@ export async function startEgressProxy(options) {
         const given = Buffer.from(colon < 0 ? "" : decoded.slice(colon + 1));
         return given.length === expected.length && timingSafeEqual(given, expected);
     };
-    /** The addresses a request may reach, or why it may not. */
     const admit = async (host, port, wantPort) => {
         if (port !== wantPort)
             return { ok: false, why: `port ${port} is not allowed` };

package/dist/email-settings.js

@@ -1,9 +1,3 @@
-/**
- * The mail server (v87) and where Inbox triggers read it (v89), saved from
- * Settings → Email in a 0600 file beside the database. Its own module, with
- * nothing but the file system, so the mailbox and triggers can read it
- * without pulling in the step runners.
- */
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 const EMAIL_FILE = "email.json";
@@ -23,7 +17,6 @@ export function readEmailSettings(dir) {
         return null;
     }
 }
-/** Save the mail server from Settings; an empty password keeps the saved one. An IMAP address lets Inbox triggers read it. */
 export function saveEmailSettings(dir, input) {
     const host = typeof input.host === "string" ? input.host.trim() : "";
     if (!/^[A-Za-z0-9.-]{1,253}$/.test(host))
@@ -43,7 +36,6 @@ export function saveEmailSettings(dir, input) {
         return { ok: false, message: "The reading port is a number, usually 993." };
     const password = typeof input.password === "string" && input.password !== "" ? input.password : readEmailSettings(dir)?.password ?? "";
     writeFileSync(join(dir, EMAIL_FILE), JSON.stringify({ host, port, secure: input.secure === true || input.secure === "on" || input.secure === "true" || port === 465, user, from, password,
-        // 993 is TLS from the start; any other port must upgrade with STARTTLS before the password is sent.
         imap: imapHost === "" ? null : { host: imapHost, port: imapPort, secure: imapPort === 993 } }), { mode: 0o600 });
     chmodSync(join(dir, EMAIL_FILE), 0o600);
     return { ok: true, said: imapHost === "" ? `Email is set up: it comes from ${from}.` : `Email is set up: it comes from ${from}, and Inbox triggers read ${imapHost}.` };