@rackbops/ac-agent 2.0.0-alpha.8

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 roshne
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,307 @@
+# @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), 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.
+
+## Install
+
+```sh
+npx @rackbops/ac-agent install
+```
+
+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. 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).
+
+### 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.
+
+### 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), and 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).
+
+## 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"
+```
+
+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.
+
+## 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"]`.
+
+**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}]}`: 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.
+- **`GET /v1/repos/:name/status`** (`agent.git.read`) → `{ok, name, path, branch, defaultBranch,
+  upstream, ahead, behind, dirty, inProgress}`, 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): 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
+  successful run answers `200 {ok: true, kind, generatedAt, durationMs, payload}`; a rejected one,
+  `502 {ok: false, error: "<message>"}`.
+
+### `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.
+
+## 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}` — 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).
+  `/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.)