@rackbops/ac-agent 2.0.0-alpha.33

package/README.md

@@ -0,0 +1,683 @@
+# @rackbops/ac-agent
+
+The per-machine host agent for [artifact-console](https://github.com/Rackbops/artifact-console): a
+small HTTPS server, paired to a console over a token, that lets it reach one dev machine's
+`claude`/`git`/`gh` and file system through an allowlisted verb API. Console-initiated pairing (a
+one-time code exchanged for a per-machine token, #48), `repos` list/status/pull and `open` (#49,
+49a), `exec/claude` (with the job registry and its SSE log) plus `exec/gh` (#49, 49b), and the
+`context-pressure` / `subagent-cost` session-log scans (#52, 52a), and `memory-footprint` /
+`toolchain-inventory` (#52, 52b) are all live -- every `scan/:kind` kind #52 planned has landed.
+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**.
+
+## Install
+
+```sh
+npx @rackbops/ac-agent install
+```
+
+During the prerelease period, install the newest prerelease explicitly with the `next` dist-tag
+(`npx @rackbops/ac-agent@next install`) -- `release.yml`'s publish step tags every `-alpha.N`/
+`-beta.N`/`-rc.N` version `next` from here on (#269), since npm refuses a plain `npm publish` of a
+prerelease version with no explicit `--tag`; a stable version still publishes under `latest`. The
+very first publish (`2.0.0-alpha.8`, #268) was done by hand under `--tag alpha` before this existed
+-- and because it was the package's first version ever, npm *also* pointed `latest` at
+`2.0.0-alpha.8` (npm's own first-publish behaviour, not a deliberate choice here). So right now a
+bare `npx @rackbops/ac-agent install` (no tag) resolves to `alpha.8`, with `alpha` and `latest` both
+still pointing at it; `next` starts moving with the next prerelease tag, and `latest` only moves
+again once a real stable version is published.
+
+### Upgrade with the Tooling script
+
+For an existing install, an up-to-date Tooling checkout provides
+[`Update-AcAgent.ps1`](https://github.com/Rackbops/Tooling/blob/main/PowerShell/Update-AcAgent.ps1)
+and its sibling helpers, including `Resolve-GhExe.ps1`. These examples assume the PowerShell session
+is at the root of that checkout:
+
+```powershell
+# Local Windows agent, explicit release
+& .\PowerShell\Update-AcAgent.ps1 -Local -Version 2.0.0-alpha.31
+
+# Newest release carrying its matching agent tarball, including prereleases
+& .\PowerShell\Update-AcAgent.ps1 -Local -Version latest
+
+# Linux targets reached from this PowerShell session
+& .\PowerShell\Update-AcAgent.ps1 -Linux 'user@host-a,user@host-b' -Version 2.0.0-alpha.31
+
+# Preview the same Linux operation
+& .\PowerShell\Update-AcAgent.ps1 -Linux 'user@host-a,user@host-b' -Version 2.0.0-alpha.31 -WhatIf
+```
+
+The updater downloads the matching release tarball once into a fresh temporary directory. A selected
+target already serving that version skips installation. Other targets are read before and after the
+install, including the endpoint version and served-certificate fingerprint; Linux also checks that
+the user service is active. Target failures are independent, and any failure makes the script exit
+nonzero. Temporary-file cleanup is attempted at the end. If the before endpoint was stopped or
+unreadable, there is no fingerprint to compare, so the run cannot verify that it stayed unchanged.
+
+`-WhatIf` is a non-mutating preview, not a zero-I/O mode: it still queries releases, downloads the
+tarball, and reads target health, but runs no install, `scp`, or mutating SSH command.
+
+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.
+
+### Linux: no special `npx` spelling needed (#278)
+
+The plain `npx @rackbops/ac-agent[@next] <verb>` line above is the one spelling that works on Linux
+regardless of npm version -- confirmed on Ubuntu 26.04 with both npm 11.19 and npm 12.0.2. `#278` was
+originally filed as an npm-11-vs-12 `npx` regression (alpha.9 silently printing `npm notice run` and
+exiting 0 with no verb output on a npm 12 box), but the real cause was narrower and applied to *every*
+npm version on Linux: `dist/ac-agent.mjs`'s own entry-point guard compared `import.meta.url` (always
+the symlink-resolved real path) against a **raw, unresolved** `process.argv[1]`. npm's
+`node_modules/.bin/<name>` bin link is a real filesystem symlink on Linux (whether reached via `npx`
+or `npm install -g`), so the two paths never matched, `main()` never ran, and the process exited `0`
+having done nothing -- on npm 11 *and* npm 12 alike. Windows never showed this: npm links a bin there
+with a `.cmd`/`.ps1` shim that invokes `node "<real path>" ...` directly, so `argv[1]` was already the
+real path. Fixed by resolving `argv[1]` through `realpathSync` before comparing (`isEntryPoint` in
+`src/cli.ts`) -- no `--yes`, `--package=`, or `--` flag is needed or helps; none of those spellings
+touch the actual bug. Requires a published release built with this fix (past `2.0.0-alpha.26`); any
+prerelease at or before that still silently no-ops on Linux the same way.
+
+Registers a Windows Task Scheduler task (`\ClaudeLocal\ac-agent`, a logon trigger for the current
+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
+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
+<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
+install, `--name` and `--port` remain intentionally ignored and print the configured value they
+kept; platform registration and restart checks use that existing port. If
+`AC_AGENT_REPOS_ROOT` is non-blank and differs from an explicitly saved `--repos-root`, install
+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
+launches a process can report success before that process has actually started listening) before
+printing `restarted: now serving <version>`. If the restart fails outright, or the health check
+never comes back healthy, the install is still reported as a success — the printed line is
+`restart failed: <reason>; run ac-agent stop && ac-agent start`, and that manual sequence is the
+fallback. A fresh install, with nothing running yet, prints neither line.
+
+### The firewall step
+
+`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
+shell — it is not a failure to work around.
+
+### Run install from a normal shell
+
+The Claude desktop app is an MSIX package (`Claude_<hash>`, e.g. `Claude_pzs8sxrjxfjjc`). A Claude
+Code session it starts — and every process that session spawns, including a PowerShell/Bash tool
+shell running `npx @rackbops/ac-agent install` — inherits the package identity, and MSIX
+**virtualizes AppData**: a write to a subfolder of `%LOCALAPPDATA%`/`%APPDATA%` is silently
+redirected into the package's private `...\Packages\<pkg>\LocalCache\Local\...`/
+`...\LocalCache\Roaming\...`, while the writing process itself believes it wrote the real path.
+`install` writes the bundle copy, `launch.js`, the cert and `agent.toml` under the state/config
+dirs, so run from such a session those files land somewhere the Windows logon task — launched later
+with the user's real, unpackaged token — can never see, and the task exits `1` at once (#263).
+`install` detects this (a nonce probe file, not just the presence of an old package copy, so a stale
+VFS leftover from a prior virtualized install never blocks a later normal one) and refuses with:
+
+```
+install ran inside a packaged app (<packageFamily>), which virtualizes AppData: the files landed
+under <vfsPath> where the logon task cannot see them. Run ac-agent install from a normal PowerShell
+window, not from a session started by the Claude desktop app.
+```
+
+Run `install` from a normal PowerShell window opened from the Start menu, not from a Claude Code
+session the desktop app started. `status`/`serve` don't refuse the same way (see **Status** and
+**serve / stop / start** below) — a `serve` launched from a virtualized session still works, since
+everything it reads and writes goes through the same virtualized view within that one session; it's
+only a *task* launched later, outside that session, that can't see the files.
+
+### Linux
+
+Run `install` as the **login user you'll actually use the agent as, never `root`**. As root there is
+no user session bus for the `systemd --user` unit to register against —
+`loginctl show-user`/`systemctl --user` calls fail with `Failed to connect to user scope bus via
+local transport: $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined` — and a root install
+would in any case put the config/state under `/root`, where the operator's own shell never looks.
+
+A `systemd --user` unit only survives past that user's login session — logout, or a reboot — if
+**lingering** is enabled for that user:
+
+```sh
+sudo loginctl enable-linger "$USER"
+```
+
+This can be run before or after `install`; order doesn't matter, because it governs the **user
+manager's** lifetime (whether `systemd --user` keeps running with no session attached), not the
+`ac-agent.service` unit itself. Without it, the user manager — and the agent with it — stops the
+moment the last session for that user ends.
+
+The unit's HTTPS listener isn't up the instant `install` returns — a `curl` fired immediately can
+race the bind and report a false failure. Wait a moment, then check:
+
+```sh
+curl -k https://127.0.0.1:8788/v1/health
+```
+
+### Windows: no console window
+
+The task's action is `wscript.exe //B "<launch.js>"` against a small generated JScript launcher
+(written into the state dir alongside the bundle copy), not a bare `node` invocation and not
+`conhost.exe --headless` (an earlier design that turned out to run nothing at all — verified live,
+`conhost.exe` isn't a generic headless-launch wrapper). `launch.js` runs
+`WScript.CreateObject("WScript.Shell").Run("<node> <bundle> serve --config-dir <abs> --state-dir
+<abs>", 0, true)` in a loop (the two dirs `install` itself resolved, baked in the same way
+`<node>`/`<bundle>` already are — see **Config and state directories** below), retrying on a crash.
+Window style `0` keeps node's console from ever appearing (Node has no `nodew.exe`, the
+`pythonw.exe`-equivalent 1.x used), and waiting (`true`, not fire-and-forget) keeps `wscript.exe`
+itself alive as the task's tracked process for the agent's entire lifetime, so the task reads
+Running while serving and a crash propagates as a non-zero exit, visible afterward as
+`LastTaskResult`. **`RestartCount 3` does not actually restart a crashed agent** — verified live (two
+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
+`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
+after `stop`. Verified live: killing node by pid left the task Running with a fresh node pid
+listening within about a minute; `stop` afterward left the task `Ready` with `LastTaskResult 267014`
+(0x41306, terminated by user) and nothing listening 150 s later. The launcher is JScript rather than
+VBScript specifically because
+VBScript is a Windows feature-on-demand Microsoft is phasing out (Insider builds first); JScript and
+Windows Script Host itself carry no such notice, so the same mechanism ships without a deprecated
+component in the loop. (A PowerShell hidden launcher — `Start-Process -WindowStyle Hidden -PassThru
+-Wait` — was also tried and verified working, but was dropped in favor of keeping Windows Script
+Host as the only script host involved.) One thing this package cannot verify by itself — no CI
+runner can register a real logon task — is named as unverified rather than assumed: whether any
+window is visible at a real logon.
+
+## Status
+
+```sh
+npx @rackbops/ac-agent status
+```
+
+Prints, 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
+(`{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`
+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
+README, Install` line to stderr. `serve` logs the same warning line once at startup, in the same
+circumstance, without refusing to start.
+
+## Pair
+
+```sh
+npx @rackbops/ac-agent pair [--force]
+```
+
+Generates a one-time pairing code and prints exactly three lines:
+
+```
+code:        <8-char code>
+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
+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
+without discarding the old token until the *new* code is actually consumed, so a stale in-flight
+attempt never wins a race against a still-valid one. Requires a certificate to already exist
+(`install` always creates one); refuses with `no certificate found -- run install first` otherwise.
+
+**On the console side**, open its Admin → Agents panel (the `agents` plugin, `plugins/agents/src/
+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).
+
+## Uninstall
+
+```sh
+npx @rackbops/ac-agent uninstall [--purge]
+```
+
+Stops and unregisters the task/unit, removes the copied bundle, cert, key, token hash, pending-pair
+file, grants and lock file. Keeps `agent.toml` unless `--purge` is given, so a re-install remembers
+the machine's chosen port/name.
+
+## serve / stop / start
+
+`serve` is what the registered task/unit actually runs — it isn't meant to be invoked directly
+except for debugging. `stop`/`start` control the registered service (`Stop-`/`Start-ScheduledTask`
+or `systemctl --user stop/start`) without touching the registration itself.
+
+## Config and state directories
+
+| | Windows | Linux |
+|---|---|---|
+| Config (`agent.toml`) | `%APPDATA%\ac-agent\` | `~/.config/ac-agent/` |
+| State (cert, key, token hash, grants, log, pid, the installed bundle copy) | `%LOCALAPPDATA%\ac-agent\` | `~/.local/state/ac-agent/` |
+
+Both are overridable with `AC_AGENT_CONFIG_DIR` / `AC_AGENT_STATE_DIR` — **absolute paths only**; a
+relative override throws, naming the value. `install` resolves these once, in its own process, and
+bakes the resolved absolute paths into the registered task/unit as `serve --config-dir <abs>
+--state-dir <abs>`, the same way it already baked in the node/bundle paths — rather than relying on
+`serve` to re-resolve them from its own environment when the task/unit actually runs. This matters
+because a Task Scheduler process (and a systemd `--user` unit) is a separate process tree that does
+not see the installing shell's variables — transient or persisted — so before this, an install under
+the overrides silently served from the real platform defaults instead, with a different certificate
+and the default port (E4 finding 13, fixed in #241). A manual `serve` with no flags still honours
+`AC_AGENT_CONFIG_DIR`/`AC_AGENT_STATE_DIR` as before.
+
+`agent.toml`:
+
+```toml
+port = 8788
+bind = "0.0.0.0"
+machine = "melody"
+repos_root = "S:/Repos"
+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.
+`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`
+still resolves. Unlike `repos_root`, `install` takes no flag for it and `status` does not report
+it.
+
+## Verbs
+
+Everything under `/v1/*` except `/v1/health` and `/v1/pair` requires pairing (see **Security
+model**). The verb registry fills `GET /v1/health`'s `capabilities` field with the sorted, unique
+list of every registered verb's capability name — with every verb group registered, that's
+`["agent.desktop.open", "agent.exec.claude", "agent.exec.gh", "agent.git.pull", "agent.git.read",
+"agent.publish.mirror", "agent.scan.context-pressure", "agent.scan.memory-footprint",
+"agent.scan.subagent-cost", "agent.scan.toolchain-inventory"]`.
+
+**Every verb also requires two headers, checked in this order** (#50), after the bearer check
+passes: `X-AC-Plugin` (the calling plugin's id) missing or shaped wrong is `400 {ok: false, error:
+"missing X-AC-Plugin"}` / `"invalid X-AC-Plugin"`; `X-AC-Grants-Revision` missing is `400 {ok:
+false, error: "missing X-AC-Grants-Revision"}`; a value that doesn't match this agent's own current
+revision — including a never-pushed `null` — is `409 {ok: false, error: "grants out of date",
+revision: <this agent's own, or null>}`, since a stale console must self-heal before its refusal
+means anything; only once the agent's own copy is known-current does an ungranted capability get a
+real refusal, `403 {ok: false, error: "<capability> is not granted to <plugin> on <machine>",
+capability, plugin}`. See **Security model** for how a grant reaches the agent in the first place.
+
+- **`GET /v1/repos`** (`agent.git.read`) → `{ok, root, repos: [{name, path, ownerName}]}`: every
+  immediate child of `repos_root` with a `.git` entry (a file for a worktree, a directory for a
+  clone), sorted by name. A missing or unreadable root answers
+  `{ok: true, repos: [], reason: "root missing"}`, never a 500. `ownerName` (#304) is the checkout's
+  `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.
+- **`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).
+- **`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`,
+  `diverged`) when it skipped, or `not-a-repo` / `fetch-failed` / `dry-run`. Fast-forward only
+  (`git merge --ff-only`) — a diverged branch is reported, never resolved. Every git call runs with
+  `GIT_TERMINAL_PROMPT=0`, so a credential prompt refuses instead of hanging a request until its
+  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.
+- **`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.
+  The `200` attests only that the launcher (`rundll32.exe url.dll,FileProtocolHandler` on Windows,
+  `xdg-open` on Linux) started — never a shell string, always argv — not that a browser or Claude
+  Desktop actually opened; that's visible to the person at the desktop, not to the caller.
+- **`POST /v1/scan/<kind>`** (`agent.scan.<kind>`, one capability per kind), body `{}` — a pure
+  dispatch shell (#49, 49c) that mounts one verb per kind registered into it; an unregistered
+  `<kind>` is `404 {"error": "no such verb"}`, the same as any other unregistered route — there is
+  no separate `GET /v1/scan` list, since the kinds a machine implements are already visible as
+  `agent.scan.<kind>` entries in `GET /v1/health`'s `capabilities`. One run per kind at a time: a
+  second `POST` while one is still in flight is `409 {ok: false, error: "scan already running"}`
+  (these scans read whole `~/.claude` trees and must not stack); a kind's own `run()` gets an
+  `AbortSignal` that fires at its `timeoutMs` — a run that doesn't honour it promptly answers the
+  client `504 {ok: false, error: "scan timed out after <n> ms"}` while the run keeps going in the
+  background (a later `POST` for that kind still gets `409`, now naming "timed out, still
+  finishing", until the run actually settles); one that never settles at all is abandoned five
+  timeouts later, freeing the kind up rather than locking it for the agent's whole lifetime. A
+  successful run answers `200 {ok: true, kind, generatedAt, durationMs, payload}`; a rejected one,
+  `502 {ok: false, error: "<message>"}`.
+  - **`context-pressure` and `subagent-cost`** (#52, 52a; `timeoutMs: 900_000` — a cold scan can
+    read on the order of a gigabyte of transcripts) both scan `claude_projects_dir` (default
+    `<homedir>/.claude/projects`) and are byte-compatible with the 1.x `artifacts-console`
+    scheduled tasks of the same name: same JSON shape, same key order, same incremental
+    `(mtime, size)` cache, same `os.linesep` cache-file line ending. `context-pressure` walks
+    `<root>/<encoded-project>/<session>.jsonl` (main session transcripts only — a subagent's own
+    transcript has its own separate window and is never folded in) and reports each session's peak
+    context-window occupancy (`input + cache_read + cache_creation` tokens, as a percentage of the
+    model's window) plus its compaction and unmarked-drop counts. `subagent-cost` walks
+    `<root>/<encoded-project>/<session>/subagents/**/agent-*.jsonl` (both the plain-Task layout and
+    the nested Workflow one) and reports each subagent's token totals and an API-equivalent dollar
+    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
+    at `<stateDir>/scans/context-pressure.json` / `<stateDir>/scans/subagent-cost.json`, created on
+    first write and removed by `uninstall` regardless of `--purge`.
+  - **`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`,
+    `user`, `user-rules` -- global, loaded into every session everywhere -- plus `project`,
+    `project-alt`, `project-rules`, `project-local`, `auto-memory` per repo, `auto-memory` truncated
+    to the first 200 lines of `MEMORY.md` under `claude_projects_dir`, same as `context-pressure`/
+    `subagent-cost`). The repo set is `GET /v1/repos`' own listing (every immediate child of
+    `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.
+  - **`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,
+    `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
+    answers `{skipped: true, reason: "toolchain-inventory is Windows-only (1.x had no Linux
+    equivalent)"}` without spawning anything. Writes (and reads back) `<state>/scans/
+    toolchain-inventory-<hostname>.md` and its `.json` sidecar, and maintains its own copy of the
+    script at `<state>/scans/Get-ToolchainInventory.ps1` (rewritten only when the bundled text
+    changes, via a temp file + rename so a killed agent never leaves a half-written copy). A
+    Store-installed `pwsh` -- an App Execution Alias under `%LOCALAPPDATA%\Microsoft\WindowsApps`,
+    which a plain Node exists check cannot see -- is found: on Windows the agent's exists check falls
+    back to `lstat` (#439), the same check `which` and the preflight use. A missing `pwsh` on PATH is
+    `502 {"error": "pwsh not found on PATH; probed: <each PATH directory's pwsh.exe, in PATH order;
+    past 40 directories, the first 20 and the last 20 around ... (+N more) ...>"}` before any spawn
+    (the registry PATH lists the machine hive then the user hive, so the tail is the end of the user
+    hive, where WindowsApps is; entries in the middle of a very long PATH can still be left out, and
+    the marker counts them); the request timeout kills only the
+    `pwsh` child, never a hung probe or `wsl.exe` process it may have spawned (1.x had the same
+    scope). The hostname used for the file name and inside the script's own report is
+    `os.hostname()` -- never the operator's configured `machine`/`--name` override -- so the agent's
+    file name always matches 1.x's own for a byte-compare.
+
+### `POST /v1/exec/claude` and the job registry
+
+- **`POST /v1/exec/claude`** (`agent.exec.claude`), body `{repo, prompt, permissionMode?, model?}` →
+  `202 {ok: true, jobId}`. `repo` resolves through the same allowlist as `GET /v1/repos/:name/status`
+  (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`
+  (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
+  `429 {ok: false, error: "too many running jobs"}`, checked before spawning, not after.
+- **`GET /v1/jobs`** (`agent.exec.claude`) → `{ok: true, jobs: [view...]}`, newest first.
+  **`GET /v1/jobs/:id`** → `{ok: true, job: view}` or `404` for an unknown id. A job view is
+  `{id, kind: "claude", label, status: "running"|"done"|"failed", startedAt, endedAt?,
+  exitCode?: number|null, repo, permissionMode}`. **`POST /v1/jobs/clear-finished`** →
+  `{ok: true, cleared}`, dropping every done/failed job (running ones are kept).
+- **`GET /v1/jobs/:id/events`** (`agent.exec.claude`) streams a job's log as Server-Sent Events: a
+  `404` for an unknown id up front, otherwise a finished job replays its whole buffer and closes,
+  and a running job replays its buffer then streams new lines live as they arrive, closing once the
+  job finishes. Two frame shapes only: `event: line` with `data` the JSON-encoded line text and `id`
+  the line's absolute position in the job's log (so a reconnecting client can tell whether it missed
+  lines to eviction); `event: done` with `data` `{"status": "done"|"failed", "exitCode":
+  number|null}`. These are the exact event names and shapes the host's own `/api/tasks/:id/log`
+  emits (`packages/host/src/tasks/route.ts`) with `exitCode` added, since the console's shell code
+  already knows how to consume them.
+
+### `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).
+- **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
+  the table):
+
+  | Subcommand | Positional | Flags |
+  |---|---|---|
+  | `issue view` | one `^[0-9]{1,9}$` | `--repo`, `--json`, `--jq` |
+  | `issue list` | none | `--repo`, `--json`, `--jq`, `--limit` (1-200), `--label`, `--author`, `--search`, `--state` (`open`\|`closed`\|`all`) |
+  | `issue comment` | one `^[0-9]{1,9}$` | `--repo`, `--body` |
+  | `pr view` | one `^[0-9]{1,9}$` | `--repo`, `--json`, `--jq` |
+  | `pr list` | none | `--repo`, `--json`, `--jq`, `--limit` (1-200), `--label`, `--author`, `--search`, `--state` (`open`\|`closed`\|`merged`\|`all`) |
+  | `pr checks` | one `^[0-9]{1,9}$` | `--repo`, `--json`, `--jq` |
+  | `pr comment` | one `^[0-9]{1,9}$` | `--repo`, `--body` |
+  | `release view` | one `^v?[0-9][A-Za-z0-9._-]{0,63}$` | `--repo` |
+  | `api` | one `^/?(repos\|orgs\|users\|rate_limit)(/(?!\.{1,2}(?:/\|$))[A-Za-z0-9._-]+)*$`, no query string | `--jq`, `--method` (`GET` only) |
+
+  `--repo` must be `^(?!\.{1,2}(?:/|$))[A-Za-z0-9._-]+/(?!\.{1,2}(?:/|$))[A-Za-z0-9._-]+$` (a bare
+  `.`/`..` half is refused the same way `resolveRepo` already refuses a bare `.`/`..` repo name — a
+  real owner or repo name may still contain a dot, e.g. `my.repo`); `--json` must be `^[A-Za-z,]+$`.
+  Both this and the `api` row's path pattern above build the same `.`/`..`-excluding segment rule
+  from one shared source (`SAFE_SEGMENT_SOURCE` in `gh-allowlist.ts`), not two independent copies.
+  `api` is **read-only by construction**: no request-body flags at all (`-f`, `-F`, `--input`, or `--method`
+  with anything but `GET` are refused), `search` is deliberately not in the path allowlist since a
+  real search needs a `q=` query string this table never permits, and a bare `.`/`..` path segment
+  is refused too — the segment class allows a literal `.` for a real repo/org name (`my.repo`), so
+  without this a `/repos/../search/issues` would otherwise satisfy the pattern and reach exactly
+  the excluded path space. `--flag=value` is split
+  before matching, and a bare `-`/`--` is always refused. A flag or subcommand not in this table —
+  `repo delete`, `issue delete`, `--body-file`, `--editor`, `--web`, `--hostname`, anything else — is
+  refused the same way, before `gh` is ever resolved or spawned.
+
+### The `.cmd`/`.bat` shim note (`claude` and `gh`)
+
+Both `exec/claude` and `exec/gh` resolve their binary by walking `PATH` themselves rather than
+letting a shell do it, because neither ever sets `shell: true` (request input reaching a shell is
+exactly what this agent refuses to do). Node itself cannot spawn a `.cmd`/`.bat` shim without
+`shell: true` (`EINVAL`, since the CVE-2024-27980 fix) — so a `claude` or `gh` install that only put
+a shim on `PATH` (common for a global npm install on Windows) answers `502` with a message naming
+the shim specifically (`"claude is a .cmd shim; install the native Claude Code binary"` /
+`"gh is a .cmd shim; install the native GitHub CLI binary"`), distinct from a bare
+`"<name> not found on PATH"` — the operator's fix differs (install the native binary vs. install it
+at all). Windows PATH resolution stops at the **first** directory with any matching extension, so a
+shim earlier on `PATH` is reported even if a native binary exists further down — that is what a real
+invocation would actually run, not "helpful" behavior a real shell wouldn't show either.
+
+### `POST /v1/publish/mirror`
+
+**`POST /v1/publish/mirror`** (`agent.publish.mirror`, #53) is the 2.0 home of 1.x's hourly
+`publish_onedrive.py`: the console pushes changed report HTML to this verb rather than the agent
+pulling from the console (the console sits behind Cloudflare Access, which an agent cannot pass).
+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
+{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"}`.
+
+- **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
+  `<publish_dir>/html/<href>.tmp-<pid>` then renamed into place. A write/rename failure (a file
+  OneDrive has locked mid-sync) counts as `failed` and the run continues with the next file.
+- **PDF** (when `pdf: true`): one `pdf/<href>.pdf` per `wanted` report (never for an `index.html`
+  page), rendered with a local headless Chromium-family browser only when missing or older than its
+  html — resolved via the same search `GET /v1/preflight`'s `chromium` row uses (winPaths, then
+  PATH, then a version manager's bin dir), never executed otherwise. No resolvable browser is not an
+  error: html still mirrors, the response's `pdf.browser` is `null`.
+- **Ownership, not "not in my docroot"** (1.x issue #230): the publish target is shared across every
+  paired machine that mirrors to it, so pruning (`prune: true`) is scoped to what THIS machine's
+  ledger — `<stateDir>/published-ledger.json`, machine-local, never inside the publish target itself
+  — claims it published; a file another machine owns is never even considered for deletion. With no
+  ledger yet, a machine adopts conservatively (only `wanted ∩ mirrored`). A prune is refused outright
+  (a veto, nothing deleted) when `wanted` is empty, or when it would delete ≥5 files AND over half
+  the mirror in one run — the response's `html.veto`/`pdf.veto` names the reason; re-run with the
+  same request (or a `--force`-equivalent isn't exposed here — see `publish-adopt` below for the
+  one-time claim that closes an adoption gap) once satisfied it's intended.
+- Response `200 {ok: true, dest, html: {written, unchanged, failed, pruned, veto}, pdf: {rendered,
+  upToDate, failed, pruned, veto, browser}}`.
+
+**`ac-agent publish-adopt`** (CLI, not a verb; one-time): refuses when `publish_dir` is unset,
+otherwise claims every file currently in the mirror for this machine's ledger. Run exactly once, only
+on the machine that published the existing (pre-agent) mirror, right at cut-over — without it those
+pre-agent files are unowned and permanently unprunable, since conservative adoption only ever claims
+files a run both mirrors and finds already present.
+
+**Config**: `publish_dir` in `agent.toml` (env override `AC_AGENT_PUBLISH_DIR`, absolute-only, like
+`repos_root`/`claude_projects_dir`) — default on Windows: `%OneDrive%\Claude-Artifacts` (or
+`%OneDriveConsumer%\Claude-Artifacts` when only that's set); `null` (unconfigured) on every other
+platform, and on a Windows box with neither OneDrive env var. `status` reports it under `publishDir`
+(`null` when unconfigured).
+
+## Health: `claudeDesktop`
+
+`GET /v1/health` carries `claudeDesktop: boolean` (#457) — whether this machine can open a
+`claude://` link, so the console can refuse to hand a deep link to a machine that has no Claude
+Desktop. **The field is omitted until the agent holds a conclusive answer**: a console reads a
+missing field as "unknown", never as "no". Detection is read-only and best-effort: only `reg.exe
+query` (Windows) or `xdg-mime query` (Linux) is ever run.
+
+- **Windows: `true` when either signal is present.** The classic registration — a `URL Protocol`
+  value under `HKCU\Software\Classes\claude` or `HKLM\Software\Classes\claude` — or a packaged
+  (MSIX) one: a `Claude_*` package key under
+  `HKCU\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppModel\Repository\Packages`
+  holding a `claude` value (named exactly, with data) under a key ending `\URLAssociations` (the package
+  manifest's URL-protocol registration; the same package's `FileAssociations` never counts). An
+  MSIX app's own `HKCU` writes can be private to the package, so a normal process cannot count on
+  seeing a classic key for a packaged install; both are checked, the classic pair first and the
+  packaged lookup (at most five package keys) only when both miss. `reg.exe`'s "End of search"
+  trailer is localized, so it is never parsed — only exit codes and key/value lines.
+- **Linux:** `xdg-mime query default x-scheme-handler/claude` exits 0 with non-blank output.
+- **Every other platform:** `false`, and nothing is run (a definite answer).
+- **Detection is never request-driven.** `serve` runs a detection at start-up and then every five
+  minutes on its own timer (unref'd, so it never keeps the process alive; stopped on shutdown).
+  `GET /v1/health` only READS the answer the agent holds: it never starts, awaits or delays a
+  detection, so a persistently failing detection costs one attempt per five minutes however often
+  health is called.
+- **Only a conclusive detection changes the held answer.** A detection is *inconclusive* if a
+  command timed out, could not be started (other than the binary being absent) or threw, or if the
+  whole detection ran past 15 seconds. An inconclusive detection never replaces the held answer,
+  and while none is held the field stays omitted. A `true` answer is always conclusive, and a
+  detection whose commands all gave an answer is definitive, including a `false` (reg.exe's "not
+  found" exit, `xdg-mime` with no handler, a binary that is not there). A child killed from outside
+  is reported as an ordinary exit code, so it counts as an answer. A detection abandoned at its
+  15-second deadline is discarded whole: its late result changes nothing.
+- **Two log lines, edge-triggered:** `claude desktop: yes` / `claude desktop: no` when the held
+  answer is first set or changes, and one line when detection becomes inconclusive (not one per
+  attempt).
+- **Lag:** after Claude Desktop is installed or removed the agent knows within five minutes plus one
+  detection (at most 15 seconds), provided detection is conclusive; the console learns it on its next
+  probe of that machine (the scheduled agent-job tick) or at once on a Ping from the Agents panel. A
+  restarted agent holds no answer until its first conclusive detection, so a probe landing in that
+  window stores "unknown".
+
+## Preflight
+
+**`GET /v1/preflight`** (#55): control plane, like `PUT /v1/grants` -- bearer-gated, no capability,
+no `X-AC-Plugin`/`X-AC-Grants-Revision` headers, and refuses a caller carrying `X-AC-Plugin` with
+`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:
+
+| `cmd` | required | executed | verdicts |
+|---|---|---|---|
+| `git` | yes | `git --version` | `ok` \| `missing` \| `broken` \| `off-path` |
+| `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` |
+| `chromium` | no | never | `ok` \| `missing` |
+
+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
+  `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
+  resolved only, never executed -- required: false, so amber (`missing`), never red, when absent.
+- **A `.cmd`/`.bat` shim is `broken` without ever being run.** Node cannot spawn one without
+  `shell: true`, so a shim is reported the same way `exec/claude`/`exec/gh` already do -- distinct
+  from a bare "not found", naming the shim's own path and the exact fix (install the native
+  binary).
+- **The PATH is the machine's, not this process's.** On Windows it is re-read from the registry
+  (`HKLM\...\Environment` then `HKCU\Environment` via `reg.exe`, spawned by its absolute
+  `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"`.
+- **The whole check answers in a few seconds.** Five 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.
+
+## 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`).
+- **`GET /v1/health` and `POST /v1/pair` are the only unauthenticated routes.** `/v1/health` answers
+  `{ok, version, apiVersion, machine, paired, capabilities, grantsRevision, claudeDesktop?}` — 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
+  answer; see **Health: `claudeDesktop`**) discloses one bit
+  — that a `claude://` handler is registered on the machine (for the agent's user, or machine-wide)
+  — as public as `capabilities`.
+  `/v1/pair` authenticates by a one-time code instead of a bearer token, since pairing is what mints
+  the token in the first place.
+- **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
+  `401 {"error": "unauthorized"}`.
+- **Grants: pushed by the console, enforced here, self-healing (#50).** The console's
+  `machine_grants` table is the source of truth; every change is pushed via `PUT /v1/grants` (bearer-
+  gated, refuses a caller carrying `X-AC-Plugin` — that header is how a real verb's own guard tells a
+  plugin's request apart from the console's own, so a plugin can never reach this route), persisted
+  to `grants.json`, and read back on every `serve` start. A push that fails at change time (agent
+  down, network) is not the end of the story: the very next verb request from that plugin fails its
+  revision check (`409`, see **Verbs**), the console pushes again and retries once, and the request
+  succeeds or is genuinely refused — so a grant change reaches the agent on its next request either
+  way, without restarting either side.
+- **A caller must pin the certificate's fingerprint, not trust a system CA** — there is no CA here,
+  by design, and a pairing console holds only the fingerprint an operator typed at pairing time, never
+  the certificate's PEM. The correct client shape is therefore an explicit compare, not
+  `checkServerIdentity`: open the TLS socket with `rejectUnauthorized: false` (there is no chain to
+  validate against), then on connect compare `getPeerCertificate().fingerprint256` — the same
+  colon-separated uppercase hex SHA-256 this package's own `status`/install output prints — against
+  the pinned value yourself, and destroy the socket on any mismatch. This package's own
+  `server.integration.test.ts` exercises exactly that shape against a real TLS socket, both for a
+  correct pin and a wrong one.
+  **`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.)