@rackbops/ac-agent 2.0.0-alpha.59 → 2.0.0-alpha.62

package/README.md

@@ -264,6 +264,101 @@ 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 and paired
+(#826, 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 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 to `agents`: no `agent.exec.*`, `agent.git.*` or `agent.scan.*`.
+
+nucbox additionally grants `agent.tunnel.lint` to the `admin` plugin, and nothing else (the owner's Grants
+screenshot, 2026-10-20).
+
+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
@@ -353,8 +448,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
 
@@ -381,7 +485,9 @@ running agent. Both outcomes are written to `agent.log`, as `replaced stale lock
 
 `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.
+that pid belongs to some other live process. When the pinned answer has no `pid` (an agent older than
+alpha.59), they refuse and name the port and version instead of killing nothing. An install also
+refuses to start while the port still answers after the stop.
 
 ## Config and state directories
 
@@ -486,8 +592,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
@@ -601,7 +707,9 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   (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.
@@ -632,8 +740,8 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   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 per-OS
-  profile/temp/locale keys, proxy and `SSL_CERT_*` keys, `GH_HOST` and `GH_CONFIG_DIR`, plus
+- **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
@@ -1106,6 +1214,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,
@@ -1153,7 +1281,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.
@@ -1235,7 +1365,7 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
   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