@rackbops/ac-agent 2.0.0-alpha.53 → 2.0.0-alpha.54

package/dist/ac-agent.mjs

@@ -47,7 +47,7 @@ function _mergeNamespaces(n, m) {
 }
 
 var name = "@rackbops/ac-agent";
-var version = "2.0.0-alpha.53";
+var version = "2.0.0-alpha.54";
 var type = "module";
 var description = "The per-machine host agent (installed with npx @rackbops/ac-agent): an HTTPS health server plus install/status/uninstall for a Windows logon task or a systemd user unit.";
 var bin = {
@@ -224,6 +224,13 @@ function managerBinDirs(deps) {
     return dirs;
 }
 
+var searchPath$1 = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  managerBinDirs: managerBinDirs,
+  regExePath: regExePath,
+  searchPath: searchPath
+});
+
 const COMMAND_TIMEOUT_MS = 5_000;
 const CLASSIC_KEYS = [
     String.raw `HKCU\Software\Classes\claude`,
@@ -1811,6 +1818,21 @@ function tunnelPreflightEnvOverride(env) {
     requireAbsolute(raw, "AC_AGENT_TUNNEL_PREFLIGHT");
     return raw;
 }
+/** `AC_AGENT_TOOLCHAIN_UPGRADE` (#675): `1`/`true` or `0`/`false` (case-insensitive, surrounding space
+ *  ignored); blank or unset is `null` (the file decides); anything else throws, naming the value, like every
+ *  other `AC_AGENT_*` override that cannot be read: guessing at an opt-in that installs software would be
+ *  the wrong way to fail. */
+function toolchainUpgradeEnvOverride(env) {
+    const raw = env?.AC_AGENT_TOOLCHAIN_UPGRADE;
+    if (raw === undefined || raw.trim() === "")
+        return null;
+    const value = raw.trim().toLowerCase();
+    if (value === "1" || value === "true")
+        return true;
+    if (value === "0" || value === "false")
+        return false;
+    throw new Error(`AC_AGENT_TOOLCHAIN_UPGRADE must be 1, true, 0 or false, got: ${raw}`);
+}
 /** A `tunnel_config` / `tunnel_preflight` value read from `agent.toml`: `null` for an absent key, a
  *  non-string or a blank string, else the string as written (the verb refuses a relative one). */
 function tunnelPathFromFile(raw) {
@@ -1837,6 +1859,7 @@ function loadConfig(dir, deps) {
     const envPublishDir = publishDirEnvOverride(deps.env);
     const envTunnelConfig = tunnelConfigEnvOverride(deps.env);
     const envTunnelPreflight = tunnelPreflightEnvOverride(deps.env);
+    const envToolchainUpgrade = toolchainUpgradeEnvOverride(deps.env);
     const defaultReposRoot = () => path.join(deps.homedir(), "repos");
     const defaultClaudeProjectsDir = () => path.join(deps.homedir(), ".claude", "projects");
     const defaultPublish = () => defaultPublishDir(deps.platform, deps.env);
@@ -1852,6 +1875,7 @@ function loadConfig(dir, deps) {
                 publishDir: envPublishDir ?? defaultPublish(),
                 tunnelConfig: envTunnelConfig,
                 tunnelPreflight: envTunnelPreflight,
+                toolchainUpgrade: envToolchainUpgrade ?? false,
             },
             path: configPath,
             source: "defaults",
@@ -1871,6 +1895,7 @@ function loadConfig(dir, deps) {
             publishDir: envPublishDir ?? (typeof raw.publish_dir === "string" ? raw.publish_dir : defaultPublish()),
             tunnelConfig: envTunnelConfig ?? tunnelPathFromFile(raw.tunnel_config),
             tunnelPreflight: envTunnelPreflight ?? tunnelPathFromFile(raw.tunnel_preflight),
+            toolchainUpgrade: envToolchainUpgrade ?? raw.toolchain_upgrade === true,
         },
         path: configPath,
         source: "file",
@@ -1894,6 +1919,9 @@ function writeConfig(dir, config, deps) {
         toml.tunnel_config = config.tunnelConfig;
     if (config.tunnelPreflight !== null)
         toml.tunnel_preflight = config.tunnelPreflight;
+    // The opt-in (#675) is written only when it is on: absent means `false`, which is what a fresh file says.
+    if (config.toolchainUpgrade)
+        toml.toolchain_upgrade = true;
     deps.writeFile(configPath, stringify$1(toml));
     return configPath;
 }
@@ -22298,6 +22326,7 @@ async function status(deps, now = () => new Date()) {
         reposRoot: loaded.config.reposRoot,
         reposCount: listRepos(loaded.config.reposRoot, deps.repoFs).repos.length,
         publishDir: loaded.config.publishDir,
+        toolchainUpgrade: loaded.config.toolchainUpgrade,
         grants,
         virtualized: virtualization.virtualized,
         lanAddress: deps.ips[0] ?? null,
@@ -23090,6 +23119,36 @@ function healthResultFrom(ok, body) {
     const version = typeof body === "object" && body !== null ? body.version : undefined;
     return typeof version === "string" ? { ok, version } : { ok };
 }
+/** What `registerToolchainUpgradeVerb` is given (#675), apart from the process-level pieces `realServe` has
+ *  to build itself. Here, and exported, so the wiring that matters (gate 2: the verb is on only when THIS
+ *  machine's loaded `agent.toml` says so) is a function with a test, not a line in `realServe` that nothing
+ *  but a real run reaches. */
+function toolchainUpgradeDeps(args) {
+    return {
+        enabled: () => args.loaded.config.toolchainUpgrade,
+        platform: args.platform,
+        which: args.which,
+        searchPath: args.searchPath,
+        run: args.run,
+        jobs: args.jobs,
+        username: () => {
+            try {
+                return args.userInfo().username;
+            }
+            catch {
+                return "<user>";
+            }
+        },
+        cwd: args.homedir,
+        logEvent: args.logEvent,
+    };
+}
+/** How many jobs `POST /v1/update` must refuse to restart the agent under: every kind that is running, plus
+ *  an upgrade that has passed its cap check but not yet started its job (#675; its pre-spawn waits can take
+ *  tens of seconds, during which no job exists). */
+function runningJobCount(jobs, upgrade) {
+    return () => jobs.runningCount() + upgrade.pendingStarts();
+}
 async function buildServiceDeps(overrides = {}) {
     const os = await import('node:os');
     const fs = await import('node:fs');
@@ -23217,6 +23276,8 @@ async function realServe(overrides = {}) {
     const { realPublishFsIo } = await Promise.resolve().then(function () { return publish$1; });
     const { registerPublishVerb } = await Promise.resolve().then(function () { return publish; });
     const { registerTunnelVerb, realTunnelFs } = await Promise.resolve().then(function () { return tunnel; });
+    const { registerToolchainUpgradeVerb } = await Promise.resolve().then(function () { return toolchainUpgrade; });
+    const { searchPath } = await Promise.resolve().then(function () { return searchPath$1; });
     // `--config-dir`/`--state-dir` (E4 finding 13, #241) are what `install` bakes into the registered
     // task/unit, so a `serve` launched that way never falls back to re-resolving from its own
     // environment (a Task Scheduler process / systemd --user unit does not see the installing
@@ -23425,6 +23486,20 @@ async function realServe(overrides = {}) {
         which: which$1,
     });
     registerGhVerb(registry$3, { run, which: which$1, logEvent: (message) => log$1.write(message) });
+    // The toolchain upgrade (#675): installs software on THIS machine, so it needs the console's grant AND
+    // this machine's own `toolchain_upgrade = true` (read from the config loaded at start-up). Registered
+    // here, not beside the tunnel verb, because it shares the job registry created just above.
+    const toolchainUpgrade$1 = registerToolchainUpgradeVerb(registry$3, toolchainUpgradeDeps({
+        loaded,
+        platform: process.platform,
+        which: which$1,
+        searchPath: async () => (await searchPath({ platform: process.platform, env: process.env, run })).path,
+        run,
+        jobs,
+        userInfo: () => os.userInfo(),
+        homedir: () => os.homedir(),
+        logEvent: (message) => log$1.write(message),
+    }));
     const readGrantsResult = readGrants(dirs.stateDir, readFile);
     if (readGrantsResult.kind === "malformed") {
         log$1.write(`grants.json unreadable (${readGrantsResult.error}), starting with no grants`);
@@ -23483,7 +23558,7 @@ async function realServe(overrides = {}) {
             env: process.env,
         }),
         selfUpdateSupported: selfUpdateSupported(process.platform),
-        runningJobs: () => jobs.runningCount(),
+        runningJobs: runningJobCount(jobs, toolchainUpgrade$1),
         now: () => new Date(),
         logEvent: (message) => log$1.write(message),
     });
@@ -64427,6 +64502,39 @@ var lock = /*#__PURE__*/Object.freeze({
 /** `agent.log`, rotated to `agent.log.1` past 1 MiB on open -- checked once at `serve` startup,
  * not on every write, so a long-running agent's own line-by-line appends stay cheap. */
 const MAX_SIZE_BYTES = 1024 * 1024;
+/** The characters that end a line, rewrite one, or reorder one: every C0 and C1 control character and DEL
+ *  (`\n`, `\r`, an ANSI escape that moves the cursor up and erases), U+2028 and U+2029 (the line and
+ *  paragraph separators that Python's `splitlines` and most editors break on), and the bidirectional
+ *  formatting controls U+202A-202E and U+2066-2069 (which reorder what a terminal shows). */
+function isLineBreaking(code) {
+    return (code <= 0x1f ||
+        (code >= 0x7f && code <= 0x9f) ||
+        code === 0x2028 ||
+        code === 0x2029 ||
+        (code >= 0x202a && code <= 0x202e) ||
+        (code >= 0x2066 && code <= 0x2069));
+}
+/** One log entry is one line, whatever it was built from (#675): a request line carries the request's
+ *  own path, which an unauthenticated caller chooses and which arrives percent-decoded, so `%0A` would
+ *  otherwise start a line of the caller's own wording (a forged audit line) and an escape sequence would
+ *  erase real ones on the screen of whoever reads the file. Each such character is written as `\xNN`, or
+ *  `\uNNNN` above U+00FF. */
+function oneLine(line) {
+    let out = "";
+    for (const ch of line) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (!isLineBreaking(code)) {
+            out += ch;
+        }
+        else if (code <= 0xff) {
+            out += `\\x${code.toString(16).padStart(2, "0")}`;
+        }
+        else {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+    }
+    return out;
+}
 function openLog(stateDir, deps) {
     const logPath = path.join(stateDir, "agent.log");
     const rotatedPath = path.join(stateDir, "agent.log.1");
@@ -64435,7 +64543,7 @@ function openLog(stateDir, deps) {
         deps.rename(logPath, rotatedPath);
     }
     return {
-        write: (line) => deps.appendFile(logPath, `${line}\n`),
+        write: (line) => deps.appendFile(logPath, `${oneLine(line)}\n`),
     };
 }
 
@@ -64762,6 +64870,100 @@ const streamSSE = (c, cb, onError) => {
 	return c.newResponse(stream.responseReadable);
 };
 
+/**
+ * The agent's job-events SSE response, shared by every verb that exposes a job stream (#49 49b for the
+ * claude jobs; #675 extracted it so `GET /v1/toolchain/upgrade/:jobId/events` is the same algorithm, not
+ * a copy). The route is the host's own (`packages/host/src/tasks/route.ts:14-90`) with `exitCode` added to
+ * the `done` frame -- `line` and `done` are the exact event names the host emits and the shell's
+ * `useTasks.ts` listens for (E4 §5 decision 12).
+ *
+ * `kind` is the capability boundary: a verb serves only its own kind's jobs, so a job of another kind is
+ * `404 no such job`, exactly like an unknown id. A plugin holding `agent.exec.claude` therefore never
+ * reads an upgrade job's log, and one holding `agent.toolchain.upgrade` never reads a claude job's.
+ */
+async function jobEventsResponse(jobs, id, c, kind) {
+    const initial = jobs.get(id);
+    if (!initial || initial.view.kind !== kind)
+        return c.json({ ok: false, error: "no such job" }, 404);
+    // streamSSE sets Cache-Control: no-cache itself -- only X-Accel-Buffering (disables a
+    // fronting proxy's response buffering, so lines aren't held back) needs setting explicitly.
+    c.header("X-Accel-Buffering", "no");
+    return streamSSE(c, async (stream) => {
+        if (initial.view.status !== "running") {
+            for (let i = 0; i < initial.lines.length; i++) {
+                if (stream.aborted)
+                    return;
+                await stream.writeSSE({
+                    event: "line",
+                    data: JSON.stringify(initial.lines[i]),
+                    id: String(initial.linesOffset + i),
+                });
+            }
+            await stream.writeSSE({
+                event: "done",
+                data: JSON.stringify({
+                    status: initial.view.status,
+                    exitCode: initial.view.exitCode ?? null,
+                }),
+            });
+            return;
+        }
+        // Subscribe BEFORE replaying, synchronously with the `initial` snapshot above -- see
+        // packages/host/src/tasks/route.ts:41-48 for why this ordering is what closes the race
+        // window between a line being logged and it landing in neither the snapshot nor the
+        // subscription.
+        let replaying = true;
+        const queued = [];
+        let resolveDone;
+        const donePromise = new Promise((resolve) => {
+            resolveDone = resolve;
+        });
+        const unsubscribe = jobs.subscribe(id, {
+            line: (line, lineId) => {
+                if (replaying)
+                    queued.push({ line, id: lineId });
+                else
+                    void stream.writeSSE({
+                        event: "line",
+                        data: JSON.stringify(line),
+                        id: String(lineId),
+                    });
+            },
+            done: (status, exitCode) => resolveDone({ status, exitCode }),
+        });
+        stream.onAbort(unsubscribe);
+        for (let i = 0; i < initial.lines.length; i++) {
+            if (stream.aborted)
+                return;
+            await stream.writeSSE({
+                event: "line",
+                data: JSON.stringify(initial.lines[i]),
+                id: String(initial.linesOffset + i),
+            });
+        }
+        for (const q of queued) {
+            if (stream.aborted)
+                return;
+            await stream.writeSSE({ event: "line", data: JSON.stringify(q.line), id: String(q.id) });
+        }
+        replaying = false;
+        const final = await donePromise;
+        unsubscribe();
+        await stream.writeSSE({
+            event: "done",
+            data: JSON.stringify({ status: final.status, exitCode: final.exitCode }),
+        });
+    });
+}
+
+/** How long a terminated child is given on POSIX before `SIGKILL` follows the polite `SIGTERM`. */
+const KILL_GRACE_MS = 10_000;
+/** How long after a limit fires the job waits for the child to close before it is finished regardless
+ *  (the grace period above, and five seconds more). */
+const LIMIT_SETTLE_MS = KILL_GRACE_MS + 5_000;
+/** How much a forced finish discards from a pipe it could not close before it closes it (see `forceFinish`):
+ *  generous for any process that merely logs, a small fraction of what a flood writes in a second. */
+const DRAIN_BUDGET_BYTES = 64 * 1024 * 1024;
 function spawnJob(argv, options, handle, spawnFn = spawn) {
     const [cmd, ...args] = argv;
     handle.log(`${options.header} in ${options.cwd}`);
@@ -64774,25 +64976,152 @@ function spawnJob(argv, options, handle, spawnFn = spawn) {
     });
     let stdoutBuf = "";
     let stderrBuf = "";
+    let settled = false;
+    let limitHit = false;
+    let exited = false;
+    let exitCode = null;
+    let loggedChars = 0;
+    let graceTimer;
+    let timeoutTimer;
+    let settleTimer;
+    let exitTimer;
+    /** The one place a limit fires: tell the caller, say so in the log, and kill the child. A child that has
+     *  already exited is not killed (its pid may belong to another process by now, and `taskkill /t /f` would
+     *  take that one and everything it started): the limit is recorded, the rest of the output dropped, and
+     *  the job finishes when the output closes or `exitSettleMs` runs out. */
+    function hitLimit(limit, message) {
+        if (limitHit || settled)
+            return;
+        limitHit = true;
+        options.onLimit?.(limit);
+        handle.log(message);
+        if (exited)
+            return;
+        killChild(child, spawnFn);
+        if (process.platform !== "win32") {
+            // SIGTERM asks politely; a child that ignores it (an installer mid-transaction) is killed outright.
+            graceTimer = setTimeout(() => {
+                if (!settled && !exited)
+                    child.kill("SIGKILL");
+            }, KILL_GRACE_MS);
+            graceTimer.unref?.();
+        }
+        settleTimer = setTimeout(forceFinish, options.limitSettleMs ?? LIMIT_SETTLE_MS);
+        settleTimer.unref?.();
+    }
+    /** The child never closed (a descendant, out of the agent's reach, still holds its output pipes): finish
+     *  the job anyway so it cannot stay `running` and hold its slot forever. A child that had exited keeps
+     *  its real exit code (a killed one that exited is the same: its code is whatever the kill left, `null`
+     *  for a signal); one that was killed and never even exited finishes `failed` with none.
+     *
+     *  The streams are DRAINED from here on rather than destroyed: closing the read end of a pipe another
+     *  process still holds makes that process's next write raise SIGPIPE, which by default ends it, and these
+     *  are the processes the agent must not disturb (a root-owned `apt-get` in the middle of a dpkg
+     *  transaction, a service a maintainer script started). What they write is discarded. The drain has a
+     *  budget (`drainBudgetBytes`): a descendant that FLOODS the pipe costs the agent most of a core for as
+     *  long as it runs, so past the budget the streams are destroyed after all, which ends only that one. */
+    function forceFinish() {
+        if (settled)
+            return;
+        settled = true;
+        stopTimers();
+        const budget = options.drainBudgetBytes ?? DRAIN_BUDGET_BYTES;
+        let drained = 0;
+        for (const stream of [child.stdout, child.stderr]) {
+            stream?.removeAllListeners("data");
+            stream?.on("data", (chunk) => {
+                drained += chunk.length;
+                if (drained > budget) {
+                    child.stdout?.destroy();
+                    child.stderr?.destroy();
+                }
+            });
+            stream?.resume();
+        }
+        if (exited) {
+            if (stdoutBuf !== "")
+                emit(stdoutBuf);
+            if (stderrBuf !== "")
+                emit(stderrBuf);
+            handle.log("[the command exited, but its output never closed; processes it started may still be running]");
+            handle.finish(exitCode === 0 && !limitHit ? "done" : "failed", exitCode);
+            return;
+        }
+        handle.log("[killed, but its output never closed; processes it started may still be running]");
+        handle.finish("failed", null);
+    }
+    /** Every line the child prints goes through here, so the output cap counts exactly what is logged. */
+    function emit(line) {
+        if (limitHit)
+            return; // after a limit fires, the rest of the output is dropped, not logged
+        loggedChars += line.length + 1;
+        if (options.maxOutputChars !== undefined && loggedChars > options.maxOutputChars) {
+            hitLimit("output-cap", `[output capped at ${options.maxOutputChars} characters; killed]`);
+            return;
+        }
+        handle.log(line);
+    }
     function flush(buf, chunk) {
         const combined = buf + chunk;
         const lines = combined.split("\n");
         const remainder = lines.pop() ?? "";
         for (const line of lines)
-            handle.log(line);
+            emit(line);
         return remainder;
     }
+    /** The cap also counts what is held back waiting for a newline: a child that prints without ever ending
+     *  a line (a progress bar redrawn with `\r`, or a runaway) must not grow the agent's memory unboundedly
+     *  just because `emit` has not seen a line yet. */
+    function checkHeldOutput() {
+        const cap = options.maxOutputChars;
+        if (cap !== undefined && loggedChars + stdoutBuf.length + stderrBuf.length > cap) {
+            hitLimit("output-cap", `[output capped at ${cap} characters; killed]`);
+        }
+    }
     child.stdout?.on("data", (chunk) => {
+        if (limitHit)
+            return;
         stdoutBuf = flush(stdoutBuf, chunk.toString());
+        checkHeldOutput();
     });
     child.stderr?.on("data", (chunk) => {
+        if (limitHit)
+            return;
         stderrBuf = flush(stderrBuf, chunk.toString());
+        checkHeldOutput();
+    });
+    if (options.timeoutMs !== undefined) {
+        const ms = options.timeoutMs;
+        timeoutTimer = setTimeout(() => hitLimit("timeout", `[timed out after ${ms} ms; killed]`), ms);
+        timeoutTimer.unref?.();
+    }
+    function stopTimers() {
+        if (timeoutTimer !== undefined)
+            clearTimeout(timeoutTimer);
+        if (graceTimer !== undefined)
+            clearTimeout(graceTimer);
+        if (settleTimer !== undefined)
+            clearTimeout(settleTimer);
+    }
+    child.on("exit", (code) => {
+        if (settled)
+            return;
+        exited = true;
+        exitCode = code;
+        // The command is over: nothing is left to time out, and a late kill is unsafe (pid reuse). The grace
+        // timer, if one is pending, checks `exited` itself; `forceFinish` returns once `settled`.
+        if (timeoutTimer !== undefined)
+            clearTimeout(timeoutTimer);
+        if (options.exitSettleMs !== undefined) {
+            exitTimer = setTimeout(forceFinish, options.exitSettleMs);
+            exitTimer.unref?.();
+        }
     });
-    let settled = false;
     child.on("error", (err) => {
         if (settled)
             return;
         settled = true;
+        stopTimers();
         handle.log(`[spawn failed] ${err.message}`);
         handle.finish("failed", null);
     });
@@ -64800,22 +65129,47 @@ function spawnJob(argv, options, handle, spawnFn = spawn) {
         if (settled)
             return;
         settled = true;
+        stopTimers();
         // A trailing partial line (no final newline) is flushed here rather than dropped.
         if (stdoutBuf !== "")
-            handle.log(stdoutBuf);
+            emit(stdoutBuf);
         if (stderrBuf !== "")
-            handle.log(stderrBuf);
-        handle.finish(code === 0 ? "done" : "failed", code);
+            emit(stderrBuf);
+        handle.finish(code === 0 && !limitHit ? "done" : "failed", code);
     });
 }
+/** Kill a child and, on win32, everything it started: `taskkill /pid <pid> /t /f` (the shell is never
+ *  involved; a failure to launch it is swallowed because `child.kill()` below is the fallback). */
+function killChild(child, spawnFn) {
+    if (process.platform === "win32" && child.pid !== undefined) {
+        try {
+            // By absolute path (as `regExePath` does for reg.exe): a bare name is searched for in the working
+            // directory before PATH.
+            const taskkill = path.win32.join(process.env.SystemRoot ?? process.env.windir ?? String.raw `C:\Windows`, "System32", "taskkill.exe");
+            const killer = spawnFn(taskkill, ["/pid", String(child.pid), "/t", "/f"], {
+                shell: false,
+                windowsHide: true,
+                stdio: "ignore",
+            });
+            killer.on("error", () => { });
+        }
+        catch {
+            // fall through to the plain kill
+        }
+    }
+    child.kill();
+}
 
 /**
  * `POST /v1/exec/claude`, `GET /v1/jobs`, `GET /v1/jobs/:id`, `POST /v1/jobs/clear-finished`,
- * `GET /v1/jobs/:id/events` (#49, 49b, items 3-5). The SSE route is the host's own algorithm
- * (`packages/host/src/tasks/route.ts:14-90`) with `exitCode` added to the `done` frame -- `line`
- * and `done` are the exact event names the host emits and the shell's `useTasks.ts` listens for
- * (E4 §5 decision 12), so a browser `EventSource` deliberately isn't the client here (the token
- * travels as a header; the host's pinned client is what actually calls this).
+ * `GET /v1/jobs/:id/events` (#49, 49b, items 3-5). The SSE route is `jobs/events.ts`'s (the host's own
+ * algorithm, `packages/host/src/tasks/route.ts:14-90`, with `exitCode` added to the `done` frame; #675
+ * extracted it so the upgrade verb shares it), so a browser `EventSource` deliberately isn't the client
+ * here (the token travels as a header; the host's pinned client is what actually calls this).
+ *
+ * Every route here serves the `claude` kind only (#675): the registry also holds `toolchain-upgrade` jobs,
+ * which `agent.exec.claude` must not list, read, stream or clear, and which must not use up one of the
+ * claude jobs' four slots (`runningCount("claude")`).
  */
 const MAX_PROMPT_LENGTH = 8192;
 const PERMISSION_MODES = ["plan", "acceptEdits", "bypassPermissions"];
@@ -64894,7 +65248,7 @@ function registerClaudeVerbs(registry, deps) {
                     : "claude not found on PATH";
                 return c.json({ ok: false, error }, 502);
             }
-            if (deps.jobs.runningCount() >= MAX_RUNNING_CLAUDE_JOBS) {
+            if (deps.jobs.runningCount("claude") >= MAX_RUNNING_CLAUDE_JOBS) {
                 return c.json({ ok: false, error: "too many running jobs" }, 429);
             }
             const argv = [
@@ -64925,7 +65279,7 @@ function registerClaudeVerbs(registry, deps) {
         capability: "agent.exec.claude",
         method: "GET",
         path: "/jobs",
-        handler: async (c) => c.json({ ok: true, jobs: deps.jobs.list() }),
+        handler: async (c) => c.json({ ok: true, jobs: deps.jobs.list().filter((job) => job.kind === "claude") }),
     });
     registry.register({
         capability: "agent.exec.claude",
@@ -64933,8 +65287,10 @@ function registerClaudeVerbs(registry, deps) {
         path: "/jobs/:id",
         handler: async (c) => {
             const entry = deps.jobs.get(c.req.param("id") ?? "");
-            if (!entry)
+            // Another kind's job (#675) is "no such job" here, exactly like an unknown id.
+            if (entry?.view.kind !== "claude") {
                 return c.json({ ok: false, error: "no such job" }, 404);
+            }
             return c.json({ ok: true, job: entry.view });
         },
     });
@@ -64942,87 +65298,13 @@ function registerClaudeVerbs(registry, deps) {
         capability: "agent.exec.claude",
         method: "POST",
         path: "/jobs/clear-finished",
-        handler: async (c) => c.json({ ok: true, cleared: deps.jobs.clearFinished() }),
+        handler: async (c) => c.json({ ok: true, cleared: deps.jobs.clearFinished("claude") }),
     });
     registry.register({
         capability: "agent.exec.claude",
         method: "GET",
         path: "/jobs/:id/events",
-        handler: async (c) => {
-            const id = c.req.param("id") ?? "";
-            const initial = deps.jobs.get(id);
-            if (!initial)
-                return c.json({ ok: false, error: "no such job" }, 404);
-            // streamSSE sets Cache-Control: no-cache itself -- only X-Accel-Buffering (disables a
-            // fronting proxy's response buffering, so lines aren't held back) needs setting explicitly.
-            c.header("X-Accel-Buffering", "no");
-            return streamSSE(c, async (stream) => {
-                if (initial.view.status !== "running") {
-                    for (let i = 0; i < initial.lines.length; i++) {
-                        if (stream.aborted)
-                            return;
-                        await stream.writeSSE({
-                            event: "line",
-                            data: JSON.stringify(initial.lines[i]),
-                            id: String(initial.linesOffset + i),
-                        });
-                    }
-                    await stream.writeSSE({
-                        event: "done",
-                        data: JSON.stringify({
-                            status: initial.view.status,
-                            exitCode: initial.view.exitCode ?? null,
-                        }),
-                    });
-                    return;
-                }
-                // Subscribe BEFORE replaying, synchronously with the `initial` snapshot above -- see
-                // packages/host/src/tasks/route.ts:41-48 for why this ordering is what closes the race
-                // window between a line being logged and it landing in neither the snapshot nor the
-                // subscription.
-                let replaying = true;
-                const queued = [];
-                let resolveDone;
-                const donePromise = new Promise((resolve) => {
-                    resolveDone = resolve;
-                });
-                const unsubscribe = deps.jobs.subscribe(id, {
-                    line: (line, lineId) => {
-                        if (replaying)
-                            queued.push({ line, id: lineId });
-                        else
-                            void stream.writeSSE({
-                                event: "line",
-                                data: JSON.stringify(line),
-                                id: String(lineId),
-                            });
-                    },
-                    done: (status, exitCode) => resolveDone({ status, exitCode }),
-                });
-                stream.onAbort(unsubscribe);
-                for (let i = 0; i < initial.lines.length; i++) {
-                    if (stream.aborted)
-                        return;
-                    await stream.writeSSE({
-                        event: "line",
-                        data: JSON.stringify(initial.lines[i]),
-                        id: String(initial.linesOffset + i),
-                    });
-                }
-                for (const q of queued) {
-                    if (stream.aborted)
-                        return;
-                    await stream.writeSSE({ event: "line", data: JSON.stringify(q.line), id: String(q.id) });
-                }
-                replaying = false;
-                const final = await donePromise;
-                unsubscribe();
-                await stream.writeSSE({
-                    event: "done",
-                    data: JSON.stringify({ status: final.status, exitCode: final.exitCode }),
-                });
-            });
-        },
+        handler: async (c) => jobEventsResponse(deps.jobs, c.req.param("id") ?? "", c, "claude"),
     });
 }
 
@@ -65374,15 +65656,18 @@ function createJobRegistry(opts = {}) {
     // it forward to find the oldest finished entry.
     const entries = new Map();
     let seq = 0;
-    function evictOldestFinishedIfOverCap() {
+    /** The cap is per kind (#675): a plugin holding only `agent.exec.claude` that runs a few hundred
+     *  trivial jobs must not evict a finished upgrade job (and its outcome) the console has yet to read. */
+    function evictOldestFinishedIfOverCap(kind) {
         let finishedCount = 0;
-        for (const e of entries.values())
-            if (e.view.status !== "running")
+        for (const e of entries.values()) {
+            if (e.view.status !== "running" && e.view.kind === kind)
                 finishedCount++;
+        }
         if (finishedCount <= maxFinished)
             return;
         for (const [id, e] of entries) {
-            if (e.view.status !== "running") {
+            if (e.view.status !== "running" && e.view.kind === kind) {
                 entries.delete(id);
                 return;
             }
@@ -65437,7 +65722,7 @@ function createJobRegistry(opts = {}) {
                     }
                 }
                 entry.subscribers.clear();
-                evictOldestFinishedIfOverCap();
+                evictOldestFinishedIfOverCap(entry.view.kind);
             },
         };
     }
@@ -65465,17 +65750,18 @@ function createJobRegistry(opts = {}) {
             entry.subscribers.add(on);
             return () => entry.subscribers.delete(on);
         },
-        runningCount: () => {
+        runningCount: (kind) => {
             let count = 0;
-            for (const e of entries.values())
-                if (e.view.status === "running")
+            for (const e of entries.values()) {
+                if (e.view.status === "running" && (kind === undefined || e.view.kind === kind))
                     count++;
+            }
             return count;
         },
-        clearFinished: () => {
+        clearFinished: (kind) => {
             let cleared = 0;
             for (const [id, e] of entries) {
-                if (e.view.status !== "running") {
+                if (e.view.status !== "running" && (kind === undefined || e.view.kind === kind)) {
                     entries.delete(id);
                     cleared++;
                 }
@@ -66608,7 +66894,7 @@ function ensureScript(fs, stateDir) {
 function sanitizeMachine(hostname) {
     return hostname.replace(/[^A-Za-z0-9._-]/g, "-");
 }
-function lastNonEmptyLine$1(text) {
+function lastNonEmptyLine$2(text) {
     const lines = text
         .split("\n")
         .map((line) => line.replace(/\r$/, ""))
@@ -66688,7 +66974,7 @@ async function runToolchainInventory(deps, signal) {
         throw new Error("scan aborted");
     }
     if (result.code !== 0) {
-        const detail = lastNonEmptyLine$1(result.stderr) || lastNonEmptyLine$1(result.stdout);
+        const detail = lastNonEmptyLine$2(result.stderr) || lastNonEmptyLine$2(result.stdout);
         throw new Error(`Get-ToolchainInventory.ps1 exited ${result.code}: ${detail}`);
     }
     const resultKind = classifyResult(result.stdout);
@@ -66932,7 +67218,7 @@ const PREREQ_TABLE = [
     },
 ];
 
-const VERSION_TIMEOUT_MS = 15_000;
+const VERSION_TIMEOUT_MS$1 = 15_000;
 function firstNonEmptyLine(text) {
     const lines = text
         .split(/\r?\n/)
@@ -66940,7 +67226,7 @@ function firstNonEmptyLine(text) {
         .filter((l) => l !== "");
     return lines[0] ?? "";
 }
-function lastNonEmptyLine(...texts) {
+function lastNonEmptyLine$1(...texts) {
     const lines = texts
         .join("\n")
         .split(/\r?\n/)
@@ -66969,7 +67255,7 @@ async function verdictForFound(entry, deps, refreshedEnv, foundPath, onPath) {
         return { ...base, status: "ok", path: foundPath, version: "", detail: "" };
     }
     const versionResult = await deps.run(foundPath, ["--version"], {
-        timeoutMs: VERSION_TIMEOUT_MS,
+        timeoutMs: VERSION_TIMEOUT_MS$1,
         env: refreshedEnv,
     });
     if (versionResult.timedOut) {
@@ -66987,17 +67273,17 @@ async function verdictForFound(entry, deps, refreshedEnv, foundPath, onPath) {
             status: "broken",
             path: foundPath,
             version: "",
-            detail: lastNonEmptyLine(versionResult.stdout, versionResult.stderr),
+            detail: lastNonEmptyLine$1(versionResult.stdout, versionResult.stderr),
         };
     }
     const version = firstNonEmptyLine(versionResult.stdout);
     if (entry.cmd === "gh") {
         const authResult = await deps.run(foundPath, ["auth", "status"], {
-            timeoutMs: VERSION_TIMEOUT_MS,
+            timeoutMs: VERSION_TIMEOUT_MS$1,
             env: refreshedEnv,
         });
         if (authResult.code !== 0) {
-            const stderrLine = lastNonEmptyLine(authResult.stderr);
+            const stderrLine = lastNonEmptyLine$1(authResult.stderr);
             return {
                 ...base,
                 status: "unauthenticated",
@@ -67739,7 +68025,7 @@ const MAX_TOTAL_DECODED_BYTES = 48 * 1024 * 1024;
 // body-too-large 413 first, never reaching (and never able to report) the more specific decoded-total
 // 400 below. +2 MB of headroom comfortably covers realistic JSON structure for up to MAX_FILES
 // entries (tens of KB in practice) so both checks are independently reachable.
-const MAX_REQUEST_BODY_BYTES = 66 * 1024 * 1024;
+const MAX_REQUEST_BODY_BYTES$1 = 66 * 1024 * 1024;
 const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 /** `Buffer.from(s, "base64")` is lenient -- it silently drops characters outside the base64 alphabet
  *  rather than throwing, so "does it decode" needs its own check, not a try/catch around the decode. */
@@ -67796,7 +68082,7 @@ function registerPublishVerb(registry, deps) {
         path: "/publish/mirror",
         middleware: [
             bodyLimit({
-                maxSize: MAX_REQUEST_BODY_BYTES,
+                maxSize: MAX_REQUEST_BODY_BYTES$1,
                 onError: (c) => c.json({ ok: false, error: "request body too large" }, 413),
             }),
         ],
@@ -75256,6 +75542,568 @@ var tunnel = /*#__PURE__*/Object.freeze({
   registerTunnelVerb: registerTunnelVerb
 });
 
+/**
+ * `POST /v1/toolchain/upgrade`, `GET /v1/toolchain/upgrade/:jobId`, `GET /v1/toolchain/upgrade/:jobId/events`
+ * (#675, PR 1 of 2), capability `agent.toolchain.upgrade`: the agent installs software on the machine it
+ * runs on, so this is the one verb whose request is a security surface. The design (roshne's decisions on
+ * #675, 2026-10-05):
+ *
+ * - TWO gates, both required. The console's grant (the registry's guard, in front of every handler here) and
+ *   the machine owner's own opt-in, `toolchain_upgrade = true` in this machine's `agent.toml`
+ *   (`deps.enabled`, the config the agent loaded at start), the first middleware after the grant guard, so
+ *   a machine that has not opted in does no work at all for a request: not even its body is limited or read.
+ *   The POST's body is then capped at `MAX_REQUEST_BODY_BYTES` before it is read.
+ * - FIXED COMMAND SHAPES, never free text. `commandFor` is the only place an upgrade argv is built, from
+ *   three literal shapes and one validated id. Every field is checked against a grammar before anything
+ *   spawns; a request that does not match is a `400` naming the field. A valid id can still name a package
+ *   the operator did not mean (the console decides which one), which is the accepted worst case. The one
+ *   other program the request can name is `cmd`, and only to read its version: it must be one of the tools
+ *   the agent's own preflight already runs `--version` on (`VERSION_READABLE_CMDS`), never an executable of
+ *   the request's choosing.
+ * - NO ELEVATION in the agent: it never tries to elevate itself. Linux needs a sudoers rule for the agent's
+ *   user (`needs-sudoers`). On Windows the agent is a limited logon task: winget answers `0x8A150019` when
+ *   the command itself needs administrator rights (`needs-elevation`, with the command to paste into an
+ *   elevated window). An installer that elevates itself through UAC may instead put a prompt on the user's
+ *   desktop, which the agent cannot answer (not verified here; see the README).
+ * - One upgrade at a time, as a job with streamed output (apt and winget outlast the host client's 30 s
+ *   body budget), a 15-minute timeout and a 1 MiB output cap, both enforced by `spawnJob`.
+ * - AUDIT: two log lines per run. One when the job starts (tool, manager, id, `cmd`), so a run the agent does
+ *   not survive still leaves a record; one when it ends (tool, manager, id, before, after, outcome, exit
+ *   code, `cmd`). The console-supplied `tool` is printed in quotes, and its grammar has no quote.
+ */
+const UPGRADE_CAPABILITY = "agent.toolchain.upgrade";
+const KIND = "toolchain-upgrade";
+/** 15 minutes: a large winget installer is the slow case; past this it is hung, and is killed. */
+const UPGRADE_TIMEOUT_MS = 15 * 60_000;
+/** 1 MiB of logged output: a runaway installer must not fill the agent's memory with log lines. */
+const UPGRADE_MAX_OUTPUT_CHARS = 1_048_576;
+const VERSION_TIMEOUT_MS = 20_000;
+/** After the upgrade command has exited, how long its output may stay open (a descendant it left running
+ *  can hold the pipes) before the job is finished with the command's real exit code anyway. */
+const EXIT_SETTLE_MS = 5_000;
+/** The most bytes of request body the POST reads: the largest valid body is a few hundred, so a granted
+ *  console cannot make the agent buffer an unbounded one. */
+const MAX_REQUEST_BODY_BYTES = 4096;
+const MAX_CONCURRENT_UPGRADES = 1;
+/** Finished jobs' outcomes kept for the status route (the job registry itself keeps 200 finished jobs). */
+const MAX_REMEMBERED_OUTCOMES = 200;
+const MAX_REASON_CHARS = 300;
+const NOT_OPTED_IN_ERROR = "toolchain upgrades are not enabled on this machine (agent.toml toolchain_upgrade)";
+const MANAGERS = ["winget", "apt", "native"];
+// The tool key lands in a job label and, in quotes, in the audit lines, so it is words and a little
+// punctuation: no quote, ":", "(", ")", ">" or ",", the characters that would let one run's line imitate
+// another's outcome. Spaces stay (the standard's keys have them: "GitHub CLI").
+const TOOL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,63}$/;
+/** The commands whose `--version` this verb may run: the agent's own preflight table, minus the one entry
+ *  the preflight itself never executes (a Chromium-family `--version` can open a window, E4 §5 decision
+ *  19). The Environment panel sends the `cmd` of a preflight row, so these are the only values it ever
+ *  sends; anything else is a request to run a program of the console's choosing. */
+const VERSION_READABLE_CMDS = PREREQ_TABLE.map((entry) => entry.cmd).filter((cmd) => cmd !== "chromium");
+// winget: a `Publisher.Name` id (`Git.Git`, `Microsoft.PowerShell`); must start alphanumeric, so it can
+// never be read as an option, and must contain a ".".
+const WINGET_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,127}$/;
+// apt: the Debian package-name grammar (2+ characters, lowercase letters, digits, "+", "-", ".").
+const APT_PACKAGE_PATTERN = /^[a-z0-9][a-z0-9+.-]{1,127}$/;
+const NATIVE_ID = "claude";
+function isManager(value) {
+    return typeof value === "string" && MANAGERS.includes(value);
+}
+function refuse$1(error) {
+    return { ok: false, error };
+}
+/** The pure half of the request check: every refusal names its field, and no process is started on a
+ *  refusal. `platform` decides which managers exist on this machine. A field is read only when it is the
+ *  body's OWN property, so a body cannot reach an inherited one. */
+function validateUpgradeRequest(body, platform) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return refuse$1("invalid JSON body");
+    }
+    const field = (name) => Object.hasOwn(body, name) ? body[name] : undefined;
+    const tool = field("tool");
+    if (typeof tool !== "string" || tool === "")
+        return refuse$1("tool: must be a non-empty string");
+    if (!TOOL_PATTERN.test(tool)) {
+        return refuse$1("tool: must be 1 to 64 letters, digits, spaces or . _ + - (starting with a letter or digit)");
+    }
+    const cmd = field("cmd");
+    if (typeof cmd !== "string" || cmd === "")
+        return refuse$1("cmd: must be a non-empty string");
+    // An allowlist, not a grammar: only the preflight's own executed tools pass, so no name, path or
+    // separator that is not one of them can reach `which`.
+    if (!VERSION_READABLE_CMDS.includes(cmd)) {
+        return refuse$1(`cmd: not a tool this agent reads the version of (${VERSION_READABLE_CMDS.join(", ")})`);
+    }
+    const manager = field("manager");
+    if (!isManager(manager))
+        return refuse$1(`manager: must be one of ${MANAGERS.join(", ")}`);
+    if (manager === "winget" && platform !== "win32") {
+        return refuse$1("manager: winget is only available on win32 machines");
+    }
+    if (manager === "apt" && platform !== "linux") {
+        return refuse$1("manager: apt is only available on linux machines");
+    }
+    const packageId = field("packageId");
+    if (typeof packageId !== "string" || packageId === "") {
+        return refuse$1("packageId: must be a non-empty string");
+    }
+    if (manager === "winget") {
+        if (!WINGET_ID_PATTERN.test(packageId)) {
+            return refuse$1("packageId: not a winget package id (letters, digits and . + _ -, starting with a letter or digit)");
+        }
+        if (!packageId.includes(".")) {
+            return refuse$1('packageId: a winget package id has the form Publisher.Name (it needs a ".")');
+        }
+    }
+    else if (manager === "apt") {
+        if (!APT_PACKAGE_PATTERN.test(packageId)) {
+            return refuse$1("packageId: not a Debian package name (lowercase letters, digits, + - ., 2 to 128 characters)");
+        }
+        // apt-get reads a trailing "-" on a package argument as "remove this package".
+        if (packageId.endsWith("-")) {
+            return refuse$1('packageId: a trailing "-" would make apt-get remove the package');
+        }
+    }
+    else {
+        if (packageId !== NATIVE_ID)
+            return refuse$1(`packageId: the native installer only knows "${NATIVE_ID}"`);
+        if (cmd !== NATIVE_ID)
+            return refuse$1(`cmd: a native upgrade runs the "${NATIVE_ID}" binary`);
+    }
+    return { ok: true, value: { tool, cmd, manager, packageId } };
+}
+// ---- the command ---------------------------------------------------------------------------------
+/** The three literal command shapes (the only argv this verb ever builds). `executablePath` is the
+ *  resolved `winget`, `sudo` or `claude`; `packageId` was validated by `validateUpgradeRequest`. */
+function commandFor(manager, packageId, executablePath) {
+    switch (manager) {
+        case "winget":
+            return [
+                executablePath,
+                "upgrade",
+                "--id",
+                packageId,
+                "--exact",
+                "--silent",
+                "--accept-package-agreements",
+                "--accept-source-agreements",
+                "--disable-interactivity",
+            ];
+        case "apt":
+            // --no-remove (apt-get(8): "If any packages are to be removed apt-get immediately aborts"): with -y
+            // alone a package whose new version Conflicts with or Breaks another installed package removes that
+            // one without asking. After `-y`, so the sudoers rule's trailing `*` still matches.
+            return [
+                executablePath,
+                "-n",
+                "apt-get",
+                "install",
+                "--only-upgrade",
+                "-y",
+                "--no-remove",
+                packageId,
+            ];
+        case "native":
+            return [executablePath, "update"];
+    }
+}
+/** The command as an operator would type it: the executable by name, not by the path this agent found. */
+function typedCommand(manager, packageId) {
+    const [exe, ...args] = commandFor(manager, packageId, "winget");
+    return [exe, ...args].join(" ");
+}
+// winget's documented return codes (microsoft/winget-cli `doc/windows/package-manager/winget/returnCodes.md`,
+// generated by `winget error`), pinned by number. Node reports a Windows exit code as unsigned; `>>> 0`
+// below makes a signed one compare the same.
+const WINGET_COMMAND_REQUIRES_ADMIN = 0x8a150019;
+const WINGET_UPDATE_NOT_APPLICABLE = 0x8a15002b;
+const WINGET_NO_APPLICATIONS_FOUND = 0x8a150014;
+// sudo's own wording when `-n` cannot proceed for want of a rule: sudo 1.9 (sudoers' logging.c, sudo(8)),
+// then sudo-rs, the default `sudo` of recent Ubuntu (strings read from the 0.2.13 binary on Ubuntu 26.04: "interactive
+// authentication is required", "I'm sorry <user>. I'm afraid I can't do that", "Sorry, user <u> may not
+// run <command> on <host>", "... is not allowed to execute '<command>' as <u> on <host>").
+const SUDO_REFUSALS = [
+    /sudo: a password is required/i,
+    /is not in the sudoers file/i,
+    /is not allowed to execute/i,
+    /is not allowed to run sudo on/i,
+    /interactive authentication is required/i,
+    /I'm afraid I can't do that/i,
+    // "Sorry, user <u> may not run sudo on <host>" (sudo 1.9) and "... may not run <command> on <host>" (sudo-rs)
+    /user \S+ may not run .+ on /i,
+];
+function sudoersRule(username) {
+    return `${username} ALL=(root) NOPASSWD: /usr/bin/apt-get install --only-upgrade -y *`;
+}
+/** Printable ASCII only, and bounded: this text ends up in a job log, a status body and an audit line. */
+function printable(text, max) {
+    return text.replace(/[^\x20-\x7e]/g, "?").slice(0, max);
+}
+function lastNonEmptyLine(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    return printable(lines.at(-1) ?? "", MAX_REASON_CHARS);
+}
+function classifyOutcome(input) {
+    if (input.limit === "timeout") {
+        return {
+            status: "timed-out",
+            reason: `killed after ${UPGRADE_TIMEOUT_MS / 60_000} minutes; the package may be half-installed, check it before retrying`,
+        };
+    }
+    if (input.limit === "output-cap") {
+        return {
+            status: "failed",
+            reason: `output passed ${UPGRADE_MAX_OUTPUT_CHARS} characters; the rest was dropped`,
+        };
+    }
+    if (input.exitCode === null) {
+        return {
+            status: "failed",
+            reason: lastNonEmptyLine(input.output) ||
+                "the command ended without an exit code (killed by a signal, or it could not be started)",
+        };
+    }
+    const code = input.exitCode >>> 0;
+    if (input.manager === "winget") {
+        if (code === WINGET_COMMAND_REQUIRES_ADMIN) {
+            return {
+                status: "needs-elevation",
+                reason: `this package needs administrator rights; run in an elevated terminal: ${typedCommand("winget", input.packageId)}`,
+            };
+        }
+        if (code === WINGET_UPDATE_NOT_APPLICABLE) {
+            return {
+                status: "already-current",
+                reason: "winget reports no applicable update (no newer version this machine can install)",
+            };
+        }
+        if (code === WINGET_NO_APPLICATIONS_FOUND) {
+            return { status: "failed", reason: "winget found no installed package with that id" };
+        }
+    }
+    if (code !== 0) {
+        if (input.manager === "apt" && SUDO_REFUSALS.some((pattern) => pattern.test(input.output))) {
+            return {
+                status: "needs-sudoers",
+                reason: `sudo refused: add a sudoers rule for this agent's user: ${sudoersRule(input.username)} (that rule lets any process of that user become root without a password; see the agent README, Operator setup)`,
+            };
+        }
+        return { status: "failed", reason: lastNonEmptyLine(input.output) || `exit ${code}` };
+    }
+    // Exit 0: what changed decides it.
+    if (input.after === "missing") {
+        return {
+            status: "failed",
+            reason: "the command succeeded but the tool's version cannot be read afterwards",
+        };
+    }
+    const aptUpgraded = input.manager === "apt" && Number(/(\d+) upgraded,/.exec(input.output)?.[1] ?? "0") > 0;
+    if (input.after !== input.before || aptUpgraded)
+        return { status: "upgraded" };
+    return { status: "already-current" };
+}
+/** The lines `spawnJob` writes to the job log about the command rather than from it, from a forced finish
+ *  (the `[timed out` and `[output capped` ones never matter here: a limit decides the outcome before the
+ *  captured text is read). `[spawn failed] <message>` is not among them on purpose: with no output at all,
+ *  it IS the reason the run failed. */
+const SPAWN_DIAGNOSTIC = /^\[(?:killed, but its output never closed|the command exited, but its output never closed)/;
+// dpkg-query's own format syntax (a status column, a tab, the package name): not a template literal.
+// biome-ignore lint/suspicious/noTemplateCurlyInString: ${...} is dpkg-query's format syntax
+const DPKG_SHOWFORMAT = "--showformat=${db:Status-Abbrev}\t${Package}\n";
+function notFoundError(name, found) {
+    if (!found.found && found.reason === "shim") {
+        return `${name} is a .cmd shim; install the native binary`;
+    }
+    return `${name} not found on PATH`;
+}
+/** The most `<exe> --version` output a version read collects (`RunOptions.maxOutputLength`). */
+const VERSION_MAX_OUTPUT = 65_536;
+const VERSION_DEADLINE_MS = VERSION_TIMEOUT_MS + 5_000;
+/** First non-empty line of `<exe> --version`, or `missing` when it cannot be run, exits non-zero, prints
+ *  nothing, or has not answered by `deadlineMs` (the read's own timeout kills the child, but its `close`
+ *  event waits for every holder of the pipes, which a child's own descendant could hold open). */
+async function readVersion(run, exe, env, deadlineMs) {
+    let deadline;
+    try {
+        const result = await Promise.race([
+            run(exe, ["--version"], {
+                timeoutMs: VERSION_TIMEOUT_MS,
+                env,
+                maxOutputLength: VERSION_MAX_OUTPUT,
+            }),
+            new Promise((resolve) => {
+                deadline = setTimeout(() => resolve(null), deadlineMs);
+            }),
+        ]);
+        if (result === null || result.timedOut || result.code !== 0)
+            return "missing";
+        const first = result.stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find((line) => line !== "");
+        return first === undefined ? "missing" : printable(first, 200);
+    }
+    catch {
+        return "missing";
+    }
+    finally {
+        if (deadline !== undefined)
+            clearTimeout(deadline);
+    }
+}
+function registerToolchainUpgradeVerb(registry, deps) {
+    const spawnJob$1 = deps.spawnJob ?? spawnJob;
+    const versionDeadlineMs = deps.versionDeadlineMs ?? VERSION_DEADLINE_MS;
+    /** A log line is a record, never a dependency: a logger that throws (a full disk) must not fail a
+     *  request that has already created a job, nor reject the unawaited `finalize`. */
+    const logEvent = (message) => {
+        try {
+            deps.logEvent(message);
+        }
+        catch {
+            // nothing else to do with it
+        }
+    };
+    const outcomes = new Map();
+    // Upgrades between the cap check and `jobs.start`: the awaits in between (PATH refresh, version read)
+    // would otherwise let two concurrent requests both see "none running".
+    let starting = 0;
+    function remember(jobId, outcome) {
+        outcomes.set(jobId, outcome);
+        if (outcomes.size > MAX_REMEMBERED_OUTCOMES) {
+            const oldest = outcomes.keys().next().value;
+            if (oldest !== undefined)
+                outcomes.delete(oldest);
+        }
+    }
+    // Gate 2: the machine owner's opt-in. A middleware, so it runs right after the grant guard and before
+    // anything reads (or even size-limits) the body.
+    const optInGate = async (c, next) => {
+        if (!deps.enabled()) {
+            return c.json({ ok: false, error: NOT_OPTED_IN_ERROR, reason: "not-opted-in" }, 403);
+        }
+        await next();
+    };
+    registry.register({
+        capability: UPGRADE_CAPABILITY,
+        method: "POST",
+        path: "/toolchain/upgrade",
+        middleware: [
+            optInGate,
+            bodyLimit({
+                maxSize: MAX_REQUEST_BODY_BYTES,
+                onError: (c) => c.json({ ok: false, error: "request body too large" }, 413),
+            }),
+        ],
+        handler: async (c) => {
+            let body;
+            try {
+                body = await c.req.json();
+            }
+            catch {
+                return c.json({ ok: false, error: "invalid JSON body" }, 400);
+            }
+            const validated = validateUpgradeRequest(body, deps.platform);
+            if (!validated.ok)
+                return c.json({ ok: false, error: validated.error }, 400);
+            const request = validated.value;
+            if (deps.jobs.runningCount(KIND) + starting >= MAX_CONCURRENT_UPGRADES) {
+                return c.json({ ok: false, error: "an upgrade is already running on this machine" }, 429);
+            }
+            starting++;
+            try {
+                const env = { PATH: await deps.searchPath() };
+                // The program that performs the upgrade: winget, sudo (for apt-get) or the native claude.
+                const executableName = request.manager === "winget" ? "winget" : request.manager === "apt" ? "sudo" : "claude";
+                const executable = deps.which(executableName, env);
+                if (!executable.found) {
+                    return c.json({ ok: false, error: notFoundError(executableName, executable) }, 502);
+                }
+                // The tool whose version is read before and after.
+                const target = deps.which(request.cmd, env);
+                if (!target.found) {
+                    return c.json({ ok: false, error: notFoundError(request.cmd, target) }, 502);
+                }
+                const before = await readVersion(deps.run, target.path, env, versionDeadlineMs);
+                // apt-get falls back to treating a package argument that matches nothing as a regular expression
+                // (apt-get(8): "a POSIX regular expression ... applied to all package names"), which with
+                // --only-upgrade would upgrade every installed package it matches. So the name must be an
+                // installed package, exactly: dpkg-query takes the name literally (the grammar has no wildcard).
+                // Asked LAST, straight before the spawn: the version read above can take up to 25 s, and a package
+                // purged in that window would otherwise reach apt-get as the pattern it falls back to.
+                if (request.manager === "apt") {
+                    const dpkgQuery = deps.which("dpkg-query", env);
+                    if (!dpkgQuery.found) {
+                        return c.json({ ok: false, error: notFoundError("dpkg-query", dpkgQuery) }, 502);
+                    }
+                    const query = await deps.run(dpkgQuery.path, ["--show", DPKG_SHOWFORMAT, "--", request.packageId], { timeoutMs: VERSION_TIMEOUT_MS, env, maxOutputLength: VERSION_MAX_OUTPUT });
+                    const installed = query.code === 0 &&
+                        query.stdout.split("\n").some((line) => {
+                            const [status, name] = line.replace(/\r$/, "").split("\t");
+                            // dpkg's status column is desired-state, current-state, error flag: "ii " is installed, "hi "
+                            // is installed and held. The current state ("i") is what makes it installed.
+                            return status?.[1] === "i" && name === request.packageId;
+                        });
+                    if (!installed) {
+                        return c.json({ ok: false, error: `packageId: ${request.packageId} is not an installed package` }, 400);
+                    }
+                }
+                const argv = commandFor(request.manager, request.packageId, executable.path);
+                const handle = deps.jobs.start({
+                    kind: KIND,
+                    label: `${request.tool} via ${request.manager} ${request.packageId}`,
+                    repo: request.manager,
+                    permissionMode: "",
+                });
+                // A line at the START as well as the end: a run the agent does not survive (a restart, a crash)
+                // otherwise leaves no record of what it was upgrading.
+                logEvent(`toolchain upgrade started: ${JSON.stringify(request.tool)} via ${request.manager} ${request.packageId} (version of ${request.cmd})`);
+                // What the child printed, for the outcome: the last lines only, and never the job's own header.
+                const captured = [];
+                let sawHeader = false;
+                let limit;
+                const finalize = async (exitCode) => {
+                    let outcome;
+                    try {
+                        const afterEnv = { PATH: await deps.searchPath() };
+                        const afterTarget = deps.which(request.cmd, afterEnv);
+                        const after = afterTarget.found
+                            ? await readVersion(deps.run, afterTarget.path, afterEnv, versionDeadlineMs)
+                            : "missing";
+                        const verdict = classifyOutcome({
+                            manager: request.manager,
+                            packageId: request.packageId,
+                            exitCode,
+                            output: captured.join("\n"),
+                            before,
+                            after,
+                            limit,
+                            username: deps.username(),
+                        });
+                        outcome = { ...verdict, before, after };
+                    }
+                    catch (err) {
+                        const message = printable(err instanceof Error ? err.message : String(err), MAX_REASON_CHARS);
+                        outcome = { status: "failed", reason: message, before, after: "missing" };
+                    }
+                    const ok = outcome.status === "upgraded" || outcome.status === "already-current";
+                    try {
+                        // The outcome and the audit line first, then the job-log trailer: a job log that fails to take
+                        // a line (the only one of these that can throw) must not cost the console its outcome or the
+                        // operator the audit line.
+                        remember(handle.id, outcome);
+                        // `cmd` is named because the verb does not tie it to the package id: the versions are of `cmd`.
+                        logEvent(`toolchain upgrade: ${JSON.stringify(request.tool)} via ${request.manager} ${request.packageId}: ${before} -> ${outcome.after} (${outcome.status}, exit ${exitCode ?? "none"}, version of ${request.cmd})`);
+                        handle.log(`after: ${outcome.after}`);
+                        handle.log(`result: ${outcome.status}${outcome.reason ? ` (${outcome.reason})` : ""}`);
+                    }
+                    catch {
+                        // A logging failure must neither stop the job finishing nor become an unhandled rejection
+                        // (`finalize` runs unawaited, and an unhandled rejection ends the agent process).
+                    }
+                    finally {
+                        // Always: a job that never finishes would hold the one upgrade slot for good.
+                        handle.finish(ok ? "done" : "failed", exitCode);
+                    }
+                };
+                // The child's output flows to the job; `finish` is held back until the outcome (and its trailer
+                // lines) is known, then called once.
+                const spawnHandle = {
+                    log: (line) => {
+                        handle.log(line);
+                        if (!sawHeader) {
+                            sawHeader = true;
+                            return;
+                        }
+                        // spawnJob's own diagnostics are not the command's words: the reason a failed run reports is
+                        // the last thing the COMMAND said, which a forced finish's note must not replace.
+                        if (SPAWN_DIAGNOSTIC.test(line))
+                            return;
+                        captured.push(line);
+                        if (captured.length > 400)
+                            captured.shift();
+                    },
+                    finish: (_status, exitCode) => {
+                        void finalize(exitCode);
+                    },
+                };
+                try {
+                    spawnJob$1(argv, {
+                        cwd: deps.cwd(),
+                        env: {
+                            NO_COLOR: "1",
+                            ...(request.manager === "apt"
+                                ? { DEBIAN_FRONTEND: "noninteractive", LC_ALL: "C" }
+                                : {}),
+                        },
+                        header: `$ ${argv.join(" ")}`,
+                        timeoutMs: UPGRADE_TIMEOUT_MS,
+                        maxOutputChars: UPGRADE_MAX_OUTPUT_CHARS,
+                        exitSettleMs: EXIT_SETTLE_MS,
+                        onLimit: (which) => {
+                            limit = which;
+                        },
+                    }, spawnHandle);
+                }
+                catch (err) {
+                    // A launch that throws before any child exists must not leave a job "running" for good.
+                    handle.log(`[spawn failed] ${printable(err instanceof Error ? err.message : String(err), MAX_REASON_CHARS)}`);
+                    handle.finish("failed", null);
+                    throw err;
+                }
+                // spawnJob logs the header synchronously; the child's own output arrives later.
+                handle.log(`before: ${before}`);
+                return c.json({ ok: true, jobId: handle.id }, 202);
+            }
+            catch (err) {
+                logEvent(`toolchain upgrade: request failed: ${printable(err instanceof Error ? err.message : String(err), MAX_REASON_CHARS)}`);
+                return c.json({ ok: false, error: "the upgrade could not be started" }, 500);
+            }
+            finally {
+                starting--;
+            }
+        },
+    });
+    registry.register({
+        capability: UPGRADE_CAPABILITY,
+        method: "GET",
+        path: "/toolchain/upgrade/:jobId",
+        handler: async (c) => {
+            const jobId = c.req.param("jobId") ?? "";
+            const entry = deps.jobs.get(jobId);
+            // Another kind's job is "no such job" here, exactly like an unknown id.
+            if (!entry || entry.view.kind !== KIND)
+                return c.json({ ok: false, error: "no such job" }, 404);
+            const outcome = outcomes.get(jobId);
+            return c.json({ ok: true, job: entry.view, ...(outcome !== undefined ? { outcome } : {}) });
+        },
+    });
+    registry.register({
+        capability: UPGRADE_CAPABILITY,
+        method: "GET",
+        path: "/toolchain/upgrade/:jobId/events",
+        handler: async (c) => jobEventsResponse(deps.jobs, c.req.param("jobId") ?? "", c, KIND),
+    });
+    return { pendingStarts: () => starting };
+}
+
+var toolchainUpgrade = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  MAX_REQUEST_BODY_BYTES: MAX_REQUEST_BODY_BYTES,
+  NOT_OPTED_IN_ERROR: NOT_OPTED_IN_ERROR,
+  UPGRADE_CAPABILITY: UPGRADE_CAPABILITY,
+  UPGRADE_MAX_OUTPUT_CHARS: UPGRADE_MAX_OUTPUT_CHARS,
+  UPGRADE_TIMEOUT_MS: UPGRADE_TIMEOUT_MS,
+  VERSION_READABLE_CMDS: VERSION_READABLE_CMDS,
+  classifyOutcome: classifyOutcome,
+  commandFor: commandFor,
+  registerToolchainUpgradeVerb: registerToolchainUpgradeVerb,
+  sudoersRule: sudoersRule,
+  validateUpgradeRequest: validateUpgradeRequest
+});
+
 /**
  * #659 PR 2: where an update comes from and what is allowed. The agent installs only an exact
  * published version of `@rackbops/ac-agent` from the public npm registry -- never a URL, a tarball
@@ -75688,4 +76536,4 @@ var updater = /*#__PURE__*/Object.freeze({
   selfUpdateSupported: selfUpdateSupported
 });
 
-export { AGENT_API_VERSION, buildRepoFs, buildWhichFs, dispatch, healthResultFrom, isEntryPoint, main, realExists };
+export { AGENT_API_VERSION, buildRepoFs, buildWhichFs, dispatch, healthResultFrom, isEntryPoint, main, realExists, runningJobCount, toolchainUpgradeDeps };