@rackbops/ac-agent 2.0.0-alpha.58 → 2.0.0-alpha.60

package/README.md

@@ -106,14 +106,24 @@ Registers a Windows Task Scheduler task (`\ClaudeLocal\ac-agent`, a logon trigge
 user) or, on Linux, a systemd `--user` unit (`ac-agent.service`, `enable --now`), copies the running
 bundle into the state dir (never the `npx` cache — that can be garbage-collected out from under a
 long-running service), writes `agent.toml` if one doesn't already exist, and generates a self-signed
-cert if one doesn't already exist. On an existing install, an explicit `--repos-root <abs>` narrowly
+cert if one doesn't already exist (also when `cert.pem`/`key.pem` exist but are not a usable pair, an
+empty or mismatched file, with a warning: the new fingerprint must be paired again; `install` prints
+it, `serve` writes it to `agent.log`). The certificate, key, token hash, grants, pending pairing code,
+`agent.toml` are written to a temp name (`<file>.tmp-<pid>`, fsynced) and renamed over; a hard kill
+between the write and the rename can leave a stray `*.tmp-<pid>` beside the file. `update.json`
+(`update.json.tmp`, not fsynced, a failed write is printed and swallowed) and the embedded
+toolchain-inventory script are renamed over from a temp name too. Still written in place: the
+Windows launch script, the systemd unit, the AppData-virtualization probe files, the scans cache (a
+torn one just re-scans) and the self-update staging directory. A file that cannot be read for
+any reason other than not existing is an error, not an empty answer (`status` instead lists it under
+`unreadable`, by file name and error code, and treats it as absent). On an existing install, an explicit `--repos-root <abs>` narrowly
 updates only the top-level `repos_root` string in `agent.toml`; comments, ordering, unknown keys,
 credentials, grants, and every other setting stay untouched. The old and new roots are compared as
 exact strings, so an equal value does not rewrite the file or change its mtime. A malformed file or
 a non-string `repos_root` is refused rather than rewritten. Prints the resolved config/state paths,
 the cert's fingerprint, and the firewall rule's status.
 
-Options: `--port <n>` (default `8788`), `--name <machine>` (default `os.hostname()`), `--repos-root
+Options: `--port <n>` (default `8788`; an integer from 1 to 65535, refused otherwise, and `agent.toml`'s `port` is held to the same rule), `--name <machine>` (default `os.hostname()`), `--repos-root
 <abs>` (default `<homedir>/repos`; the fleet's roots differ per box — Windows and Linux checkouts
 don't share a layout, so every real install passes this explicitly). A relative `--repos-root` is
 rejected before installation side effects on both fresh and existing installs. On an existing
@@ -125,13 +135,20 @@ warns that the environment still wins at runtime until it is unset.
 Installing over an already-running agent restarts it (#277): once the task/unit is re-registered
 against the new bundle, `install` stops the old process and starts it again through the same
 `stop`/`start` machinery the `ac-agent stop`/`ac-agent start` commands use, then confirms the new
-process is actually answering (a health check, retried for a few seconds — the OS command that
+process is actually answering (on the configured `bind` when it names one address, else on `127.0.0.1`) (a health check, retried for a few seconds — the OS command that
 launches a process can report success before that process has actually started listening) before
 printing `restarted: now serving <version>`. Only a health answer reporting the **new** version
 counts (#659), so the old process still answering on the port is not mistaken for the new one.
 
 Before copying the new bundle in over a running agent, `install` keeps the one it replaces as
-`bin/ac-agent.prev.mjs` in the state dir (#659; one backup, overwritten by the next install). If the
+`bin/ac-agent.prev.mjs` in the state dir (#659; one backup, overwritten by the next install). Both
+the backup (`ac-agent.prev.mjs.tmp`) and the new bundle (`ac-agent.mjs.tmp`) are copied beside their
+target and renamed into place, as is the restore, so an install killed mid-copy leaves the old bundle
+whole. When the running agent reported its version and `node <bundle> version` is available, the live
+bundle is backed up only if it reports that same version: after an aborted install it may be a newer
+file than the process serving, and it must not overwrite a good backup (an existing backup is kept when
+it is the running version; otherwise no backup is made and `install` prints a warning that it cannot
+roll back). When the running version is not known the backup is made unchecked, as before. If the
 new bundle never answers health at its own version, `install` rolls back:
 1. It stops the task/unit again. On Windows this ends `launch.js`'s retry loop, so it can't rerun the
    broken bundle in the middle of the restore.
@@ -152,8 +169,11 @@ restart (registering the task/unit, the certificate) and a backup was made, the
 is copied back onto the disk; the error is reported as before.
 
 The install then **fails** (exit 1), because it did not take. If the rollback fails too, it prints
-`rollback failed: ...`, leaves both bundles in place, and also exits 1; `ac-agent start` is the
-fallback.
+`rollback failed: ...` and also exits 1; `ac-agent start` is the fallback. Which file holds what depends
+on how far the rollback got: `ac-agent.prev.mjs` always holds the previous bundle, and the live
+`ac-agent.mjs` holds the previous bundle too once the restore copy has run (a failure while starting it or
+confirming it), but still the new one when the failure came before that copy. The message names
+`ac-agent.prev.mjs` and says to copy it over the live bundle if it is not already there.
 
 When there was no bundle to go back to, a restart that fails outright still reports the install as a
 success, with `restart failed: <reason>; run ac-agent stop && ac-agent start`, and that manual
@@ -184,8 +204,11 @@ it.
 
 `install` tries to add an inbound rule (`New-NetFirewallRule`, Windows only) so a LAN caller can
 reach the port. Creating a firewall rule needs administrator rights; when the process isn't
-elevated, `install` prints the exact one-liner to run in an elevated PowerShell and `status` reports
-`firewall: missing` until that's done. This is expected on a fresh install run from an ordinary
+elevated, `install` prints the exact one-liner to run in an elevated PowerShell. An existing `ac-agent`
+rule is kept only when its `LocalPort` is the install's port; a rule on another port (a reinstall with a
+different port) is removed and recreated, and when that needs elevation the printed one-liner removes it
+first. `uninstall` leaves the rule in place and prints the elevated `Remove-NetFirewallRule` command
+that removes it. Only `install` reports the rule's state; `status` has no firewall field. This is expected on a fresh install run from an ordinary
 shell — it is not a failure to work around.
 
 ### Run install from a normal shell
@@ -241,6 +264,99 @@ race the bind and report a false failure. Wait a moment, then check:
 curl -k https://127.0.0.1:8788/v1/health
 ```
 
+#### A server host that also runs the console (#826)
+
+The machine that runs the console in Docker can pair an agent too, so its own toolchain is graded in
+the Agents panel's Environment section like any other machine's; nucbox is set up this way (#826; its pairing was still pending on
+2026-10-20). It installs
+the Linux way above, with these differences.
+
+**Node 26 from NodeSource's apt repository.** The agent needs Node 26 or newer (`engines.node`, #827;
+see **Install** above), the fleet's one line, and Ubuntu's own `nodejs` is older (22 on Ubuntu 26.04).
+Write NodeSource's key and source by hand rather than piping its setup script to a shell. The key:
+
+```sh
+curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
+  | gpg --dearmor | sudo tee /usr/share/keyrings/nodesource.gpg >/dev/null
+sudo chmod 0644 /usr/share/keyrings/nodesource.gpg
+```
+
+Its fingerprint is `6F71 F525 2828 41EE DAF8 51B4 2F59 B5F9 9B1B E0B4`. The source, in deb822 form,
+is `/etc/apt/sources.list.d/nodesource.sources`:
+
+```
+Types: deb
+URIs: https://deb.nodesource.com/node_26.x
+Suites: nodistro
+Components: main
+Architectures: amd64
+Signed-By: /usr/share/keyrings/nodesource.gpg
+```
+
+Two pins make NodeSource's packages win over Ubuntu's: `/etc/apt/preferences.d/nodejs` (below) and
+`/etc/apt/preferences.d/nsolid` (the same, with `Package: nsolid`):
+
+```
+Package: nodejs
+Pin: origin deb.nodesource.com
+Pin-Priority: 600
+```
+
+Then `sudo apt-get update && sudo apt-get install -y nodejs`, which brings `npm` with it. On nucbox
+(2026-10-09) that installed `26.11.1-1nodesource1` with npm 11.20.0 and removed Ubuntu's nodejs 22,
+its `node-*` libraries and `nodejs-doc`, so check first that nothing else on the host runs on the
+system Node. On nucbox nothing else did (its services run in Docker; the plan's read of the box,
+2026-10-08), so the agent is the system Node's only user.
+
+**An empty repos root.** After `sudo loginctl enable-linger "$USER"`:
+
+```sh
+mkdir -p "$HOME/ac-agent-repos"
+npx -y @rackbops/ac-agent install --repos-root "$HOME/ac-agent-repos"
+```
+
+The console's host holds no checkout the console should list or pull, so the repos root is an empty
+directory. `curl -k https://127.0.0.1:8788/v1/health` then answers `{"ok":true, ...,
+"paired":false}`.
+
+**The console reaches it at the host's LAN address.** Pair it as in **Pair** below, giving the
+console's form the URL `pair` prints. That is the host's LAN address, not `127.0.0.1`: the console's
+container runs on the same machine, but it calls this agent the way it calls any other, and inside the
+container `127.0.0.1` is the container itself. `pair` and the certificate leave Docker's bridge
+interfaces out (`docker0`, `br-*`, `veth*`; #330) unless they are the machine's only addresses, so the
+address printed is the real NIC's. A host firewall has to admit the agent's port from the console's
+Docker network as well as from the LAN, since the container's traffic to the host arrives from its
+bridge address (not verified on nucbox; pairing is the test). Give the pairing form the host's name in
+the fleet standard (`nucbox`): the Upgrade action finds the standard host by the name the console holds
+for the machine, and the Environment grading by the name the agent reports (its OS hostname, which an
+inventory sidecar's `hostname` maps to the host; see the agents plugin's README, "Which standard host a
+machine is").
+
+**The minimal grant set.** Opt the machine in to upgrades (`toolchain_upgrade = true` and the sudoers
+rule, **Operator setup** under `POST /v1/toolchain/upgrade`; read what that rule grants before adding
+it to a production host), restart it (`stop`, then `start`), and in the Grants grid give the `agents`
+plugin `agent.toolchain.upgrade` and nothing else: no `agent.exec.claude`, no `agent.git.*`, no
+`agent.scan.*`. The grading needs no grant at all (`GET /v1/preflight` is control plane, and so is
+`POST /v1/update`, which lets the console update the agent itself). The Upgrade button needs none
+either: it shows on any `behind` row whose tool the standard gives a package for on a Linux server
+(among `git`, `gh`, `node` and `claude`; a `docker` or `cloudflared` row gets one too, and the agent
+runs that upgrade at the next 05:00 America/New_York, #978). The grant is what lets
+a click succeed; without it the agent refuses with `agent.toolchain.upgrade is not granted to agents on
+<machine>`. That one granted verb installs a package the standard names: as root, through `sudo apt-get
+install --only-upgrade` and the sudoers rule, or for Claude Code with its own `claude update` as the
+agent's user. No other verb is granted: no `agent.exec.*`, `agent.git.*` or `agent.scan.*`.
+
+The console no longer asks this machine for what it has not been granted (#843):
+- The host's job runner skips a machine that has not granted every capability a job declares: no
+  `job_runs` row, no task and no `job failed` notification. The four `scans` jobs declare
+  `agent.scan.<kind>`, so each reads `not granted` on the machine's row instead of a failed run.
+- The `repos` plugin's repo-currency check and `provider-artifacts`' hourly `publish.mirror` raise no
+  Needs-attention row for a machine that never had the grant; the card reads `not granted`. A grant
+  revoked after a good result raises one row (`Repo currency is no longer granted on <machine>`, and
+  its mirror-publish counterpart) for 7 days, then nothing.
+- The Admin Security card's tunnel lint reads the console's own grants and does not call this agent;
+  it shows `agent.tunnel.lint is not granted to admin on <machine>` as a neutral row, not a warning.
+
 ### Windows: no console window
 
 The task's action is `wscript.exe //B "<launch.js>"` against a small generated JScript launcher
@@ -258,7 +374,8 @@ Running while serving and a crash propagates as a non-zero exit, visible afterwa
 scratch tasks with these exact settings, one killed by pid and one exiting on its own, sampled every
 30 s for 150 s): Task Scheduler's restart-on-failure does not act on the action's exit code for this
 action shape. The real crash-restart mechanism is `launch.js`'s own retry loop (#238): a non-zero
-exit sleeps a minute and runs node again, up to 3 retries, since the exit code is already in
+exit sleeps a minute and runs node again, up to 3 retries in a row (a run that lasted longer than five
+minutes starts the count over, so the budget is per crash loop, not per logon session), since the exit code is already in
 `wscript.exe`'s own hand; a zero exit (a deliberate shutdown) ends the loop instead. `stop`/`uninstall`
 stop the task first — ending the loop — before killing the orphaned node by pid, the reverse of the
 order that would otherwise let the loop see a bare kill as a crash and resurrect the agent a minute
@@ -280,14 +397,17 @@ window is visible at a real logon.
 npx @rackbops/ac-agent status
 ```
 
-Prints, as JSON: the config path and whether it came from a file or defaults, the state dir, the
+Prints two plain lines, `lan address: <ip|(none)>` and `repos: <n>`, and then, as JSON: the config path and whether it came from a file or defaults, the state dir, the
 Task Scheduler/systemd service state, whether a pairing token is stored (`paired: true/false`), the
-cert's fingerprint, the result of a live `GET /v1/health` call against itself (using its own pinned
-cert, not a system CA — see **Security model** below), the currently-held grants
+cert's fingerprint, `certExpiry` (`{validTo, daysLeft, expiringSoon}`, `null` with no readable cert;
+`expiringSoon` is true within 30 days of `notAfter` or after it, and then a `warning: the agent's
+certificate ...` line goes to stderr), the result of a live `GET /v1/health` call against itself (pinned
+to the cert's fingerprint and nothing else: not a system CA and not the validity dates, so an expired
+cert still answers and `certExpiry` is where the expiry shows — see **Security model** below), the currently-held grants
 (`{revision, plugins: <count>} | null`, from `grants.json` — `null` when it is absent or malformed,
 the same as a freshly-purged or never-pushed-to agent), the effective `reposRoot` and a live
 `reposCount` computed from the same immediate-child, `.git`-entry, realpath-contained listing as
-`GET /v1/repos` (a missing or unreadable root is zero), and `virtualized: true/false` (#263) — `true`
+`GET /v1/repos` (a missing or unreadable root is zero), `unreadable` (`{file: error code}` for any file status could not read, `{}` normally), and `virtualized: true/false` (#263) — `true`
 when this session's own AppData writes to the resolved config/state dirs are virtualized by a
 packaged app (see **Run install from a normal shell** above), which also prints a `warning: this
 session's AppData is virtualized (<packageFamily>); the logon task cannot see <stateDir> -- see
@@ -314,7 +434,7 @@ url:         <this machine's URL>
 fingerprint: <cert fingerprint>
 ```
 
-The code is 8 characters from an alphabet that excludes ambiguous glyphs (`0`/`O`, `1`/`I`/`L`, easy
+The code is 8 characters from an alphabet that excludes ambiguous glyphs (`0`/`O`, `1`/`I`, easy
 to misread off a small screen or mishear read aloud) and expires in **10 minutes**; only its hash is
 ever written to disk (`<stateDir>/pair.json`). Refuses with `already paired -- pass --force to
 re-pair (mints a fresh code)` if a token is already stored — `--force` starts a fresh pairing
@@ -326,8 +446,17 @@ attempt never wins a race against a still-valid one. Requires a certificate to a
 ui.tsx`) and fill in the pairing form with the three printed values plus an optional machine name:
 URL, Fingerprint, Code, Name. Submitting calls `POST /api/agents` — success adds the machine to the
 paired list; the console then reaches it, per capability, once an operator grants that capability to
-a plugin for it in the same panel's Grants grid (see **Security model** below — nothing runs until a
-capability is both declared by the plugin and granted here).
+a plugin for it in the same panel's Grants grid (see **Security model** below — no verb runs until a
+capability is both declared by the plugin and granted here; the control-plane routes, `PUT /v1/grants`,
+`GET /v1/preflight`, and `POST` and `GET /v1/update`, need no grant).
+Every other POST verb answers `413 {ok:false,error:"request body too large"}` above 64 KiB; publish,
+toolchain-upgrade and `exec/gh` (512 KiB, for one 64 KiB `--body`) keep their own larger caps.
+
+**Unpairing** (the Agents panel's Unpair, `DELETE /api/agents/:id`) is local to the console: it forgets the
+machine and its grants and makes no call to the agent, which keeps its stored token hash and keeps accepting
+the token. To cut that credential off, run `pair --force` on the machine and pair it again from the console
+(the old token stops working once the new code is consumed), or `uninstall`, which removes the token hash. A
+copy of the console's `/state/ac.db` taken before the unpair still holds the old token in clear.
 
 ## Uninstall
 
@@ -345,6 +474,17 @@ the machine's chosen port/name.
 except for debugging. `stop`/`start` control the registered service (`Stop-`/`Start-ScheduledTask`
 or `systemctl --user stop/start`) without touching the registration itself.
 
+**The lock.** `agent.pid` is taken with `O_EXCL`. A pid left by an unclean exit (a Windows logoff or
+reboot runs no shutdown handler) is replaced when it is this process's own pid, is not a valid pid, or
+is not running. It is also replaced when nothing answers `/v1/health` on the configured port with this
+machine's own certificate, which is pid reuse. A start is refused only while that pinned answer names a
+running agent. Both outcomes are written to `agent.log`, as `replaced stale lock (pid N, <why>)` or
+`already running (pid N, port P)`. `GET /v1/health` carries the answering agent's `pid` for this.
+
+`stop`, `uninstall` and an install's restart kill only the pid that pinned answer names. When nothing
+answers they kill nothing and remove the stale `agent.pid`, and they print `... nothing was killed` if
+that pid belongs to some other live process.
+
 ## Config and state directories
 
 | | Windows | Linux |
@@ -375,7 +515,8 @@ claude_projects_dir = "C:/Users/melody/.claude/projects"
 
 Unknown keys are ignored, so a future field never breaks an older agent reading a newer file.
 `repos_root` is overridable live with `AC_AGENT_REPOS_ROOT` the same way `port` is with
-`AC_AGENT_PORT` — absolute paths only; a relative override throws, naming the value.
+`AC_AGENT_PORT` (which, unlike the file's `port`, is not range-checked: it is read as an integer and a value
+it cannot read is ignored) — absolute paths only; a relative override throws, naming the value.
 `claude_projects_dir` (#52, 52a; default `<homedir>/.claude/projects`) is handled identically, with
 its own live override `AC_AGENT_CLAUDE_PROJECTS_DIR` — it names the root the `context-pressure` and
 `subagent-cost` scans read, overridable so a fixture tree or a non-default `CLAUDE_CONFIG_DIR`
@@ -447,8 +588,8 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
 - **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
+  absolute if PATH gave a relative entry (`exec/claude` and `exec/gh` resolve their tool on the same refreshed PATH, #716, and `exec/claude`
+  also makes its path absolute, 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
@@ -500,9 +641,14 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
     figure at list rates (never money actually spent — this box runs Claude Code on a
     subscription). Both read exactly six fields per transcript record (`type`, `subtype` /
     `attributionAgent`, `timestamp`, `cwd`, `message.{id, model, usage}`); `message.content` --
-    prompts, tool results, file contents -- is never deserialised, by either scan. The cache lands
+    prompts, tool results, file contents -- is parsed in memory with the rest of the line but never read or kept, and never leaves the process, in either scan. The cache lands
     at `<stateDir>/scans/context-pressure.json` / `<stateDir>/scans/subagent-cost.json`, created on
-    first write and removed by `uninstall` regardless of `--purge`.
+    first write and removed by `uninstall` regardless of `--purge`. Beside each cache sits a
+    `<kind>.tables` file holding a digest of the tables its rows were computed from (the context
+    windows; the prices and cache multipliers). A cache whose digest differs, or that has none, is
+    dropped and every transcript re-parsed, and a row naming an unmapped (context-pressure) or
+    unpriced (subagent-cost) model is re-parsed on every scan, so adding the model to the table
+    fixes its rows without a manual cache delete.
   - **`memory-footprint`** (#52, 52b; no custom `timeoutMs` -- a cold run is kilobytes of I/O, not
     the transcript-scale reads above) is a producer only, computed live on every request and never
     cached: the fixed 8-layer set Claude Code assembles into a session's preamble (`enterprise`,
@@ -513,7 +659,14 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
     `repos_root` with a `.git` entry) -- unlike 1.x, which read the console's configured repo list,
     so the payload's `repo` and `name` fields are both the directory name, never an `owner/name`
     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.
+    sizes and line counts ever leave this scan -- file content is never read into the payload. Every
+    layer file is `lstat`ed first: a layer file or the rules directory itself that is a symlink,
+    anything that is not a regular file, or a file over 1 MiB is skipped as if absent; inside the rules
+    directory, symlinked files and directories are not followed, and the walk goes at most 8
+    directories deep, so a hostile checkout cannot point a layer at `/dev/zero`, a FIFO or a huge
+    file. Accepted limitation: a skipped layer is silent and reads as absent (the payload has no field
+    for it), so a dotfiles-managed `~/.claude/CLAUDE.md` that is a symlink, or any layer file over
+    1 MiB, is undercounted.
   - **`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 byte for byte from 1.x
     `main` at `da0848f`, `data/README.md`) through `pwsh -NoProfile -File <script> -OutFile <state>/scans/
@@ -545,11 +698,14 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   (a 404 before anything spawns); `prompt` is a non-empty string, at most 8 KiB (the Windows
   `CreateProcess` command-line limit is 32,767 characters total, and quoting can double a prompt's
   own backslashes and quotes — 8 KiB leaves headroom for the fixed flags and the repo path in the
-  worst case) with no control character other than `\n`/`\t`; `permissionMode` is one of `plan`
+  worst case) with no control character other than `\n`/`\t`, and not starting with `-` (`400 prompt must
+  not start with '-'`: `claude` would read it as a flag); `permissionMode` is one of `plan`
   (the default) / `acceptEdits` / `bypassPermissions`; `model` is an optional
   `^[A-Za-z0-9._-]{1,64}$` string. Any other shape is `400` before anything spawns. `claude` runs as
   `claude -p <prompt> --permission-mode <mode> --add-dir <repo path> [--model <model>]`, `cwd` the
-  resolved repo. **At most 4 `claude` jobs run at once** — a 5th concurrent request is
+  resolved repo. `claude` is looked up on the refreshed PATH (the registry's on Windows, the process PATH
+  elsewhere), and the job runs with that PATH, so a `claude` installed after the agent started is found
+  without a restart (#716). **At most 4 `claude` jobs run at once** — a 5th concurrent request is
   `429 {ok: false, error: "too many running jobs"}`, checked before spawning, not after. Only `claude`
   jobs count: a running toolchain upgrade (#675) neither uses up a slot nor is blocked by a claude job.
 - **`GET /v1/jobs`** (`agent.exec.claude`) → `{ok: true, jobs: [view...]}`, newest first.
@@ -573,10 +729,19 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
 ### `POST /v1/exec/gh`
 
 - **`POST /v1/exec/gh`** (`agent.exec.gh`), body `{args: string[]}` → `200 {ok: true, code, stdout,
-  stderr, truncated}` (stdout/stderr each capped at 1 MiB, `truncated: true` when either was cut). A
-  non-zero `gh` exit is still a `200` — the caller reads `code`. At most 32 arguments, each at most
-  4 KiB with no control characters, except a `--body` value (`--body <text>` or `--body=<text>`),
-  which may be up to 64 KiB and contain `\n`/`\t` (a PR/issue comment body).
+  stderr, truncated}` (stdout/stderr each capped at 1 MiB, `truncated: true` when either was cut or when
+  collection stopped at the cap, which also kills `gh`). A non-zero `gh` exit is still a `200` — the
+  caller reads `code`; a `gh` that cannot be launched answers `code: 127`. At most 32 arguments, each at
+  most 4 KiB with no control characters. Only a `--body` value (`--body <text>` or `--body=<text>`) may
+  be longer, up to 64 KiB (24 KiB on Windows, where the command line is limited) and contain `\n`/`\t`
+  (a PR/issue comment body); any other flag's value, `--search=<text>` included, is held to the 4 KiB and
+  no-control-character rule.
+- **The `gh` child gets an allowlisted environment, not the agent's** (#714): `PATH` (the refreshed PATH `gh` was
+  looked up on, #716), the per-OS profile/temp/locale keys, proxy and `SSL_CERT_*` keys, `GH_HOST` and `GH_CONFIG_DIR`, plus
+  `GH_PROMPT_DISABLED`, `GH_NO_UPDATE_NOTIFIER` and `NO_COLOR`. `GH_TOKEN`, `GITHUB_TOKEN`,
+  `GH_ENTERPRISE_TOKEN` and `GITHUB_ENTERPRISE_TOKEN` are deliberately left out, so `gh` takes its
+  credential from `gh auth login` on the machine. A `--jq` program that names the environment
+  (`env`, `$ENV`) is refused `400 invalid value for --jq: ...` before anything spawns.
 - **Every argument is checked against a fixed allowlist before anything spawns** — an unlisted
   subcommand, flag, or malformed positional is `400 {ok: false, error: "<token and why>"}`, logged as
   `gh refused: <error>`, additive-only (nothing here is ever loosened without a deliberate change to
@@ -631,12 +796,13 @@ pulling from the console (the console sits behind Cloudflare Access, which an ag
 Body `{files: [{href, base64}], wanted: string[], pdf: boolean, prune: boolean}` — `files` at most
 1000 entries, each `href` a relative POSIX path (no empty/`.`/`..` segment, no drive/UNC anchor)
 ending `.html`, `base64` a valid base64 string, decoded total at most 48 MB (a request body over
-~66 MB is rejected by the route's own raised body-size cap before JSON parsing even runs, `413
+~66 MB is rejected by the route's own body-size cap (larger than the 16 KiB cap on the pair, grants and update routes) before JSON parsing even runs, `413
 {ok: false, error: "request body too large"}`); `wanted` an array of such hrefs (every html href the
 caller currently wants mirrored, not just the changed ones in `files`); `pdf`/`prune` booleans. `409
 {ok: false, error: "publish target not configured"}` when `publish_dir` is unset (most paired
 machines — a Linux box has no OneDrive). One run at a time: `409 {ok: false, error: "publish already
-running"}`.
+running"}`, which also answers while an earlier request is still sending its body (the guard is taken
+before the body is read, so a client that opens a request and never finishes it holds it for other callers).
 
 - **HTML**: each file's bytes are compared against what's on disk (size, then sha256) — unchanged
   bytes are never rewritten (OneDrive re-uploads every rewrite); a changed or new file is written to
@@ -809,7 +975,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`** (`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` |
+| `cmd` | the tool whose `--version` is read before and after; found with `which`, run for nothing else | one of **`git`, `gh`, `node`, `claude`, `docker`, `cloudflared`** (`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. `docker` and `cloudflared` (#828) are accepted but **deferred** to the next 05:00 America/New_York, because upgrading either can restart the host's containers or tunnels (#978; see **Deferred upgrades** below). 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`) |
 
@@ -836,7 +1002,7 @@ here). It still installs the new dependencies the upgrade needs (`apt-get(8)`).
 The worst a hostile console can do with a valid request is upgrade an installed package the operator
 did not mean, with the new dependencies that upgrade needs (never removing a package). Apart from the
 package id, the one thing the request names is `cmd`, and it can only pick
-one of the four tools above to run `--version` on (never a program of its choosing); it cannot install
+one of the six tools above to run `--version` on (never a program of its choosing); it cannot install
 or run anything else from the request's text. The verb does not tie `cmd` to `packageId`: `cmd` only says
 whose version is read, so a request naming `git` with another package's id reports the status of git's
 version. The audit lines name `cmd` for that reason. For `apt` the package must also **be an installed
@@ -854,6 +1020,26 @@ counts an upgrade that has passed its check but not yet started its job. A tool
 (`winget`, `sudo`, `dpkg-query`, `cmd`) is `502 {ok: false, error: "<name> not found on PATH"}`. A running
 claude job does not count against it, and it does not count against the claude cap.
 
+**Deferred upgrades (#978).** When `cmd` is `docker` or `cloudflared` (`DEFERRED_CMDS`), on every
+platform, the answer is `202 {ok: true, jobId, scheduledFor}` with `scheduledFor` the ISO time of the next
+**05:00 America/New_York** strictly after the request (a request at 05:00:30 runs at 05:00 the next day).
+The window is wall-clock time in that zone, so it follows the daylight-saving change; the zone changes its
+clocks at 02:00, so 05:00 always exists and is never ambiguous. Why: the upgrade restarts the Docker
+daemon and its containers (the console's included; they come back through `restart: unless-stopped`,
+`deploy/compose.yaml.example`), or the cloudflared tunnels the console is reached through. The agent runs
+outside Docker, so it survives both, and it owns the schedule rather than the console. The request-time
+refusals are the usual ones (`400`, `502`, the cap) and come before any job exists; the version is read
+at fire time. The job exists at once, in status `running`, with a `scheduled: runs at ...` line, and it
+holds the one upgrade slot: a second request is `429 {ok: false, error: "an upgrade is already scheduled
+on this machine for <ISO time>"}`, and `POST /v1/update` is refused (`409 jobs running`) like for any
+running job. At 05:00 the agent repeats the PATH refresh, both lookups, the version read and, for `apt`,
+the installed-package check (the machine may have changed overnight); if one now fails, the job finishes
+`failed` with that reason as its outcome. A machine that slept through the window and wakes more than 90
+minutes late does not run it then: the job moves to the next 05:00 (job-log line `missed its window;
+rescheduled`, audit line `toolchain upgrade rescheduled: ...`). The schedule lives in the agent's memory: **an agent restart
+before 05:00 drops it**, and the `toolchain upgrade scheduled:` audit line is the record. There is no "run
+now" override and no per-machine time yet (#978, later chunks).
+
 **The job.** The answer is `202 {ok: true, jobId}` and the upgrade runs as a job (`kind:
 "toolchain-upgrade"`, `repo` the manager, `permissionMode` empty, `label` `<tool> via <manager>
 <packageId>`) because `apt` and `winget` outlast the host's 30 s body budget. It is killed after **15
@@ -893,7 +1079,8 @@ answered within 25 seconds is `missing`, and its output is bounded at 64 KiB.
 kind's jobs, and one holding only `agent.exec.claude` never reads these):
 
 - **`GET /v1/toolchain/upgrade/:jobId`** → `{ok: true, job: <view>, outcome?: {status, reason?, before,
-  after}}`; `outcome` is present once the agent has worked the outcome out, when the command is over (a
+  after}, scheduled?: {runAt, waiting}}`; `scheduled` is present for a deferred job (`waiting: true` until
+  the agent has spawned it, `false` after; #978); `outcome` is present once the agent has worked the outcome out, when the command is over (a
   job whose launch threw has none: its request was a `500` that returned no job id). `404 no such job` for
   an unknown id or another kind's.
 - **`GET /v1/toolchain/upgrade/:jobId/events`** → the same Server-Sent Events as `/v1/jobs/:id/events`
@@ -920,7 +1107,9 @@ desktop (the agent is a logon task in that session) that the agent cannot answer
 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 that is not closing advice.
 
-**Audit.** Two lines in the agent log per run: `toolchain upgrade started: "<tool>" via <manager>
+**Audit.** Two lines in the agent log per run (a deferred one first logs `toolchain
+upgrade scheduled: "<tool>" via <manager> <packageId> at <ISO time> (version of <cmd>)`, #978):
+`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),
 and, when it finishes, `toolchain upgrade: "<tool>" via <manager> <packageId>: <before> -> <after> (<status>,
 exit <code>, version of <cmd>)`. The tool key is console-supplied, so it is printed in quotes (its
@@ -938,9 +1127,9 @@ ones on a terminal) is written as `\xNN`, and so are U+2028 and U+2029 (which Py
 most editors break lines on) and the explicit bidirectional embeddings, overrides and isolates
 U+202A-202E and U+2066-2069 (which reorder text), as `\uNNNN`. So a request path cannot forge or split an
 audit line, or reorder one with an explicit bidi control; the implicit marks U+200E, U+200F and U+061C
-are passed through and can only reorder neutral characters within the line. The log is rotated only when `serve` starts (one previous
-file is kept, overwritten at the next rotation), and a failed write is dropped, so a run is on record
-for as long as that file is, not for ever.
+are passed through and can only reorder neutral characters within the line. The log is rotated to `agent.log.1` once it passes 1 MiB, checked when it is opened and on every write (one previous
+file is kept, overwritten at the next rotation), a logged request path is cut at 200 characters, and a failed write
+or rotation is dropped rather than failing the request, so a run is on record for as long as that file is, not for ever.
 
 ### Operator setup
 
@@ -1021,6 +1210,26 @@ query` (Windows) or `xdg-mime query` (Linux) is ever run.
   restarted agent holds no answer until its first conclusive detection, so a probe landing in that
   window stores "unknown".
 
+## Machine identity (#914)
+
+The console is moving to treat a machine as its **OS machine id** (#914): a changed id is a different
+machine. This agent reports the id so the console can recognise a re-pair from the same machine; what the
+console does with it is a separate change (AM5, #914), not part of this one. The agent reads the id once,
+at `serve` start:
+
+- **Linux:** the first non-empty line of `/etc/machine-id`, else of `/var/lib/dbus/machine-id`, if it is 32
+  hex characters (a first-boot `uninitialized` placeholder is not an id).
+- **Windows:** `MachineGuid` from `reg.exe query HKLM\SOFTWARE\Microsoft\Cryptography /v MachineGuid`
+  (readable without elevation; 5 s limit), if it is a GUID.
+- **Anything else, or any failure:** no id; the agent reports none and the console decides by certificate
+  as before.
+
+**Only a hash leaves the machine**: HMAC-SHA256 of the lower-cased id under the key
+`ac-agent/os-machine-id/v1`, as 64 lowercase hex characters, in the field `osMachineId`. It is answered by
+`POST /v1/pair` and, to a caller with a valid bearer token only, by `GET /v1/health`; an unauthenticated
+health caller never sees it. The field is omitted when there is no id. `apiVersion` is unchanged (additive
+field; an older console ignores it).
+
 ## Preflight
 
 **`GET /v1/preflight`** (#55): control plane, like `PUT /v1/grants` -- bearer-gated, no capability,
@@ -1044,8 +1253,8 @@ The `docker` and `cloudflared` rows (#828) are two of the fleet standard's tools
 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`.
+panel grades them there and offers an Upgrade: `POST /v1/toolchain/upgrade` accepts both as a `cmd` and
+defers the run to the next 05:00 America/New_York (#978).
 
 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
@@ -1068,7 +1277,9 @@ free text (a `broken` row's last non-empty output line, `unauthenticated`'s
   `System32` path) so a tool installed after the agent's logon task started is still seen; on
   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"`.
+  `searchPath` on the report names which: `"registry"` or `"process"`. `exec/claude`, `exec/gh`, the repo
+  verbs and the toolchain upgrade search the same PATH (#716, #699, #675), so a row the panel reads as
+  `ok` is a tool those verbs find.
 - **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.
@@ -1099,6 +1310,11 @@ software is never something a grant could hand to a plugin.
 3. **Downloads the tarball** (60 s timeout) and refuses it over 20 MB or unless its sha512 matches.
    A declared `content-length` over the cap is refused before reading. Without one, the body is read
    in full and then checked, so only the timeout bounds that read.
+   **Trust model:** the sha512 compared is the `dist.integrity` the same registry answered in step 2, so
+   it catches a corrupted or swapped tarball but not a malicious publish. No npm registry signature or
+   provenance is checked, so a hostile `@rackbops/ac-agent` release (a compromised npm account or token)
+   would pass these steps and, once an operator clicks Update, run as the privileged per-machine daemon.
+   That is the same trust as the first `npx @rackbops/ac-agent install`.
 4. **Reads only `package/dist/ac-agent.mjs` and `package/package.json` out of it,** in memory,
    refusing an archive that unpacks past 100 MB. No path from the archive is ever written.
    `package.json` must name the same package and version.
@@ -1142,10 +1358,10 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
 ## Security model
 
 - **HTTPS only**, with a self-signed certificate generated once at install (RSA 2048, SHA-256,
-  10-year validity; SAN covers the machine's hostname, every non-internal IPv4 address, and
-  `127.0.0.1`).
+  10-year validity; SAN covers the machine's hostname, the machine's LAN-preferred IPv4 addresses
+  (virtual and tunnel interfaces skipped unless nothing else exists), and `127.0.0.1`).
 - **`GET /v1/health` and `POST /v1/pair` are the only unauthenticated routes.** `/v1/health` answers
-  `{ok, version, apiVersion, machine, paired, capabilities, grantsRevision, claudeDesktop?}` — enough
+  `{ok, version, apiVersion, machine, paired, capabilities, grantsRevision, claudeDesktop?}` (plus `osMachineId` for a valid bearer only, #914; see **Machine identity**) — enough
   for a caller to discover what it's talking to before pairing, nothing that requires trust.
   `grantsRevision` is `null` before this agent has ever received a `PUT /v1/grants` (or if
   `grants.json` went missing). `claudeDesktop` (present only once the agent holds a conclusive
@@ -1157,9 +1373,9 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
 - **`POST /v1/toolchain/upgrade` is the one verb that installs software** (#675), so it is behind two
   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: 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
+  id (the one other program a request can name, `cmd`, is limited to six tools whose `--version` the
+  preflight already runs: an explicit list, so a new preflight row is not on it; `docker` and
+  `cloudflared` are, and their upgrade is deferred to 05:00 America/New_York, #978), 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
@@ -1208,9 +1424,9 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
   **`rejectUnauthorized: false` is not a pin by itself, and pairing it with `checkServerIdentity`
   doesn't make it one:** verified directly against this Node version that `checkServerIdentity` is
   never invoked at all once `rejectUnauthorized` is false — the whole verification pathway is
-  skipped, so a "pin" layered on top of it is dead code, not an additional check. (Holding the
-  actual certificate PEM in hand — which this package's own CLI does, reading its own on-disk
-  `cert.pem` for its `status` self-check — is a different, legitimate case: `ca: <PEM>` with the
-  default `rejectUnauthorized: true` validates the chain and keeps `checkServerIdentity` live. A
-  pairing console never has that PEM, only the fingerprint, so it needs the explicit-compare shape
-  above.)
+  skipped, so a "pin" layered on top of it is dead code, not an additional check. This package's own
+  CLI uses the same explicit-compare shape (`src/pin.ts`, with a 10 s handshake and response budget) for
+  its `status` and install self-checks, although it holds its own `cert.pem`: `ca: <PEM>` with the
+  default `rejectUnauthorized: true` is not used, because a self-signed cert past its `notAfter` fails
+  chain validation (CERT_HAS_EXPIRED) and would report a healthy agent as down. The expiry is
+  `status`'s `certExpiry` to report.