@rackbops/ac-agent 2.0.0-alpha.55 → 2.0.0-alpha.57

package/README.md

@@ -10,8 +10,8 @@ one-time code exchanged for a per-machine token, #48), `repos` list/status/pull
 as are the OneDrive mirror (`publish/mirror`, #53) and the tunnel-config lint (`tunnel/lint`, #416).
 Every verb also
 requires a per-plugin capability grant, pushed by the console and enforced here (#50) -- see
-**Verbs** and **Security model** below. `GET /v1/preflight` (#55) -- git/gh/node/claude executed,
-chromium only resolved -- is control plane, not a verb; see **Preflight**.
+**Verbs** and **Security model** below. `GET /v1/preflight` (#55) -- git/gh/node/claude and (#828)
+docker/cloudflared executed, chromium only resolved -- is control plane, not a verb; see **Preflight**.
 
 ## Install
 
@@ -27,6 +27,26 @@ resolves to the newest release. Two older tags are frozen: `alpha` (the very fir
 `2.0.0-alpha.40`. Nothing moves either any more, and the maintainer removes or moves them by hand.
 `latest` is expected to go back to stable-only once the first stable `2.0.0` ships.
 
+**Node 26 or newer** (`engines.node: ">=26"`, #827), the fleet's one Node line and the console image's
+major. `npx` treats `engines` only as a warning, so the agent checks for itself before any verb: on an
+older Node every verb (`install`, `status`, `stop` and `uninstall` included) does nothing and exits 2,
+its stderr ending with the line `ac-agent requires Node >=26, found <version>`. On Ubuntu, the
+distribution's own `nodejs` is older; Node 26 comes from NodeSource's `node_26.x` apt repository
+(`https://deb.nodesource.com/node_26.x`).
+
+Move a machine's Node to 26 **before** its agent updates to a release that carries this floor. The
+console's update (`POST /v1/update`, below) checks the staged bundle by running its `version --json`
+with the agent's own Node, so on an older Node the update is refused (422, naming that line) and the
+running agent stays as it was. A plain `npx @rackbops/ac-agent install` on an older Node is refused the
+same way, before anything is copied or registered.
+
+- **The installed task or unit keeps the Node `install` ran under**, as an absolute path
+  (`process.execPath`). An apt or MSI upgrade in place moves that Node with it. A version manager
+  (fnm, nvm, volta) does not: after switching it to 26, run `install` again under 26, or the agent
+  keeps running the old Node and its updates are refused with that line.
+- **To stop or uninstall from a machine still below 26**, run a release from before the floor, e.g.
+  `npx @rackbops/ac-agent@2.0.0-alpha.55 stop`, or move the machine's Node first.
+
 ### Upgrade with the Tooling script
 
 For an existing install, an up-to-date Tooling checkout provides
@@ -61,8 +81,9 @@ tarball, and reads target health, but runs no install, `scp`, or mutating SSH co
 Run Windows `-Local` from a [normal PowerShell window](#run-install-from-a-normal-shell). Every
 Windows machine runs `-Local` for itself; remote Windows installation is unsupported. `gh` must have
 access to the release repository. Linux targets need working noninteractive SSH and `node`/`npx` on
-their `PATH`. `-Port` changes only the health-check port (default `8788`); it does not reconfigure the
-agent.
+their `PATH`; the target's own Node runs the new bundle, so a release that carries the Node 26 floor
+needs Node 26 there too (see above). `-Port` changes only the health-check port (default `8788`); it
+does not reconfigure the agent.
 
 ### Linux: no special `npx` spelling needed (#278)
 
@@ -416,10 +437,24 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   `owner/name` resolved from its `origin` remote (`git remote get-url origin`, parsed the way 1.x's
   `init_config.py:parse_remote` does), or `null` when there's no remote or it isn't a GitHub-shaped
   URL — never an error. This makes the route spawn one `git remote get-url` per repo (parallelized),
-  so it is no longer git-free the way it was before #304.
+  so it is no longer git-free the way it was before #304. **All three repo routes need git**: they
+  look for it first (see below), and a machine without it answers
+  `502 {ok: false, error: "git not found on PATH"}` (or, when PATH holds only a `.cmd`/`.bat` shim,
+  `git is a .cmd shim; install the native binary`) before any repo work, a bad `:name` included.
 - **`GET /v1/repos/:name/status`** (`agent.git.read`) → `{ok, name, path, ownerName, branch,
   defaultBranch, upstream, ahead, behind, dirty, inProgress}` (`ownerName` as above), read-only (no
   fetch — `pull` is what refreshes the refs `status` reads).
+- **git is run by absolute path** (#699). Each of the three requests resolves git once, on the
+  refreshed PATH (the registry's on Windows, the process PATH elsewhere: the search the preflight and
+  the toolchain upgrade use), and every git spawn of that request names the path it found, made
+  absolute if PATH gave a relative entry (`exec/claude` does the same for `claude`, the other spawn
+  whose working directory a request chooses). This matters on Windows, where a bare `git` is looked for in the
+  spawn's working directory first (`git.com`, then `git.exe`), and every call here has a repo checkout
+  as its working directory: a `git.exe` that a clone, a branch or a fast-forward put in the repo's root
+  would otherwise run as the agent's user, unattended (the daily `repo.pull` job reaches it). A bare
+  name is looked up on PATH only elsewhere, so Linux was not exposed to that; a relative PATH entry is
+  the one way a working directory could matter there, and the absolute path closes it too. See
+  **Security model** for the second, general layer.
 - **`POST /v1/repos/:name/pull`** (`agent.git.pull`), body `{dryRun?: boolean}` → `{ok: true, row}`
   where `row.status` is `updated | would | current | skipped | error` and `row.reason` names which
   of the six 1.x-derived guards applied (`dirty`, `branch`, `ahead`, `in-progress`, `no-upstream`,
@@ -429,7 +464,8 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   timeout.
 - **`:name` is an allowlist, not a path** — it must match a machine-generated repo name pattern, must
   not be `.`/`..`, and must actually be one of the entries `GET /v1/repos` would list; anything else
-  is `404 {"error": "no such repo"}` before any git call runs.
+  is `404 {"error": "no such repo"}` before any git call runs (on a machine with git: without it the
+  `502` above comes first).
 - **`POST /v1/open`** (`agent.desktop.open`), body `{url}` → `{ok: true}`. Only a `https:` or
   `claude:` URL is accepted (the console's own deep-link shape,
   `claude://code/new?q=<prompt>&folder=<path>`); anything else is `400` before any process spawns.
@@ -479,8 +515,8 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
     string. Tokens are a byte estimate (~4 chars/token; the payload says `estimated: true`); only
     sizes and line counts ever leave this scan -- file content is never read into the payload.
   - **`toolchain-inventory`** (#52, 52b; `timeoutMs: 600_000` -- about seventy version probes plus a
-    WSL probe) ships and runs 1.x's own `Get-ToolchainInventory.ps1` (vendored from 1.x `main` at `8e33836`
-    plus the six lines #673 added, `data/README.md`) through `pwsh -NoProfile -File <script> -OutFile <state>/scans/
+    WSL probe) ships and runs 1.x's own `Get-ToolchainInventory.ps1` (vendored byte for byte from 1.x
+    `main` at `5de373e`, `data/README.md`) through `pwsh -NoProfile -File <script> -OutFile <state>/scans/
     toolchain-inventory-<hostname>.md -NoRender`, with the child's `cwd` set to `<state>/scans` --
     **never a project directory**, since the script's own `pnpm --version` probe rewrites
     `pnpm-lock.yaml` in whatever directory it runs in. **Windows-only**: on any other platform this
@@ -773,7 +809,7 @@ anything starts; a request that fails is `400 {ok: false, error: "<field>: <why>
 | Field | Meaning | Must be |
 |---|---|---|
 | `tool` | the standard's tool key; the job's label and the audit lines only, never part of a command | `^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,63}$` (words, spaces allowed as in `GitHub CLI`: no `"`, `:`, `(`, `)`, `>` or `,`, and the audit lines print it in quotes, so one run's line cannot imitate another's outcome) |
-| `cmd` | the tool whose `--version` is read before and after; found with `which`, run for nothing else | one of **`git`, `gh`, `node`, `claude`**: the tools the agent's own preflight already runs `--version` on (`PREREQ_TABLE` minus `chromium`, which it never executes), which are the `cmd`s of the preflight rows the Environment panel sends. Any other name is `400 cmd: not a tool this agent reads the version of` |
+| `cmd` | the tool whose `--version` is read before and after; found with `which`, run for nothing else | one of **`git`, `gh`, `node`, `claude`** (`VERSION_READABLE_CMDS`, an explicit list): tools the agent's own preflight already runs `--version` on, which are the `cmd`s of the preflight rows the Environment panel sends. The preflight also executes `docker` and `cloudflared` (#828), but those rows are graded only: upgrading either can restart the host's containers or tunnels, so the verb refuses them with the error below (its wording predates #828), and adding a preflight row never widens this list. Any other name is `400 cmd: not a tool this agent reads the version of` |
 | `manager` | which package manager | `winget` (Windows only), `apt` (Linux only) or `native` |
 | `packageId` | the package | `winget`: `^[A-Za-z0-9][A-Za-z0-9.+_-]{0,127}$` with a `.` (a `Publisher.Name` id); `apt`: the Debian package-name grammar `^[a-z0-9][a-z0-9+.-]{1,127}$`, not ending in `-`; `native`: exactly `claude` (and `cmd` exactly `claude`) |
 
@@ -871,7 +907,7 @@ kind's jobs, and one holding only `agent.exec.claude` never reads these):
 | `already-current` | exit 0 and the version is unchanged; winget's `0x8A15002B` (no applicable update) also maps here, and means "no newer version this machine can install", which is not always the same as "current" | for the winget code |
 | `needs-sudoers` | `apt`: `sudo -n` refused, in sudo 1.9's wording (`a password is required`, `is not in the sudoers file`, `is not allowed to execute`, `is not allowed to run sudo on`, `user <u> may not run sudo on <host>`) or sudo-rs's, the default `sudo` of recent Ubuntu (`interactive authentication is required`, `I'm afraid I can't do that`, `user <u> may not run <command> on <host>`) | the sudoers rule to add, with what it grants |
 | `needs-elevation` | `winget`: its `0x8A150019` return code (command requires administrator privileges) | the command to paste into an elevated terminal |
-| `failed` | any other non-zero exit (the last output line, printable and cut at 300 characters), winget's `0x8A150014` (no installed package with that id), the output cap, a version that cannot be read after an exit 0, a command that could not start | what failed |
+| `failed` | any other non-zero exit (the last output line that is not closing advice such as `Or consider using native installation with: claude install`, printable and cut at 300 characters), winget's `0x8A150014` (no installed package with that id), the output cap, a version that cannot be read after an exit 0, a command that could not start | what failed |
 | `timed-out` | the 15-minute limit | check the package before retrying: it may be half-installed |
 
 The winget return codes are pinned by number from winget's own generated table
@@ -882,7 +918,7 @@ package, or an installer that elevates itself, when its caller is not elevated h
 here**: it may relaunch the installer through UAC, which puts a consent prompt on the logon user's
 desktop (the agent is a logon task in that session) that the agent cannot answer; the job then waits
 until it is answered or the 15-minute limit fires (`timed-out`), and a limited `taskkill` cannot end an
-elevated installer. Anything else an installer fails with is `failed`, with its last output line.
+elevated installer. Anything else an installer fails with is `failed`, with its last output line that is not closing advice.
 
 **Audit.** Two lines in the agent log per run: `toolchain upgrade started: "<tool>" via <manager>
 <packageId> (version of <cmd>)` when the job starts (so a run the agent does not survive is on record),
@@ -992,7 +1028,7 @@ no `X-AC-Plugin`/`X-AC-Grants-Revision` headers, and refuses a caller carrying `
 `403 {ok: false, error: "preflight is the console's, not a plugin's"}`. The console's own
 `POST /api/agents/:id/preflight` (`packages/host`) relays it into the Agents panel's Environment
 section. Live and stateless: nothing is cached on either side, and a call answers `200 {ok: true,
-machine, checkedAt, searchPath: "registry" | "process", rows}`, five rows always, in this order:
+machine, checkedAt, searchPath: "registry" | "process", rows}`, seven rows always, in this order:
 
 | `cmd` | required | executed | verdicts |
 |---|---|---|---|
@@ -1000,16 +1036,25 @@ machine, checkedAt, searchPath: "registry" | "process", rows}`, five rows always
 | `gh` | yes | `gh --version`, then `gh auth status` | `ok` \| `missing` \| `broken` \| `off-path` \| `unauthenticated` |
 | `node` | yes | `node --version` | `ok` \| `missing` \| `broken` \| `off-path` |
 | `claude` | yes | `claude --version` | `ok` \| `missing` \| `broken` \| `off-path` |
+| `docker` | no | `docker --version` | `ok` \| `missing` \| `broken` \| `off-path` |
+| `cloudflared` | no | `cloudflared --version` | `ok` \| `missing` \| `broken` \| `off-path` |
 | `chromium` | no | never | `ok` \| `missing` |
 
+The `docker` and `cloudflared` rows (#828) are two of the fleet standard's tools: the console host and
+the server stacks run in Docker, and cloudflared runs the tunnels that put them behind Cloudflare
+Access. Both are optional: a missing one is amber, never a failed preflight. The standard applies Docker
+to `linux-server` and `windows-dev` hosts and cloudflared to `linux-server` only, and the Environment
+panel grades them there, but never offers to upgrade them: `POST /v1/toolchain/upgrade` refuses both as
+a `cmd`.
+
 Each row is `{cmd, label, status, required, path, why, version, detail}` -- `version` the first
 non-empty line of `--version`'s stdout (CRLF handled), `""` otherwise; `detail` status-dependent
 free text (a `broken` row's last non-empty output line, `unauthenticated`'s
 `run gh auth login [-- <stderr line>]`, `off-path`'s `found under a version manager, not on PATH`),
 `""` when there is nothing to add.
 
-- **Executed, not just resolved.** `git`/`gh`/`node`/`claude` are resolved on the refreshed PATH
-  (below) AND run (`<exe> --version`, a **15 s** timeout per spawn); `gh` additionally runs
+- **Executed, not just resolved.** `git`/`gh`/`node`/`claude`/`docker`/`cloudflared` are resolved on
+  the refreshed PATH (below) AND run (`<exe> --version`, a **15 s** timeout per spawn); `gh` additionally runs
   `gh auth status` (needs the network -- offline it exits non-zero and the row reads
   `unauthenticated` with the stderr line saying why, since a real, validated token is what bullet 2
   wants, not merely a cached one `gh auth token` would report on regardless). `chromium` is
@@ -1024,7 +1069,7 @@ free text (a `broken` row's last non-empty output line, `unauthenticated`'s
   Linux the process PATH plus every version-manager bin directory (`fnm`/`nvm`/`volta`/`asdf`) is
   searched as a fallback, so a tool invisible to a bare `which` reads `off-path`, never `missing`.
   `searchPath` on the report names which: `"registry"` or `"process"`.
-- **The whole check answers in a few seconds.** Five rows run concurrently; the worst case is
+- **The whole check answers in a few seconds.** The seven rows run concurrently; the worst case is
   `gh`'s `--version` answering just under 15 s and then `auth status` timing out at 15 s too --
   under the console's own 100 s edge-request budget behind Cloudflare Access.
 
@@ -1113,9 +1158,31 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
   independent gates (the console's grant, and the machine owner's own `toolchain_upgrade` key in
   `agent.toml`, off by default), upgrades with only three fixed command shapes and a validated package
   id (the one other program a request can name, `cmd`, is limited to four tools whose `--version` the
-  preflight already runs), takes its elevation from the machine's own configuration rather than ever
+  preflight already runs: an explicit list, so the preflight's `docker` and `cloudflared` rows are not
+  among them), takes its elevation from the machine's own configuration rather than ever
   elevating itself, and logs every run. See **`POST /v1/toolchain/upgrade`**, including what the Linux
   sudoers rule it needs actually grants.
+- **The agent does not run an executable it finds in a request's working directory** (#699), in two
+  layers, neither of which replaces the other. (1) git (the repo verbs), `gh`, `claude`, the browser and
+  `winget`/`sudo`/`dpkg-query` are found first and spawned by their absolute path (git and `claude`,
+  the two whose working directory a request chooses, have a relative PATH entry made absolute first:
+  layer (2) does not cover a relative name that carries a directory, only a bare one), and `reg.exe` and
+  `taskkill.exe` are built from `%SystemRoot%\System32`; the system launchers that never run in a
+  request's directory are still bare names: `rundll32.exe` and `powershell.exe` on Windows, which layer (2)
+  covers, and `xdg-open`, `xdg-mime`, `systemctl`, `loginctl` and `systemd-run` on Linux, which has no
+  default working-directory search for a bare name. (The tunnel lint runs its interpreter in the
+  directory of the operator-configured preflight script, which is the script it runs anyway.)
+  (2) On Windows the agent process defines
+  `NoDefaultCurrentDirectoryInExePath=1` in its own environment as the first thing `ac-agent` does (every
+  command: `install`, `serve`, `status`, ...), unless that variable is already set. Windows' (and
+  libuv's) search for a bare executable name then no longer looks in the spawn's working directory
+  first, for any bare-name spawn anywhere in the process, and every child inherits the variable. The
+  variable is the agent's own addition to its environment, so a child (git and its credential
+  helpers, `ssh`) sees it too; it only turns the current-directory executable search off, which is
+  also what a Windows shell that has the variable set does: a script a child runs (an npm script, say)
+  that relies on a bare `build.bat` in its working directory, without `.\`, stops finding it. No agent
+  code depends on its value, and it does nothing off Windows. A machine that already defines it with a
+  value is left as it is (an empty value counts as unset and is replaced).
 - **Every other route requires `Authorization: Bearer <token>`**, compared with a
   constant-time equality check against a stored hash (never the token itself). Before pairing,
   every such route answers `401 {"error": "not paired"}`; a present-but-wrong token answers

package/data/README.md

@@ -1,17 +1,15 @@
 # `packages/agent/data/`
 
-Vendored copies of source files owned by other repos (unmodified, except where an entry below
-records a local addition), embedded into the agent's bundle as text (see `../text-plugin.mjs`).
+Vendored copies of source files owned by other repos, unmodified, embedded into the agent's bundle as
+text (see `../text-plugin.mjs`).
 
 ## `Get-ToolchainInventory.ps1`
 
 A copy of `artifact-console/data/Get-ToolchainInventory.ps1` from
 [`Rackbops/artifacts-console`](https://github.com/Rackbops/artifacts-console) (the 1.x app), pinned
-to commit `8e33836` **on that repo's `main`, plus one local addition (Rackbops/artifact-console#673):
-six added lines, the `Claude Code CLI` catalog row (after `Docker`, with its four-line comment) and its
-`$refLinks` entry**. It is byte-identical to `8e33836` apart from those six lines. From a checkout of
-that repo, `git -C <artifacts-console checkout> show 8e33836:artifact-console/data/Get-ToolchainInventory.ps1 | diff - <this repo>/packages/agent/data/Get-ToolchainInventory.ps1`
-prints exactly them, and `8e33836`'s own sha256 is `76b6a712c27f34ea9dc4cec230fc7107fd3c88720e8f24c0c2c933f2a685fea0`.
+to commit `5de373e` on that repo's `main`, byte-identical, with no local addition. From a checkout of
+that repo, `git -C <artifacts-console checkout> show 5de373e:artifact-console/data/Get-ToolchainInventory.ps1 | diff - <this repo>/packages/agent/data/Get-ToolchainInventory.ps1`
+prints nothing.
 
 - 1,832 lines, 102,154 bytes
 - LF line endings, no BOM, ASCII-only
@@ -21,20 +19,18 @@ The hash is platform-stable because both repos' `.gitattributes` normalize this
 `text=auto eol=lf`, and `toolchain-inventory.test.ts` asserts the embedded text hashes to the value
 above -- a re-vendored script whose bytes moved fails that test rather than silently drifting.
 
-**Re-copy, never edit -- with one standing exception.** The script is shipped and run as-is
+**Re-copy, never edit.** The script is shipped and run as-is
 (`packages/agent/src/scans/toolchain-inventory.ts`); a local edit here would break the byte-compare
-against 1.x's own output, which is the entire point of vendoring rather than rewriting it. The six
-lines above are the only local edit, made so that this agent's inventory reports the Claude Code CLI's
-version (the 1.x pipeline's sidecar validator had already learned the name, in `ac-pipeline` 0.4.1).
-1.x's `v1-maintenance` branch carries the same row and `$refLinks` text since artifacts-console#750
-(`ac-pipeline` 0.4.1), but that branch's script is an older revision without the `## Containers`
-section, so it is not a source to re-copy from. **Until the same six lines land on 1.x `main`, a
-re-vendor from `main` drops the row**; `toolchain-inventory.test.ts` then fails (the catalog-names
-test and the Claude Code CLI row tests name it), so it cannot be dropped silently. To pick up a newer
-1.x revision: copy the file from the new commit (re-applying the six lines if `main` does not carry
-them yet), update the commit hash and the three numbers above, and re-run the embedding/drift-guard
-tests (`toolchain-inventory.test.ts`) -- they also pin the script's catalog names and schema-version
-literal, so a re-vendor whose shape moved is caught there, not discovered on a card.
+against 1.x's own output, which is the entire point of vendoring rather than rewriting it. The
+`Claude Code CLI` catalog row (after `Docker`) and its `$refLinks` entry, which this agent's
+inventory reports for Rackbops/artifact-console#673, come from 1.x `main` itself since
+artifacts-console#755. 1.x's `v1-maintenance` branch carries the same row since
+artifacts-console#750, but that branch's script is an older revision without the `## Containers`
+section, so it is not a source to re-copy from. To pick up a newer 1.x revision: copy the file from
+the new `main` commit, update the commit hash and the three numbers above, and re-run the
+embedding/drift-guard tests (`toolchain-inventory.test.ts`) -- they pin the script's catalog names
+(the `Claude Code CLI` row included) and schema-version literal, so a re-vendor whose shape moved is
+caught there, not discovered on a card.
 
 **Provenance note (Tooling#721 F3, landed 2026-09-29):** re-pinned from `7280ae6` to `8e33836`
 (`git diff --stat 7280ae6 8e33836 -- artifact-console/data/Get-ToolchainInventory.ps1`: 456
@@ -53,3 +49,8 @@ re-vendor changes for a machine with no such WSL/docker setup (the realistic cas
 today) is nothing. Confirmed by `toolchain-inventory.test.ts`'s existing suite passing unchanged (no
 test needed updating for this sync) -- the script's catalog and schema-version literal, which that
 suite pins directly, are both identical to before.
+
+**Provenance note (2026-10-09):** re-pinned from `8e33836` plus the six local `Claude Code CLI`
+lines (Rackbops/artifact-console#673) to `5de373e`, byte-identical, via artifacts-console#755 (the
+1.x `main` twin of artifacts-console#750, for artifacts-console#754). `git hash-object` gives
+`50ee5b9ad2cf7ae3722d438bb956daedc322df71` for both files, so the three numbers above are unchanged.

package/dist/ac-agent.mjs

@@ -47,7 +47,7 @@ function _mergeNamespaces(n, m) {
 }
 
 var name = "@rackbops/ac-agent";
-var version = "2.0.0-alpha.55";
+var version = "2.0.0-alpha.57";
 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 = {
@@ -59,7 +59,7 @@ var files = [
 	"data/"
 ];
 var engines = {
-	node: ">=24"
+	node: ">=26"
 };
 var publishConfig = {
 	access: "public"
@@ -119,7 +119,9 @@ function expandVars(value, env) {
 }
 /** Where `reg.exe` lives on this machine (`%SystemRoot%\System32`, `C:\Windows` when the process
  *  environment carries no `SystemRoot`). Shared with `claude-desktop.ts` (#457), so the two registry
- *  readers never disagree about which binary they launch. */
+ *  readers never disagree about which binary they launch. Absolute, not `reg.exe`, because Windows looks
+ *  for a bare name in the working directory first; `applySpawnGuard` (cli.ts, #699) now stops the whole
+ *  process doing that, and this stays absolute so neither layer is the only protection. */
 function regExePath(env) {
     const systemRoot = env.SystemRoot ?? String.raw `C:\Windows`;
     return path.win32.join(systemRoot, "System32", "reg.exe");
@@ -5208,7 +5210,12 @@ function createGrantState(initial, persist) {
     let current = initial;
     return {
         revision: () => current?.revision ?? null,
-        allows: (pluginId, capability) => (current?.grants[pluginId] ?? []).includes(capability),
+        // Own keys only (#722): `grants` is parsed from JSON, a plain object, and `constructor` passes
+        // PLUGIN_ID, so a bare `grants[pluginId]` read the inherited `Object` (no `.includes`) and the
+        // guard answered 500 instead of 403.
+        allows: (pluginId, capability) => current !== null && Object.hasOwn(current.grants, pluginId)
+            ? (current.grants[pluginId] ?? []).includes(capability)
+            : false,
         replace: (set) => {
             persist(set);
             current = set;
@@ -21540,8 +21547,8 @@ const GIT_TIMEOUT_MS = 120_000;
 // should cost that request single-digit seconds, not the full network-call budget.
 const ORIGIN_TIMEOUT_MS = 10_000;
 const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" };
-async function git(run, cwd, args, timeoutMs = GIT_TIMEOUT_MS) {
-    return run("git", args, { cwd, timeoutMs, env: GIT_ENV });
+async function git(exec, cwd, args, timeoutMs = GIT_TIMEOUT_MS) {
+    return exec.run(exec.cmd, args, { cwd, timeoutMs, env: GIT_ENV });
 }
 /** 1.x `provenance.py:53-55`'s lesson: a git *worktree*'s marker files sit directly in its own
  *  git-dir the same way a plain clone's do, so an existence check (not an is-directory check)
@@ -21608,26 +21615,26 @@ function parseRemoteOwnerName(url) {
 }
 /** The checkout's `origin` remote URL, trimmed, or null when there is none or the call fails --
  *  never thrown. */
-async function originUrl(repoPath, run) {
-    const result = await git(run, repoPath, ["remote", "get-url", "origin"], ORIGIN_TIMEOUT_MS);
+async function originUrl(repoPath, exec) {
+    const result = await git(exec, repoPath, ["remote", "get-url", "origin"], ORIGIN_TIMEOUT_MS);
     if (result.code !== 0)
         return null;
     return result.stdout.trim();
 }
-async function repoStatus(repoPath, run, exists) {
-    const gitDirResult = await git(run, repoPath, ["rev-parse", "--absolute-git-dir"]);
+async function repoStatus(repoPath, exec, exists) {
+    const gitDirResult = await git(exec, repoPath, ["rev-parse", "--absolute-git-dir"]);
     if (gitDirResult.code !== 0)
         return { ok: false, error: `git: ${gitDirResult.stderr}` };
-    const headResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const headResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
     if (headResult.code !== 0)
         return { ok: false, error: `git: ${headResult.stderr}` };
-    const originHeadResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "origin/HEAD"]);
-    const upstreamResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "@{upstream}"]);
+    const originHeadResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "origin/HEAD"]);
+    const upstreamResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "@{upstream}"]);
     const hasUpstream = upstreamResult.code === 0;
     const countsResult = hasUpstream
-        ? await git(run, repoPath, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"])
+        ? await git(exec, repoPath, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"])
         : { code: 1, stdout: ""};
-    const porcelainResult = await git(run, repoPath, ["status", "--porcelain"]);
+    const porcelainResult = await git(exec, repoPath, ["status", "--porcelain"]);
     if (porcelainResult.code !== 0)
         return { ok: false, error: `git: ${porcelainResult.stderr}` };
     const { behind, ahead } = counts(countsResult.stdout.trim(), countsResult.code);
@@ -21642,7 +21649,7 @@ async function repoStatus(repoPath, run, exists) {
         inProgress: inProgress(gitDirResult.stdout.trim(), exists),
     };
 }
-async function pullRepo(name, repoPath, run, options, exists) {
+async function pullRepo(name, repoPath, exec, options, exists) {
     const skip = (reason, detail, behind = 0, ahead = 0) => ({
         name,
         path: repoPath,
@@ -21652,10 +21659,10 @@ async function pullRepo(name, repoPath, run, options, exists) {
         behind,
         ahead,
     });
-    const gitDirResult = await git(run, repoPath, ["rev-parse", "--absolute-git-dir"]);
+    const gitDirResult = await git(exec, repoPath, ["rev-parse", "--absolute-git-dir"]);
     if (gitDirResult.code !== 0)
         return skip("not-a-repo", "no git checkout here");
-    const fetchResult = await git(run, repoPath, ["fetch", "--prune"]);
+    const fetchResult = await git(exec, repoPath, ["fetch", "--prune"]);
     if (fetchResult.code !== 0) {
         return {
             name,
@@ -21670,20 +21677,20 @@ async function pullRepo(name, repoPath, run, options, exists) {
             ahead: 0,
         };
     }
-    const upstreamResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "@{upstream}"]);
+    const upstreamResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "@{upstream}"]);
     const hasUpstream = upstreamResult.code === 0;
     const countsResult = hasUpstream
-        ? await git(run, repoPath, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"])
+        ? await git(exec, repoPath, ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"])
         : { code: 1, stdout: ""};
     const { behind, ahead } = counts(countsResult.stdout.trim(), countsResult.code);
-    const headResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const headResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
     const branch = headResult.stdout.trim();
-    const originHeadResult = await git(run, repoPath, ["rev-parse", "--abbrev-ref", "origin/HEAD"]);
+    const originHeadResult = await git(exec, repoPath, ["rev-parse", "--abbrev-ref", "origin/HEAD"]);
     const defaultBr = defaultBranch(originHeadResult.stdout.trim(), originHeadResult.code);
     if (inProgress(gitDirResult.stdout.trim(), exists)) {
         return skip("in-progress", "a rebase/merge is underway", behind, ahead);
     }
-    const porcelainResult = await git(run, repoPath, ["status", "--porcelain"]);
+    const porcelainResult = await git(exec, repoPath, ["status", "--porcelain"]);
     if (porcelainResult.stdout.trim() !== "") {
         return skip("dirty", "uncommitted changes", behind, ahead);
     }
@@ -21720,7 +21727,7 @@ async function pullRepo(name, repoPath, run, options, exists) {
             ahead: 0,
         };
     }
-    const mergeResult = await git(run, repoPath, ["merge", "--ff-only", "@{upstream}"]);
+    const mergeResult = await git(exec, repoPath, ["merge", "--ff-only", "@{upstream}"]);
     if (mergeResult.code !== 0) {
         return skip("diverged", 
         // 1.x's check_repo (repo_pull.py:216) slices the same combined, stripped stdout+stderr text.
@@ -21737,6 +21744,82 @@ async function pullRepo(name, repoPath, run, options, exists) {
     };
 }
 
+/** The absolute path of the executable `findExecutable` found, for a verb that spawns it with a working
+ *  directory that is not the agent's own (a repo checkout, #699). `findExecutable` joins a PATH entry to
+ *  the tool name as it is, so a PATH with a relative entry (`.`, `bin`) yields `git.exe` or `bin\git.exe`:
+ *  existence was checked against the AGENT's working directory, but a spawn resolves a relative name
+ *  against its own `cwd`, where a checkout's planted file would be the one that runs. `path.resolve`
+ *  names the very file that was checked, and returns an absolute path unchanged. */
+function absoluteExecutablePath(found) {
+    return path.resolve(found);
+}
+/** The text of the `502` a verb answers when the executable it needs cannot be run (#699): the tool is
+ *  `name` and the result of looking for it is `found`. A `.cmd`/`.bat` shim on PATH is named as such,
+ *  with what to install instead (`nativeBinary` completes "install ..."), and anything else is "not found
+ *  on PATH". `gh.ts`, the repo verbs and the toolchain upgrade all build their message with this, so the
+ *  wording a client matches on is one function's for those three (`claude.ts` and the preflight still
+ *  build their own inline copies of the same kind of text). */
+function notFoundError(name, found, nativeBinary = "the native binary") {
+    if (!found.found && found.reason === "shim") {
+        return `${name} is a .cmd shim; install ${nativeBinary}`;
+    }
+    return `${name} not found on PATH`;
+}
+/** Strips one pair of surrounding double quotes from a PATH entry ("C:\Program Files\Git\cmd" is
+ *  legal in a Windows PATH, and `CreateProcess` strips it before use) -- an entry left quoted
+ *  would otherwise never match a real file and read as `missing`. Harmless on POSIX, where a real
+ *  directory name wrapped in literal quotes is not a thing that happens. */
+function unquote(entry) {
+    return entry.length >= 2 && entry.startsWith('"') && entry.endsWith('"')
+        ? entry.slice(1, -1)
+        : entry;
+}
+function findExecutable(name, env, platform, fs) {
+    const pathVar = env.PATH ?? env.Path ?? "";
+    const sep = platform === "win32" ? ";" : ":";
+    // A PATH entry that doesn't exist on disk is skipped by the exists() checks below, never thrown
+    // -- there's nothing here to throw on a plain string split, and exists() is a pure boolean.
+    const dirs = pathVar
+        .split(sep)
+        .filter((d) => d !== "")
+        .map(unquote);
+    // path.win32/path.posix explicitly, never the bare path.join/path.dirname -- those pick their
+    // behavior from the OS this code is actually running on, not from the `platform` parameter, so
+    // testing "linux" logic from a Windows dev box (or vice versa) would silently join with the
+    // wrong separator otherwise.
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
+    const probed = [];
+    if (platform === "win32") {
+        for (const dir of dirs) {
+            const exePath = join(dir, `${name}.exe`);
+            probed.push(exePath);
+            if (fs.exists(exePath))
+                return { found: true, path: exePath };
+            const cmdPath = join(dir, `${name}.cmd`);
+            if (fs.exists(cmdPath))
+                return { found: false, reason: "shim", path: cmdPath };
+            const batPath = join(dir, `${name}.bat`);
+            if (fs.exists(batPath))
+                return { found: false, reason: "shim", path: batPath };
+        }
+        return { found: false, reason: "not-found", probed };
+    }
+    for (const dir of dirs) {
+        const candidate = join(dir, name);
+        probed.push(candidate);
+        if (fs.exists(candidate) && fs.isExecutable(candidate))
+            return { found: true, path: candidate };
+    }
+    return { found: false, reason: "not-found", probed };
+}
+
+var which = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  absoluteExecutablePath: absoluteExecutablePath,
+  findExecutable: findExecutable,
+  notFoundError: notFoundError
+});
+
 /** Whether `root/name`'s REAL (symlink/junction-resolved) parent is still the real `root` --
  *  the check a nominal path match can't make. `false` on any realpath failure: a path that can't
  *  be resolved is never treated as contained. */
@@ -21810,18 +21893,34 @@ function resolveRepo(root, name, fs) {
 /** Annotates one already-listed entry with its resolved `ownerName` -- a real `git remote
  *  get-url` spawn per call, so this is only ever used from the HTTP handlers below, never from
  *  `listRepos` itself (memory-footprint's scan calls that directly and must stay git-free). */
-async function withOwnerName(entry, run) {
-    const url = await originUrl(entry.path, run);
+async function withOwnerName(entry, exec) {
+    const url = await originUrl(entry.path, exec);
     return { ...entry, ownerName: url === null ? null : parseRemoteOwnerName(url) };
 }
+/** Where git is, resolved ONCE at the start of a request (#699), before any repo work and before any
+ *  working directory is used: every git spawn of the request then names this absolute path, never the
+ *  bare `git` that Windows would look for in the repo itself first. Not found is the verb's `502`, in
+ *  the wording `gh` uses.
+ *
+ *  The path is made absolute (`absoluteExecutablePath`): a PATH with a relative entry would otherwise
+ *  hand the spawn `git.exe` or `bin\git.exe`, to be resolved against the repo. */
+async function resolveGit(deps) {
+    const found = deps.which("git", { PATH: await deps.searchPath() });
+    if (!found.found)
+        return { ok: false, error: notFoundError("git", found) };
+    return { ok: true, git: { run: deps.run, cmd: absoluteExecutablePath(found.path) } };
+}
 function registerRepoVerbs(registry, deps) {
     registry.register({
         capability: "agent.git.read",
         method: "GET",
         path: "/repos",
         handler: async (c) => {
+            const git = await resolveGit(deps);
+            if (!git.ok)
+                return c.json({ ok: false, error: git.error }, 502);
             const listed = listRepos(deps.root(), deps.fs);
-            const repos = await Promise.all(listed.repos.map((entry) => withOwnerName(entry, deps.run)));
+            const repos = await Promise.all(listed.repos.map((entry) => withOwnerName(entry, git.git)));
             return c.json({ ...listed, repos });
         },
     });
@@ -21830,16 +21929,19 @@ function registerRepoVerbs(registry, deps) {
         method: "GET",
         path: "/repos/:name/status",
         handler: async (c) => {
+            const git = await resolveGit(deps);
+            if (!git.ok)
+                return c.json({ ok: false, error: git.error }, 502);
             // Hono's param() is typed string | undefined for a dynamically-built path (it can't see
             // the literal ":name" above at the type level); an actually-missing segment can't reach
             // this handler at all, and the fallback empty string just fails resolveRepo's pattern.
             const resolved = resolveRepo(deps.root(), c.req.param("name") ?? "", deps.fs);
             if (resolved === null)
                 return c.json({ ok: false, error: "no such repo" }, 404);
-            const status = await repoStatus(resolved.path, deps.run, deps.fs.exists);
+            const status = await repoStatus(resolved.path, git.git, deps.fs.exists);
             if (!status.ok)
                 return c.json(status, 502);
-            const { ownerName } = await withOwnerName(resolved, deps.run);
+            const { ownerName } = await withOwnerName(resolved, git.git);
             return c.json({ name: resolved.name, path: resolved.path, ownerName, ...status });
         },
     });
@@ -21848,6 +21950,9 @@ function registerRepoVerbs(registry, deps) {
         method: "POST",
         path: "/repos/:name/pull",
         handler: async (c) => {
+            const git = await resolveGit(deps);
+            if (!git.ok)
+                return c.json({ ok: false, error: git.error }, 502);
             const resolved = resolveRepo(deps.root(), c.req.param("name") ?? "", deps.fs);
             if (resolved === null)
                 return c.json({ ok: false, error: "no such repo" }, 404);
@@ -21861,7 +21966,7 @@ function registerRepoVerbs(registry, deps) {
             catch {
                 // No body, or a non-JSON one -- dryRun keeps its documented default of false.
             }
-            const row = await pullRepo(resolved.name, resolved.path, deps.run, { dryRun }, deps.fs.exists);
+            const row = await pullRepo(resolved.name, resolved.path, git.git, { dryRun }, deps.fs.exists);
             deps.logEvent(`pull ${row.name}: ${row.status} ${row.reason}`);
             return c.json({ ok: true, row });
         },
@@ -22939,15 +23044,26 @@ async function dispatch(argv, io) {
 // apart from the fs-dep builders (`realExists`/`buildRepoFs`/`buildWhichFs`), which cli.test.ts builds
 // against a stubbed fs (#439). ---
 const TASK_NAME = "ac-agent";
-function checkEnvironment() {
-    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-    if (major < 24) {
-        process.stderr.write(`ac-agent requires Node >=24, found ${process.versions.node}\n`);
-        return 2;
+/**
+ * The oldest Node major the agent runs on (#827): the fleet's one Node line, the console image's
+ * major. Both `package.json` files say `engines.node: ">=<NODE_FLOOR>"`, and node-floor.test.ts pins
+ * all three to the Dockerfile's `FROM node:<major>...`. `npx` treats `engines` only as a warning, so
+ * `checkEnvironment` is what actually refuses an older Node.
+ */
+const NODE_FLOOR = 26;
+/**
+ * The runtime check `main` runs before any verb (so a machine left on an older Node fails loudly
+ * instead of running untested, and `install` never half-installs): a Node major below `NODE_FLOOR`,
+ * or a platform other than Windows or Linux, is refused with one stderr line and exit 2. Pure, so the
+ * caller writes the line and exits; `null` means the agent may run.
+ */
+function checkEnvironment(nodeVersion = process.versions.node, platform = process.platform) {
+    const major = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    if (major < NODE_FLOOR) {
+        return { code: 2, message: `ac-agent requires Node >=${NODE_FLOOR}, found ${nodeVersion}` };
     }
-    if (process.platform !== "win32" && process.platform !== "linux") {
-        process.stderr.write(`ac-agent supports Windows and Linux, found ${process.platform}\n`);
-        return 2;
+    if (platform !== "win32" && platform !== "linux") {
+        return { code: 2, message: `ac-agent supports Windows and Linux, found ${platform}` };
     }
     return null;
 }
@@ -23365,18 +23481,25 @@ async function realServe(overrides = {}) {
     const registry$3 = createVerbRegistry();
     const run = createRun();
     const repoFs = buildRepoFs(fs);
+    const whichFs = buildWhichFs(fs);
+    // The optional second (env) parameter is #55's own addition: claude.ts/gh.ts's own deps type
+    // `which` as one-argument (a required second parameter would not be assignable to that, tsc
+    // 5.9 TS2322), while runPreflight's deps call it with the refreshed PATH on every probe.
+    const which$1 = (name, env = process.env) => findExecutable(name, env, process.platform, whichFs);
+    // The PATH to look for an executable on: the registry's on Windows (a tool installed after this agent
+    // started is still found), the process PATH elsewhere. One closure for the repo verbs (git, #699) and
+    // the toolchain upgrade, so "where is X" has a single answer ("reuse that resolution, never a second
+    // list").
+    const refreshedPath = async () => (await searchPath({ platform: process.platform, env: process.env, run })).path;
     registerRepoVerbs(registry$3, {
         root: () => loaded.config.reposRoot,
         run,
         fs: repoFs,
         logEvent: (message) => log$1.write(message),
+        which: which$1,
+        searchPath: refreshedPath,
     });
     registerOpenVerb(registry$3, { spawn: createSpawn(), platform: process.platform });
-    const whichFs = buildWhichFs(fs);
-    // The optional second (env) parameter is #55's own addition: claude.ts/gh.ts's own deps type
-    // `which` as one-argument (a required second parameter would not be assignable to that, tsc
-    // 5.9 TS2322), while runPreflight's deps call it with the refreshed PATH on every probe.
-    const which$1 = (name, env = process.env) => findExecutable(name, env, process.platform, whichFs);
     // Named so both /v1/preflight (below, via createApp) and the publish verb's browser resolution
     // (#53, immediately below) share the exact same search -- "reuse that resolution, never a second
     // list" (E6-work/53-publish-mirror.md).
@@ -23493,7 +23616,7 @@ async function realServe(overrides = {}) {
         loaded,
         platform: process.platform,
         which: which$1,
-        searchPath: async () => (await searchPath({ platform: process.platform, env: process.env, run })).path,
+        searchPath: refreshedPath,
         run,
         jobs,
         userInfo: () => os.userInfo(),
@@ -23609,10 +23732,40 @@ async function realServe(overrides = {}) {
     process.on("SIGTERM", shutdown);
     process.on("SIGINT", shutdown);
 }
+/** The environment variable that stops Windows from searching the current directory for an executable. */
+const NO_CWD_EXE_SEARCH_VAR = "NoDefaultCurrentDirectoryInExePath";
+/**
+ * Make this process refuse the current-directory executable search (#699). On Windows, a spawn of a bare
+ * name (`git`, `taskkill`, ...) is resolved by libuv's `search_path` (`src/win/process.c`), which looks in
+ * the spawn's working directory first -- `<name>.com`, then `<name>.exe` -- whenever
+ * `NeedCurrentDirectoryForExePathW("")` is true, i.e. unless the CALLING PROCESS's environment defines
+ * `NoDefaultCurrentDirectoryInExePath` (the child's `env` option is not consulted). So a spawn whose cwd
+ * is a repo checkout runs whatever the checkout holds. Setting the variable here covers every bare-name
+ * spawn in this process, and the children inherit it (so a child's own `cmd.exe` stops running a bare
+ * `build.bat` out of its working directory too). This is the general guard for that class (`taskkill.exe`
+ * and `reg.exe` were already spawned by absolute path for it; `git` was the one that was missed); the
+ * repo verbs still run git by absolute path, so neither layer is the only protection. It covers a BARE
+ * name only: a relative name that carries a directory (`bin\git.exe`) is resolved against the spawn's
+ * working directory either way, which is why `absoluteExecutablePath` exists. A no-op off Windows, and it
+ * never changes a value that is set.
+ * The empty string counts as unset: whether an empty value switches the search off is not something
+ * this code relies on.
+ */
+function applySpawnGuard(env, platform) {
+    if (platform !== "win32")
+        return;
+    const current = env[NO_CWD_EXE_SEARCH_VAR];
+    if (current === undefined || current === "")
+        env[NO_CWD_EXE_SEARCH_VAR] = "1";
+}
 async function main(argv) {
+    // Before anything can spawn: the very first statement, ahead of the environment check and of every
+    // dynamic import below.
+    applySpawnGuard(process.env, process.platform);
     const envError = checkEnvironment();
     if (envError !== null) {
-        process.exit(envError);
+        process.stderr.write(`${envError.message}\n`);
+        process.exit(envError.code);
     }
     const io = {
         install: async (args) => {
@@ -65144,7 +65297,8 @@ 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.
+            // directory before PATH. `applySpawnGuard` (cli.ts, #699) now also stops the process doing that
+            // for any bare name; this stays absolute so neither layer is the only protection.
             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,
@@ -65252,7 +65406,8 @@ function registerClaudeVerbs(registry, deps) {
                 return c.json({ ok: false, error: "too many running jobs" }, 429);
             }
             const argv = [
-                which.path,
+                // absolute: this spawn's cwd is the repo checkout (#699), see absoluteExecutablePath
+                absoluteExecutablePath(which.path),
                 "-p",
                 validated.value.prompt,
                 "--permission-mode",
@@ -65560,10 +65715,7 @@ function registerGhVerb(registry, deps) {
             }
             const which = deps.which("gh");
             if (!which.found) {
-                const error = which.reason === "shim"
-                    ? "gh is a .cmd shim; install the native GitHub CLI binary"
-                    : "gh not found on PATH";
-                return c.json({ ok: false, error }, 502);
+                return c.json({ ok: false, error: notFoundError("gh", which, "the native GitHub CLI binary") }, 502);
             }
             const result = await deps.run(which.path, args, { timeoutMs: GH_TIMEOUT_MS, env: GH_ENV });
             const stdout = truncateOutput(result.stdout);
@@ -65586,59 +65738,6 @@ var gh = /*#__PURE__*/Object.freeze({
   registerGhVerb: registerGhVerb
 });
 
-/** Strips one pair of surrounding double quotes from a PATH entry ("C:\Program Files\Git\cmd" is
- *  legal in a Windows PATH, and `CreateProcess` strips it before use) -- an entry left quoted
- *  would otherwise never match a real file and read as `missing`. Harmless on POSIX, where a real
- *  directory name wrapped in literal quotes is not a thing that happens. */
-function unquote(entry) {
-    return entry.length >= 2 && entry.startsWith('"') && entry.endsWith('"')
-        ? entry.slice(1, -1)
-        : entry;
-}
-function findExecutable(name, env, platform, fs) {
-    const pathVar = env.PATH ?? env.Path ?? "";
-    const sep = platform === "win32" ? ";" : ":";
-    // A PATH entry that doesn't exist on disk is skipped by the exists() checks below, never thrown
-    // -- there's nothing here to throw on a plain string split, and exists() is a pure boolean.
-    const dirs = pathVar
-        .split(sep)
-        .filter((d) => d !== "")
-        .map(unquote);
-    // path.win32/path.posix explicitly, never the bare path.join/path.dirname -- those pick their
-    // behavior from the OS this code is actually running on, not from the `platform` parameter, so
-    // testing "linux" logic from a Windows dev box (or vice versa) would silently join with the
-    // wrong separator otherwise.
-    const join = platform === "win32" ? path.win32.join : path.posix.join;
-    const probed = [];
-    if (platform === "win32") {
-        for (const dir of dirs) {
-            const exePath = join(dir, `${name}.exe`);
-            probed.push(exePath);
-            if (fs.exists(exePath))
-                return { found: true, path: exePath };
-            const cmdPath = join(dir, `${name}.cmd`);
-            if (fs.exists(cmdPath))
-                return { found: false, reason: "shim", path: cmdPath };
-            const batPath = join(dir, `${name}.bat`);
-            if (fs.exists(batPath))
-                return { found: false, reason: "shim", path: batPath };
-        }
-        return { found: false, reason: "not-found", probed };
-    }
-    for (const dir of dirs) {
-        const candidate = join(dir, name);
-        probed.push(candidate);
-        if (fs.exists(candidate) && fs.isExecutable(candidate))
-            return { found: true, path: candidate };
-    }
-    return { found: false, reason: "not-found", probed };
-}
-
-var which = /*#__PURE__*/Object.freeze({
-  __proto__: null,
-  findExecutable: findExecutable
-});
-
 /**
  * The agent's in-memory job registry (#49, 49b): a port of the host's own
  * `packages/host/src/tasks/registry.ts` (#42), extended with the fields a `claude -p` run needs
@@ -66234,7 +66333,8 @@ const WINDOWS = {
 };
 const TIERS = [200_000, 1_000_000];
 function windowFor(model, occupancy) {
-    const win = WINDOWS[model];
+    // Own keys only (#722): `model` is text from a transcript, as in 1.x's dict lookup.
+    const win = Object.hasOwn(WINDOWS, model) ? WINDOWS[model] : undefined;
     if (win !== undefined)
         return { window: win, mapped: true };
     for (const tier of TIERS) {
@@ -66644,7 +66744,8 @@ function isPlainObject(v) {
 /** USD-equivalent for one assistant turn, at list API rates. `0` for an unpriced model -- the
  *  caller counts its tokens and surfaces the id instead of guessing. */
 function recordCost(model, usage) {
-    const rate = PRICES[model];
+    // Own keys only (#722): `model` is text from a transcript, as in 1.x's dict lookup.
+    const rate = Object.hasOwn(PRICES, model) ? PRICES[model] : undefined;
     if (!rate)
         return 0;
     const creation = isPlainObject(usage.cache_creation) ? usage.cache_creation : {};
@@ -66733,7 +66834,7 @@ function scanFile(fileBuffer, mtime, size, stem, parentName, fullPathComponents)
         turns++;
         if (model) {
             models.add(model);
-            if (!(model in PRICES))
+            if (!Object.hasOwn(PRICES, model))
                 unpriced.add(model);
         }
         cost += recordCost(model, usage);
@@ -66851,7 +66952,7 @@ var scriptText = "<#\n.SYNOPSIS\n    Inventory the language toolchains installed
  * Runs 1.x's own `Get-ToolchainInventory.ps1` through `pwsh` (#52, 52b; 1.x had no Linux
  * equivalent, `toolchain_sidecar.py`, `sched_spec.py:264-273`), kind `toolchain-inventory`,
  * capability `agent.scan.toolchain-inventory`. Shipped and run, not rewritten (`data/README.md`):
- * the script is 1,832 lines (1.x `main` at `8e33836` plus the six lines #673 added) whose output is
+ * the script is 1,832 lines (1.x `main` at `5de373e`, vendored byte for byte) whose output is
  * the byte-compare target, so a TypeScript rewrite would have to re-derive every probe and
  * formatting rule and still match it byte for byte.
  *
@@ -67176,7 +67277,8 @@ var scan = /*#__PURE__*/Object.freeze({
  *
  * `why` strings are 1.x's own (`:116-157`), verbatim -- they are the *consequence* of a tool's
  * absence, not a restatement of its name, and this plan reuses them rather than re-deriving new
- * wording that could quietly drift from what the 1.x Environment card has always said.
+ * wording that could quietly drift from what the 1.x Environment card has always said. The
+ * `docker` and `cloudflared` rows (#828) have no 1.x counterpart; theirs follow the same rule.
  */
 const PREREQ_TABLE = [
     {
@@ -67203,6 +67305,19 @@ const PREREQ_TABLE = [
         required: true,
         why: "the spawned `claude -p` coding tasks, and the context-pressure / subagent-cost scans -- every console action that runs a headless Claude fails without it",
     },
+    // #828: two of the fleet standard's tools; optional, so a machine without them is not a failed preflight.
+    {
+        cmd: "docker",
+        label: "Docker",
+        required: false,
+        why: "the console host and every server stack run in it; without it a server role has nothing to run, and a dev box simply has no container tooling",
+    },
+    {
+        cmd: "cloudflared",
+        label: "cloudflared",
+        required: false,
+        why: "the tunnels that put the console and the other stacks behind Cloudflare Access; without it a server host is unreachable from outside the LAN",
+    },
     {
         cmd: "chromium",
         label: "PDF renderer (Chromium-family)",
@@ -67339,7 +67454,7 @@ async function checkRowUnsafe(entry, deps, refreshedEnv) {
     return { ...base, status: "missing", path: "", version: "", detail: "" };
 }
 /** Wraps one row's whole resolution so a throwing `which`/`run`/`exists` becomes that row's own
- *  `broken`, never a crash that takes the other four rows down with it (1.x
+ *  `broken`, never a crash that takes the other rows down with it (1.x
  *  `tests/test_readiness.py:263`'s "a probe that raises becomes a row, not a crash"). */
 async function checkRow(entry, deps, refreshedEnv) {
     try {
@@ -67372,7 +67487,7 @@ const CHROMIUM_ENTRY = PREREQ_TABLE.find((entry) => entry.cmd === "chromium");
  * with `runPreflight`'s own `chromium` row) rather than a second candidate list: winPaths first, then
  * `cmd`/`altCmds` on the refreshed PATH, then the same names under a version manager's bin dir. Never
  * executes the browser (E4 §5 decision 19, unchanged here). Used by the publish-mirror verb (#53) so
- * finding a PDF renderer doesn't also run the rest of preflight (git/gh/node/claude) on every publish.
+ * finding a PDF renderer doesn't also run the rest of preflight (every executed row) on every publish.
  */
 async function resolveChromiumPath(deps) {
     if (!CHROMIUM_ENTRY)
@@ -75557,9 +75672,9 @@ var tunnel = /*#__PURE__*/Object.freeze({
  *   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.
+ *   other program the request can name is `cmd`, and only to read its version: it must be one of the four
+ *   tools in `VERSION_READABLE_CMDS` (each one the preflight already runs `--version` on), 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
@@ -75594,11 +75709,15 @@ const MANAGERS = ["winget", "apt", "native"];
 // 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");
+/** The commands whose `--version` this verb may run: four of the tools the agent's own preflight executes
+ *  (never `chromium`, which the preflight only resolves: a Chromium-family `--version` can open a window,
+ *  E4 §5 decision 19). The Environment panel sends the `cmd` of a preflight row, so a `cmd` outside this
+ *  list is either a row the panel only grades (`docker`, `cloudflared`, #828: upgrading either can restart
+ *  the containers or tunnels on the host, a host operation, not a panel button's) or a request to run a
+ *  program of the console's choosing. */
+// An explicit list, not derived from PREREQ_TABLE: adding a preflight row must never widen the `cmd`s this
+// verb accepts for an upgrade (#828). (`cmd` is not tied to `packageId`; see the README.)
+const VERSION_READABLE_CMDS = ["git", "gh", "node", "claude"];
 // 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}$/;
@@ -75628,8 +75747,8 @@ function validateUpgradeRequest(body, platform) {
     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`.
+    // An allowlist, not a grammar: only the four upgradable 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(", ")})`);
     }
@@ -75738,12 +75857,18 @@ function sudoersRule(username) {
 function printable(text, max) {
     return text.replace(/[^\x20-\x7e]/g, "?").slice(0, max);
 }
+/** A closing line that advises rather than reports, e.g. the Claude CLI's "Or consider using native
+ *  installation with: claude install" printed after the error that actually failed the run. */
+const ADVICE_LINE = /^(?:or\s+)?(?:consider|try|hint|tip|see|for more)(?=\s|:|$)/i;
+/** The command's last line that reports something: trailing advice lines are skipped, so the reason
+ *  is the failure and not the hint printed after it. All-advice output falls back to its last line. */
 function lastNonEmptyLine(text) {
     const lines = text
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter((line) => line !== "");
-    return printable(lines.at(-1) ?? "", MAX_REASON_CHARS);
+    const reported = lines.findLast((line) => !ADVICE_LINE.test(line));
+    return printable(reported ?? lines.at(-1) ?? "", MAX_REASON_CHARS);
 }
 function classifyOutcome(input) {
     if (input.limit === "timeout") {
@@ -75812,12 +75937,6 @@ const SPAWN_DIAGNOSTIC = /^\[(?:killed, but its output never closed|the command
 // 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;
@@ -76536,4 +76655,4 @@ var updater = /*#__PURE__*/Object.freeze({
   selfUpdateSupported: selfUpdateSupported
 });
 
-export { AGENT_API_VERSION, buildRepoFs, buildWhichFs, dispatch, healthResultFrom, isEntryPoint, main, realExists, runningJobCount, toolchainUpgradeDeps };
+export { AGENT_API_VERSION, NODE_FLOOR, NO_CWD_EXE_SEARCH_VAR, applySpawnGuard, buildRepoFs, buildWhichFs, checkEnvironment, dispatch, healthResultFrom, isEntryPoint, main, realExists, runningJobCount, toolchainUpgradeDeps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-agent",
-  "version": "2.0.0-alpha.55",
+  "version": "2.0.0-alpha.57",
   "private": false,
   "type": "module",
   "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.",
@@ -13,7 +13,7 @@
     "data/"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=26"
   },
   "publishConfig": {
     "access": "public"