toolroll 0.9.103 → 0.9.105

package/dist/laptop-background.js

@@ -1,24 +1,3 @@
-/**
- * Keeping Toolroll running in the background on a laptop (easy-start plan D): `toolroll background on|off|show`,
- * `toolroll stop`, and the `laptop` part of `toolroll status`.
- *
- * The login item itself is laptop-service.ts's definition (com.toolroll.up / toolroll-up.service). This module is
- * the handoff around it:
- *
- * - **on** writes and validates the unit without loading it, stops the foreground `up` this invoker owns (if one runs
- *   for this database) by SIGTERM to its controller and waits until that controller's whole process record is proved
- *   gone by start identity and the port is free, then loads the unit and proves the console live within 30 s. Any
- *   failure boots the unit out, removes it (or puts back the one that was there), starts the foreground `up` again if
- *   it was stopped, and says what failed. An identical unit already loaded is left alone.
- * - **off** stops and removes only our own label.
- * - **stop**: with the service loaded, the supervisor stops it (it comes back at login); otherwise the controller of
- *   the proven console, found through its signed process record, gets SIGTERM — never the console child, which the
- *   controller would only start again.
- *
- * Every outside effect goes through LaptopSeams: tests give a temporary HOME, a scripted launchctl/systemctl, and their
- * own child processes. Without a supervisor seam, a test run (VITEST) refuses to reach the real launchctl or systemctl.
- * Other services (the desktop app's com.toolroll.browser, a watch on this database) are reported, never touched.
- */
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { createServer } from "node:net";
@@ -54,18 +33,15 @@ function resolveSeams(seams) {
         host: seams.host ?? hostname(),
         buildAt: seams.buildAt ?? installedBuild,
         healthTimeoutMs: seams.healthTimeoutMs ?? 30_000,
-        // A drain is bounded by `up`'s own forced stop (stop-grace 30 s + 20 s); a margin past it.
         exitTimeoutMs: seams.exitTimeoutMs ?? 75_000,
         ...(seams.foreground === undefined ? {} : { foreground: seams.foreground }),
     };
 }
 const realSupervisor = async (file, args, options) => {
-    // Tests never reach this machine's real launchd or systemd: they pass their own supervisor.
     if (process.env["VITEST"] !== undefined)
         throw Error(`a test reached the real ${file}: pass LaptopSeams.supervisor`);
     return (await import("./exec.js")).run(file, args, options);
 };
-/** The package version beside an installed unit's `dist/bin.js`. Null when it can't be read. */
 function installedBuild(entry) {
     try {
         const version = JSON.parse(readFileSync(join(dirname(dirname(entry)), "package.json"), "utf8")).version;
@@ -94,7 +70,6 @@ function portIsFree(port) {
         probe.listen(port, "127.0.0.1", () => probe.close(() => resolve(true)));
     });
 }
-/** `toolroll up`'s port when none is named. */
 const DEFAULT_PORT = 4180;
 const uid = () => (typeof process.getuid === "function" ? process.getuid() : 501);
 function labelOf(platform) {
@@ -114,31 +89,25 @@ function readUnit(path) {
 function firstLine(text) {
     return text.trim().split("\n")[0] ?? "";
 }
-// ---- the supervisor, for our own label only ------------------------------------------------------------------------
-/** Whether our label is loaded (launchd) or active (systemd) now. */
 async function serviceLoaded(s, platform) {
     if (platform === "darwin")
         return (await s.supervisor("launchctl", ["print", `gui/${uid()}/${LAPTOP_LABEL_DARWIN}`])).code === 0;
     const answer = await s.supervisor("systemctl", ["--user", "is-active", `${LAPTOP_LABEL_LINUX}.service`]);
     return ["active", "activating", "reloading", "deactivating"].includes(answer.stdout.trim());
 }
-/** The written unit, checked by the platform's own validator, never loaded. Null when it passes. */
 async function validateUnit(s, platform, path) {
     if (platform === "darwin") {
         const checked = await s.supervisor("plutil", ["-lint", path]);
         return checked.code === 0 ? null : `plutil refused the login item: ${firstLine(checked.stdout) || firstLine(checked.stderr) || `exit ${checked.code}`}`;
     }
     const checked = await s.supervisor("systemd-analyze", ["verify", "--user", path]);
-    // Not every Linux has systemd-analyze; systemctl itself still parses the unit when it loads it.
     if (checked.notFound)
         return null;
     return checked.code === 0 ? null : `systemd-analyze refused the unit: ${firstLine(checked.stderr) || firstLine(checked.stdout) || `exit ${checked.code}`}`;
 }
-/** Load and start our unit. Null on success. */
 async function startService(s, platform, path) {
     if (platform === "darwin") {
         const service = `gui/${uid()}/${LAPTOP_LABEL_DARWIN}`;
-        // `background off` disabled the label; loading it again is the person's explicit yes.
         const enabled = await s.supervisor("launchctl", ["enable", service]);
         if (enabled.code !== 0)
             return `launchctl could not enable ${LAPTOP_LABEL_DARWIN}: ${firstLine(enabled.stderr) || `exit ${enabled.code}`}`;
@@ -151,10 +120,6 @@ async function startService(s, platform, path) {
     const enabled = await s.supervisor("systemctl", ["--user", "enable", "--now", `${LAPTOP_LABEL_LINUX}.service`]);
     return enabled.code === 0 ? null : `systemctl could not start ${LAPTOP_LABEL_LINUX}: ${firstLine(enabled.stderr) || `exit ${enabled.code}`}`;
 }
-/**
- * Stop our unit. `until: "login"` (toolroll stop) leaves it to start again at the next login; `"removed"` (off,
- * rollback) also disables it. Resolves once the supervisor no longer has it running. Null on success.
- */
 async function stopService(s, platform, path, until) {
     if (platform === "darwin") {
         const service = `gui/${uid()}/${LAPTOP_LABEL_DARWIN}`;
@@ -166,7 +131,6 @@ async function stopService(s, platform, path, until) {
         const out = await s.supervisor("launchctl", ["bootout", service]);
         if (out.code !== 0)
             await s.supervisor("launchctl", ["unload", path]);
-        // launchctl can return before the label leaves the domain; wait for the observable boundary.
         for (const deadline = Date.now() + s.exitTimeoutMs;;) {
             if ((await s.supervisor("launchctl", ["print", service])).code !== 0)
                 return null;
@@ -181,12 +145,6 @@ async function stopService(s, platform, path, until) {
         return `systemctl could not stop ${LAPTOP_LABEL_LINUX}: ${firstLine(stopped.stderr) || `exit ${stopped.code}`}`;
     return null;
 }
-/**
- * The controller of this database's live console, proved from the plane's own records: a live runner on this host
- * whose signed process record names the proven console (pid and start time) and exactly one live `up` process, that
- * `up` still the process the record names (same start time), and the console's parent that `up`. Anything else —
- * no record, a reused pid, a console whose parent is someone else — proves nothing and is refused.
- */
 export function findController(store, databaseFile, console_, s) {
     let why = "no Toolroll process record names the running console";
     for (const runner of store.listRunners()) {
@@ -224,10 +182,6 @@ export function findController(store, databaseFile, console_, s) {
     }
     return { why };
 }
-/**
- * SIGTERM to the controller (its full drain), re-checking its start time at the moment of the signal, then wait until
- * every process in its signed record is proved gone by start identity. Never signals the console child.
- */
 async function drainController(databaseFile, controller, s) {
     if (s.probe.start(controller.pid) !== controller.started)
         return `process ${controller.pid} is no longer the \`up\` that was found; nothing was stopped`;
@@ -286,13 +240,11 @@ export async function backgroundShow(store, databaseFile, requestedPort, seams =
         return { ok: false, reason: "unreadable", message: conflicts.error };
     return { ok: true, show: { platform, label: definition.label, unit: definition.path, installed: compareInstalled(readUnit(definition.path), definition), loaded: await serviceLoaded(s, platform), running, conflicts, port } };
 }
-/** `requestedPort`: --port, else the running console's, else the port this laptop install saved, else `up`'s default. */
 export async function backgroundOn(store, databaseFile, requestedPort, seams = {}) {
     const s = resolveSeams(seams);
     const platform = s.platform;
     if (platform !== "darwin" && platform !== "linux")
         return { ok: false, reason: "unsupported", message: `there is no background service for ${platform}; keep \`toolroll up\` running yourself` };
-    // A login item runs at every login: something a person sets up, never a coding agent on their behalf.
     if (s.agent)
         return { ok: false, reason: "agent", message: "a coding agent can't set Toolroll to start at login; run `toolroll background on` yourself at a terminal" };
     const first = await s.proveConsole(databaseFile, store);
@@ -310,7 +262,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
         if (live.ok)
             return { ok: true, action: "unchanged", label: definition.label, unit: definition.path, url: live.url, pid: live.pid, stoppedForeground: false };
     }
-    // 1. Other services on this database (or the desktop app's console) are a person's call, at a terminal.
     const conflicts = detectOtherServices({ platform, home: s.home, db: databaseFile });
     if (!Array.isArray(conflicts))
         return { ok: false, reason: "unreadable", message: conflicts.error };
@@ -321,8 +272,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
         if (!(await s.confirm(`${reasons}. Keep Toolroll running in the background anyway?`)))
             return { ok: false, reason: "declined", message: "Nothing was changed." };
     }
-    // 2. What runs now: our service under another definition (replaced), the foreground `up` this invoker owns, or
-    // nothing. A console that runs elsewhere is not ours to stop.
     const live = await s.proveConsole(databaseFile, store);
     if (!live.ok && live.state === "refused")
         return { ok: false, reason: "console-unproven", message: live.message };
@@ -340,7 +289,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
             foreground = found;
         }
     }
-    // 3. The unit, written and validated, not loaded.
     const rollback = [];
     const restoreUnit = () => {
         try {
@@ -363,7 +311,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
         restoreUnit();
         return { ok: false, reason: "write", message: `could not write ${definition.path}: ${error.message}` };
     }
-    /** 7. Undo everything this call did, in reverse, and say what failed. */
     const fail = async (message, reason, loaded = false) => {
         if (loaded || (await serviceLoaded(s, platform))) {
             const out = await stopService(s, platform, definition.path, "removed");
@@ -389,8 +336,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
         restoreUnit();
         return { ok: false, reason: "invalid-unit", message: `${invalid}. Nothing was changed` };
     }
-    // 4. Hand over: the old definition's service is stopped through the supervisor, the foreground `up` by SIGTERM to its
-    // controller; either way, every process its record names is proved gone and the port is free before anything loads.
     if (wasLoaded) {
         const stopped = await stopService(s, platform, definition.path, "login");
         if (stopped !== null) {
@@ -411,7 +356,6 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
     if (!(await waitPortFree(handoffPort, s)) || (handoffPort !== port && !(await waitPortFree(port, s)))) {
         return fail(`port ${port} is still taken after Toolroll stopped`, "port-busy");
     }
-    // 5. Load it, and 6. prove the console it starts.
     const started = await startService(s, platform, definition.path);
     if (started !== null)
         return fail(started, "supervisor");
@@ -420,14 +364,12 @@ export async function backgroundOn(store, databaseFile, requestedPort, seams = {
         return fail(`the background service did not answer within ${Math.round(s.healthTimeoutMs / 1000)} s (${healthy.message})`, "unhealthy", true);
     return { ok: true, action: installed === "absent" ? "installed" : wasLoaded ? "replaced" : "installed", label: definition.label, unit: definition.path, url: healthy.url, pid: healthy.pid, stoppedForeground: foreground !== null };
 }
-/** The previous service, put back as it was: its unit is restored by the caller; this loads it again. */
 async function restartPrevious(s, platform, path, before, rollback) {
     if (before === null)
         return;
     const again = await startService(s, platform, path);
     rollback.push(again === null ? "started the previous background service again" : `could not start the previous background service again: ${again}`);
 }
-/** The supervisor stopped it: wait for the record's proof, without signalling anything ourselves. */
 async function waitControllerGone(databaseFile, controller, s) {
     const file = runnerProcessFile(databaseFile, controller.runner);
     for (const deadline = Date.now() + s.exitTimeoutMs;;) {
@@ -447,7 +389,6 @@ export async function backgroundOff(store, databaseFile, seams = {}) {
     const label = labelOf(platform), path = unitPath(platform, s.home);
     const present = existsSync(path);
     const loaded = await serviceLoaded(s, platform);
-    // The wish goes first: a restart must never race a person turning this off.
     recordBuilderWish(store, "stopped", "background off", packageVersion(), new Date());
     if (!present && !loaded)
         return { ok: true, action: "already-off", label, unit: path };
@@ -484,10 +425,8 @@ export async function laptopStop(store, databaseFile, seams = {}) {
     const live = await s.proveConsole(databaseFile, store);
     if (!live.ok && live.state === "refused")
         return { ok: false, reason: "console-unproven", message: live.message };
-    // The wish goes first: a restart must never race a person stopping this.
     recordBuilderWish(store, "stopped", "stop", packageVersion(), new Date());
     const found = live.ok ? findController(store, databaseFile, live, s) : null;
-    // Our service, loaded: the supervisor stops it (SIGTERM reaches the controller, which drains). It starts at login.
     if ((platform === "darwin" || platform === "linux") && existsSync(unitPath(platform, s.home)) && await serviceLoaded(s, platform)) {
         const stopped = await stopService(s, platform, unitPath(platform, s.home), "login");
         if (stopped !== null)
@@ -508,11 +447,6 @@ export async function laptopStop(store, databaseFile, seams = {}) {
         return { ok: false, reason: "still-running", message: drained };
     return { ok: true, action: "stopped", pid: found.pid, startsAtLogin: false };
 }
-/**
- * The `laptop` key of `toolroll status`: whether this database's console is proven live (its address and the console
- * process), and whether a background service runs it — ours ("on"), another service on this database or the desktop
- * app's ("other-service"), or none ("off"). Reads files only; never asks the supervisor.
- */
 export async function laptopStatus(store, databaseFile, seams = {}) {
     const s = resolveSeams(seams);
     let live;
@@ -534,17 +468,10 @@ export async function laptopStatus(store, databaseFile, seams = {}) {
     }
     return { running: live.ok, url: live.ok ? live.url : null, pid: live.ok ? live.pid : null, background };
 }
-// ---- easy start: starting the installed service again ------------------------------------------------------------------
-/** Whether Toolroll's own login item is installed here (its unit file exists). Reads one path; asks no supervisor. */
 export function backgroundInstalled(seams = {}) {
     const s = resolveSeams(seams);
     return (s.platform === "darwin" || s.platform === "linux") && existsSync(unitPath(s.platform, s.home));
 }
-/**
- * Bare `toolroll` and `toolroll open` with the background service installed but this database's console not running
- * (stopped with `toolroll stop`, or not yet started at this login): start it through its supervisor — never a second
- * `up` beside it — and prove the console it runs live. Our own label only.
- */
 export async function startInstalledService(store, databaseFile, seams = {}) {
     const s = resolveSeams(seams);
     const platform = s.platform;
@@ -559,14 +486,11 @@ export async function startInstalledService(store, databaseFile, seams = {}) {
             return { ok: false, state: "refused", message: started };
     }
     else if (platform === "darwin") {
-        // Loaded but not answering (between restarts): ask launchd to run it now.
         await s.supervisor("launchctl", ["kickstart", `gui/${uid()}/${LAPTOP_LABEL_DARWIN}`]);
     }
     const healthy = await awaitHealthy(databaseFile, store, s);
     return healthy.ok ? healthy : { ok: false, state: "refused", message: `the background service did not answer within ${Math.round(s.healthTimeoutMs / 1000)} s (${healthy.message})` };
 }
-// ---- restarting this computer's own builder (plain-toolroll.md P2.3) ---------------------------------------------------
-/** Whether the supervisor shows our process gone: not loaded, or loaded with nothing running. Null when it can't tell. */
 async function supervisedExit(s, platform) {
     if (platform === "darwin") {
         const shown = await s.supervisor("launchctl", ["print", `gui/${uid()}/${LAPTOP_LABEL_DARWIN}`]);
@@ -580,7 +504,6 @@ async function supervisedExit(s, platform) {
     const state = shown.stdout.trim();
     return state === "inactive" || state === "failed" ? true : state === "" || state === "unknown" ? null : false;
 }
-/** Whether the unit is switched off at the supervisor (`background off` disabled it). Null when it can't tell. */
 async function labelDisabled(s, platform) {
     if (platform === "darwin") {
         const shown = await s.supervisor("launchctl", ["print-disabled", `gui/${uid()}`]);
@@ -594,8 +517,6 @@ async function labelDisabled(s, platform) {
         return null;
     return shown.stdout.trim() === "enabled" ? false : true;
 }
-/** Whether every process of this computer's current registrations is proved gone, by their signed records. False: one
- * may live, or nothing proves it. */
 function recordedRuntimeGone(store, databaseFile, s) {
     let proved = 0;
     for (const runner of store.listRunners()) {
@@ -608,12 +529,6 @@ function recordedRuntimeGone(store, databaseFile, s) {
     }
     return proved > 0;
 }
-/**
- * Start our own service again, by Toolroll alone, only when a person's recorded wish is to run, nothing is stopping or
- * updating, the old process is proved gone, what would start is what ran, and it isn't over its attempts. Every other
- * answer leaves the need with one label, "Start the builder". This never enables a disabled label, which is what sets it
- * apart from `startService`: a person's own yes.
- */
 export async function restartOwnBuilder(store, databaseFile, seams = {}, now = new Date()) {
     const s = resolveSeams(seams);
     const platform = s.platform;

package/dist/laptop-service.js

@@ -1,38 +1,10 @@
-/**
- * The laptop-mode login item, generated and compared — never installed.
- *
- * Laptop mode keeps one `toolroll up --laptop` console running for the
- * person who is logged in: a launchd LaunchAgent on macOS
- * (~/Library/LaunchAgents/com.toolroll.up.plist), a systemd user unit on
- * Linux (~/.config/systemd/user/toolroll-up.service). This module only
- * computes what that definition would be, whether an installed one matches,
- * and which existing services would conflict with it. Nothing here writes a
- * unit, loads one, or calls launchctl or systemctl; the handoff that does
- * (`toolroll background on`) is laptop-background.ts.
- *
- * The command is pinned with absolute paths, as daemon.ts pins its services:
- * launchd and systemd do not inherit an interactive shell's PATH, so the unit
- * runs the absolute Node binary with the package entry, and the database is
- * the canonical path (realpath of its folder) so a symlinked folder and its
- * target are one database. Values with control characters are refused: a
- * newline would end a systemd line and a NUL cannot appear in either format.
- *
- * Conflicts are reported, never touched: the desktop/browser service
- * (com.toolroll.browser, and com.standing-orders.browser from before the
- * rename) and any `daemon install` watch whose unit points at the same
- * database. Whatever cannot be read counts as a conflict, so the caller asks
- * instead of assuming.
- */
 import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-// POSIX paths throughout: a LaunchAgent and a systemd unit only ever name POSIX paths.
 import { posix } from "node:path";
 import { definitionDigest, launchdPlist } from "./daemon.js";
 const { basename, dirname, isAbsolute, join } = posix;
 export const LAPTOP_LABEL_DARWIN = "com.toolroll.up";
 export const LAPTOP_LABEL_LINUX = "toolroll-up";
-/** The services laptop mode never runs beside on macOS: the desktop app's browser controller, either name. */
 export const BROWSER_SERVICE_LABELS = ["com.toolroll.browser", "com.standing-orders.browser"];
-/** The watch labels daemon.ts writes (labelFor / legacyLabelFor). */
 const WATCH_PREFIXES = ["com.toolroll.watch.", "com.standing-orders.watch."];
 export const nodeFs = {
     exists: existsSync,
@@ -40,8 +12,6 @@ export const nodeFs = {
     readdir: path => readdirSync(path),
     realpath: path => realpathSync(path),
 };
-// Every C0 control character and DEL: newline and NUL are the dangerous ones,
-// the rest are never part of a real path and are not valid XML 1.0 either.
 const CONTROL = /[\u0000-\u001f\u007f]/;
 function checkPath(name, value) {
     if (value === "")
@@ -52,11 +22,6 @@ function checkPath(name, value) {
         return `${name} must be an absolute path (got ${value})`;
     return null;
 }
-/**
- * The database path the unit names: its folder resolved through realpath,
- * its file name kept (the file may not exist yet). A relative, empty or
- * control-character path, or a folder that cannot be resolved, refuses.
- */
 export function canonicalDatabasePath(db, fs = nodeFs) {
     const problem = checkPath("the database path", db);
     if (problem !== null)
@@ -80,13 +45,6 @@ function unitPathFor(platform, home) {
         ? { label: LAPTOP_LABEL_DARWIN, path: join(home, "Library", "LaunchAgents", `${LAPTOP_LABEL_DARWIN}.plist`) }
         : { label: LAPTOP_LABEL_LINUX, path: join(home, ".config", "systemd", "user", `${LAPTOP_LABEL_LINUX}.service`) };
 }
-/**
- * The login item for laptop mode, computed without writing anything. On
- * macOS the text comes from daemon.ts's launchdPlist, so it carries the same
- * KeepAlive/ExitTimeOut contract and the same service digest (which binds the
- * runtime's and package's code, read only). On Linux it is a systemd user
- * unit in daemon.ts's shape, with systemd's `%` and `$` expansion escaped.
- */
 export function laptopServiceDefinition(args) {
     const { platform } = args;
     if (platform !== "darwin" && platform !== "linux")
@@ -114,11 +72,6 @@ export function laptopServiceDefinition(args) {
         : systemdUnit({ command, workingDirectory: stateDir, pathEnv, logPath });
     return { platform, label, path, text, digest: definitionDigest(text), command, db, logPath };
 }
-/**
- * The systemd user unit: daemon.ts's watch unit shape (Restart=always,
- * default.target) plus TimeoutStopSec=60, launchd's ExitTimeOut, so a stop
- * gets the same drain window on both platforms.
- */
 function systemdUnit(args) {
     return `[Unit]
 Description=toolroll laptop console
@@ -138,35 +91,20 @@ StandardError=append:${systemdSpecifiers(args.logPath)}
 WantedBy=default.target
 `;
 }
-/** `%` starts a specifier in every systemd setting. */
 function systemdSpecifiers(text) {
     return text.replace(/%/g, "%%");
 }
-/**
- * daemon.ts's quoting (double quotes around anything with whitespace,
- * quotes or backslashes; `"` and `\` escaped), plus `%%` everywhere and, in
- * a command line, `$$`, since ExecStart expands `$NAME`.
- */
 function systemdQuote(part, command) {
     let text = systemdSpecifiers(part);
     if (command)
         text = text.replace(/\$/g, "$$$$");
     return /[\s"'\\]/.test(text) || text === "" ? `"${text.replace(/(["\\])/g, "\\$1")}"` : text;
 }
-/** Whether an installed unit's text is exactly this definition. Null (or undefined) text means no unit is installed. */
 export function compareInstalled(existingText, definition) {
     if (existingText === null || existingText === undefined)
         return "absent";
     return existingText === definition.text && definitionDigest(existingText) === definition.digest ? "same" : "different";
 }
-/**
- * Existing services laptop mode must not run beside: the browser service on
- * macOS (whatever database it uses — it is a console of its own), and any
- * daemon.ts watch whose unit points at this database, by `--db` or by its
- * `--token-file` sitting in the database's folder (daemon install keeps the
- * runner token beside the database it was installed from). A unit that
- * cannot be read is listed too. Laptop mode's own unit is never a conflict.
- */
 export function detectOtherServices(args) {
     const fs = args.fs ?? nodeFs;
     if (args.platform !== "darwin" && args.platform !== "linux")
@@ -220,7 +158,6 @@ export function detectOtherServices(args) {
     }
     return conflicts;
 }
-/** Which database a watch's command line names: its `--db`, else the folder of its `--token-file`. */
 function watchDatabase(argv, fs) {
     const value = (flag) => {
         const at = argv.indexOf(flag);
@@ -243,12 +180,10 @@ function watchDatabase(argv, fs) {
         return { folder: dirname(tokenFile) };
     }
 }
-/** ProgramArguments from a plist daemon.ts wrote. */
 function plistProgramArguments(text) {
     const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text)?.[1] ?? "";
     return [...array.matchAll(/<string>([^<]*)<\/string>/g)].map(match => unxml(match[1] ?? ""));
 }
-/** ExecStart from a systemd unit, split as systemd would for the quoting daemon.ts and this module write. */
 function systemdExecStart(text) {
     const line = /^ExecStart=(.*)$/m.exec(text)?.[1] ?? "";
     return (line.match(/"(?:[^"\\]|\\.)*"|\S+/g) ?? []).map(part => (part.startsWith('"') ? part.slice(1, -1).replace(/\\(["\\])/g, "$1") : part).replace(/%%/g, "%").replace(/\$\$/g, "$"));
@@ -256,11 +191,9 @@ function systemdExecStart(text) {
 function unxml(text) {
     return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
 }
-/** The command an installed unit runs, argument by argument (a plist's ProgramArguments, a unit's ExecStart). */
 export function unitCommand(text, platform) {
     return platform === "darwin" ? plistProgramArguments(text) : systemdExecStart(text);
 }
-/** The value after `flag` in an installed unit's command, or null. */
 export function unitFlag(text, platform, flag) {
     const argv = unitCommand(text, platform);
     const at = argv.indexOf(flag);

package/dist/latency-timeline.js

@@ -1,20 +1,6 @@
-/**
- * Latency timelines (docs/plans/actors-lessons.md, from durable-actors' latency timeline): for one operation, a short
- * list of milestones, each an offset from its start, kept in the plane (latency_timeline, bounded and pruned) for:
- *
- * - console requests slower than SLOW_REQUEST_MS: route matched, signed in, chrome and worker reads, handler, render;
- * - release checks: each part's start and end, from the sealed report's start times and the check's own `took:` line;
- * - deploys: each phase, and each health wait with its reason (scripts/deploy-phases.mjs writes those).
- *
- * Milestones carry route ids, part and phase names and fixed reason words only: never a URL, a query, a body or a
- * secret. A console request's offsets are monotonic (performance.now within one process); a check's and a deploy's
- * are wall-clock offsets, since their parts run in other processes.
- */
 import { performance } from "node:perf_hooks";
 import { latencyTimelines, MAX_MILESTONES, recordLatencyTimeline } from "./store.js";
-/** A console request slower than this keeps its timeline. */
 export const SLOW_REQUEST_MS = 1_000;
-/** One operation's milestones as they happen, bounded (the store bounds them again when kept). */
 export class Timeline {
     startedAt = new Date();
     t0 = performance.now();
@@ -26,7 +12,6 @@ export class Timeline {
     }
     elapsed() { return performance.now() - this.t0; }
 }
-/** Keep a finished console request's timeline when it was slow. Best effort: a failed write never touches the answer. */
 export function keepSlowRequest(store, timeline, route, status, now) {
     const total = timeline.elapsed();
     if (total < SLOW_REQUEST_MS)
@@ -35,10 +20,9 @@ export function keepSlowRequest(store, timeline, route, status, now) {
         recordLatencyTimeline(store, { kind: "console", subject: route, startedAt: timeline.startedAt, totalMs: total,
             milestones: [...timeline.marks, { name: "answered", ms: total, detail: `status ${status}` }] }, now);
     }
-    catch { /* display only */ }
+    catch { }
 }
 const TOOK = /^(\d+(?:\.\d+)?) (s|min)$/;
-/** The check's own `took:` line (scripts/release-check.mjs): each part's duration, in ms, by label. */
 export function partDurations(stdout) {
     const line = stdout.split("\n").reverse().find(one => one.startsWith("took: "));
     const durations = new Map();
@@ -54,7 +38,6 @@ export function partDurations(stdout) {
     }
     return durations;
 }
-/** A release check's parts as milestones: each part that started, and its end where its duration is known. */
 export function checkMilestones(report, stdout) {
     const took = partDurations(stdout);
     const started = report.parts.flatMap(part => {
@@ -70,7 +53,6 @@ export function checkMilestones(report, stdout) {
     ]).sort((a, b) => a.ms - b.ms);
     return { startedAt: new Date(first), totalMs: Math.max(...milestones.map(one => one.ms)), milestones };
 }
-/** Keep a release check's timeline beside its run. Best effort: the check's outcome never depends on it. */
 export function keepCheckTimeline(store, args) {
     if (args.report === null)
         return;
@@ -80,9 +62,8 @@ export function keepCheckTimeline(store, args) {
             return;
         recordLatencyTimeline(store, { kind: "release-check", subject: `check ${args.report.mode}`, runId: args.runId, taskId: args.taskId, ...timeline }, args.now);
     }
-    catch { /* display only */ }
+    catch { }
 }
-/** 65 s → "1:05"; 3 723 s → "1:02:03". */
 export function clockWords(ms) {
     const seconds = Math.round(ms / 1000), h = Math.floor(seconds / 3600), m = Math.floor((seconds % 3600) / 60), s = seconds % 60;
     return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
@@ -98,7 +79,6 @@ function viewOf(one) {
             return { label: mark.name, at: `+${clockWords(mark.ms)}`, detail: began === undefined ? mark.detail ?? null : `took ${clockWords(mark.ms - began)}` };
         }) };
 }
-/** A run's check timelines and its task's deploy timelines, for the page (null: none kept). */
 export function timingFor(store, runId, taskId) {
     try {
         const kept = runId === null ? latencyTimelines(store, { taskId, limit: 5 }) : latencyTimelines(store, { runId, taskId, limit: 5 });
@@ -109,7 +89,6 @@ export function timingFor(store, runId, taskId) {
         return null;
     }
 }
-/** The approver's debug view beside /healthz (/health): the slowest recent console requests, one line each. */
 export function slowRequestLines(store, limit = 20) {
     try {
         return latencyTimelines(store, { kind: "console", limit }).map(one => `${one.startedAt} ${one.subject} ${Math.round(one.totalMs)} ms: ${one.milestones.map(mark => `${mark.name} +${Math.round(mark.ms)}${mark.detail === undefined ? "" : ` (${mark.detail})`}`).join(", ")}`);

package/dist/lead-about.js

@@ -1,8 +1,6 @@
 import { scanForSecrets } from "./evidence.js";
 export const ABOUT_YOU_MAX_LINES = 20;
-/** Each line is under 200 characters. */
 export const ABOUT_YOU_LINE_MAX = 199;
-/** This person's confirmed lines; an older store reads as none. */
 export function aboutYouOf(store, account) {
     if (account == null || account === "")
         return [];
@@ -13,7 +11,6 @@ export function aboutYouOf(store, account) {
         return [];
     }
 }
-/** One line as it is saved, or the problem with it. */
 export function checkAboutYouLine(value) {
     const line = typeof value === "string" ? value.replace(/^\s*[-*•]\s*/, "").replace(/\s+/g, " ").trim() : "";
     if (line.length < 2)
@@ -24,10 +21,8 @@ export function checkAboutYouLine(value) {
         return { ok: false, message: "Use plain words, with no passwords or keys." };
     return { ok: true, line };
 }
-/** The Settings form's text, one line each: the saved list, or the problem with it. Blank lines and repeats go. */
 export function checkAboutYou(text) {
     const lines = [];
-    // A problem names the line as the person sees it in the box, blank lines and repeats counted.
     for (const [index, raw] of text.replace(/\r\n?/g, "\n").split("\n").entries()) {
         if (raw.trim() === "")
             continue;
@@ -41,11 +36,9 @@ export function checkAboutYou(text) {
         return { ok: false, message: `Keep it to ${ABOUT_YOU_MAX_LINES} lines.` };
     return { ok: true, lines };
 }
-/** Save the whole list for this person (already checked). Their lead's name and persona are left as they are. */
 export function saveAboutYou(store, account, lines, now) {
     store.setLeadAbout(account, lines, now);
 }
-/** The list once a confirmed line is added, or once it replaces line `replaces` (1-based). */
 export function withAboutYouLine(lines, line, replaces) {
     if (replaces > 0) {
         if (replaces > lines.length)