@rackbops/ac-agent 2.0.0-alpha.8 → 2.0.0-alpha.9

package/README.md

@@ -4,9 +4,13 @@ The per-machine host agent for [artifact-console](https://github.com/Rackbops/ar
 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), and `exec/claude` (with the job registry and its SSE log) plus `exec/gh` (#49, 49b) are all
-live; `scan/:kind` (49c) lands in a later issue. Every verb also requires a per-plugin capability
-grant, pushed by the console and enforced here (#50) -- see **Verbs** and **Security model** below.
+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
 
@@ -14,6 +18,17 @@ grant, pushed by the console and enforced here (#50) -- see **Verbs** and **Secu
 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.
+
 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
@@ -33,6 +48,32 @@ elevated, `install` prints the exact one-liner to run in an elevated PowerShell
 `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.
+
 ### Windows: no console window
 
 The task's action is `wscript.exe //B "<launch.js>"` against a small generated JScript launcher
@@ -75,9 +116,14 @@ 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), and the currently-held grants
+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 same as a freshly-purged or never-pushed-to agent), 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.
 
 ## Uninstall
 
@@ -120,18 +166,26 @@ 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.desktop.open", "agent.exec.claude", "agent.exec.gh", "agent.git.pull", "agent.git.read",
+"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:
@@ -167,20 +221,63 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   `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): this package ships no kinds itself, the four #52 scans
-  (`context-pressure`, `subagent-cost`, `memory-footprint`, `toolchain-inventory`) register into it,
-  so until then every `<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"}` (the #52 scans read whole `~/.claude` trees and must not stack); a kind's own `run()`
-  gets an `AbortSignal` that fires at its `timeoutMs` (120s default) — 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
+  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 missing
+    `pwsh` on PATH is `502 {"error": "pwsh not found on PATH"}` before any spawn; 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
 
@@ -263,6 +360,49 @@ at all). Windows PATH resolution stops at the **first** directory with any match
 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.
 
+## 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,