@andromarces/agent-loops 0.2.1 → 0.3.0

package/README.md

@@ -79,6 +79,64 @@ npm install -g @andromarces/agent-loops
 pnpm add -g @andromarces/agent-loops
 ```
 
+Set up the harness entry points and parent guards at user scope:
+
+```bash
+agent-loop install
+```
+
+`install` detects the harness CLIs on `PATH`, preselects them, and writes the
+entry point and guard for each selected harness. It is interactive; pass
+`--harness <list> --yes` for scripts, and `--dry-run` to print the planned
+writes without changing anything. A second run with the same package makes no
+change. `agent-loop uninstall` removes only the files and settings entries the
+install recorded, and restores a file that install changed when the file is
+otherwise unchanged. Install applies a harness guard before its entry point, and
+if a write fails part way through it records the writes that completed, so
+`uninstall` still removes or restores them. It leaves a target in place when it
+cannot remove or restore it safely; see [Uninstall skips](#uninstall-skips).
+
+`install` must run from a global install or a linked clone. It writes the package
+location as an absolute path into every entry point and guard, and `npx` and
+`pnpm dlx` place the package in a cache directory that npm or pnpm can delete.
+When it detects its own package root inside that cache, `install` refuses with a
+message that asks for a global install first, so it never writes a path that can
+disappear. `uninstall` reads only the manifest and the harness files, so it still
+removes them after the package is gone.
+
+```bash
+agent-loop install --harness claude,codex --yes
+agent-loop uninstall
+```
+
+### Uninstall skips
+
+`agent-loop uninstall` prints one line per target as
+`<harness>: <action> <path> (<detail>)`. A target that it cannot remove or
+restore safely reports `skip`, stays on disk, and loses its manifest record:
+uninstall deletes the harness record, and removes the manifest when no harness
+remains. Uninstall never retries a skipped target, and a backup file can remain
+on disk with no record. Recover a skipped target by hand.
+
+`install` writes a backup at `<file>.agent-loops-backup` when the target existed
+before install and install changed it, and uninstall reads that file to restore
+the pre-install bytes. Install writes no backup when the target did not exist
+before install, and none when it already held the installed bytes.
+
+| Reported detail                                    | Target   | What stays on disk                                                   | Manual recovery                                                                                                                                                                                                                                                       |
+| -------------------------------------------------- | -------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owned file changed since install; left unchanged` | file     | The file, with your later edits, and a backup when present           | Restore `<file>.agent-loops-backup` over the file when that backup exists and you want the pre-install content, or delete the file when you do not want it. Delete the backup by hand when it stays behind.                                                           |
+| `backup missing; left unchanged`                   | file     | The file, unchanged since install, with no backup                    | Install wrote no backup when the file already held the installed bytes, so the file can be your original and needs no change. Otherwise restore the original from version control or another copy, or delete the file when you do not want the installed entry point. |
+| `settings do not parse; left unchanged`            | settings | The settings file, still invalid, and a backup when present          | The record is gone, so no later `agent-loop uninstall` retries it. Repair the syntax and remove the recorded entry by hand, or restore `<file>.agent-loops-backup` when that backup exists and your later edits can be discarded. Then delete the backup.             |
+| `recorded entry not found; left unchanged`         | settings | The settings file, with no recorded entry, and a backup when present | The recorded entry is already gone. Remove another agent-loop entry by hand when one is present, then delete the backup when it exists.                                                                                                                               |
+| `backup missing; left unchanged`                   | settings | The settings file, still holding the recorded entry                  | Remove the recorded entry by hand, or restore the original from version control or another copy. The backup is gone, so none remains to delete.                                                                                                                       |
+
+When a settings file changed after install but still parses and holds the
+recorded entry, uninstall reports `remove-entry` instead: it removes only that
+entry, keeps your edits, and leaves the result not byte-identical. The backup at
+`<file>.agent-loops-backup` stays behind, so delete it by hand when you no
+longer need the pre-install copy.
+
 Run it without installing:
 
 ```bash
@@ -86,6 +144,9 @@ npx @andromarces/agent-loops --help
 pnpm dlx @andromarces/agent-loops --help
 ```
 
+`--help` writes no config, so it runs from the cache. `install` writes config
+that points at the package, so it refuses from the cache; see [Install](#install).
+
 Install from a Git URL instead of the registry:
 
 ```bash
@@ -102,28 +163,39 @@ The `bin` script keeps its `#!/usr/bin/env node` shebang and executable bit, so
 
 ### From a clone (development)
 
-Development uses pnpm and the repository Git hooks:
+Development uses pnpm and the repository Git hooks. User-scope integrations
+point at the package location, so a clone registers its own copy with `npm link`
+before `agent-loop install`:
 
 ```bash
 git clone <repository-url>
 cd agent-loops
 pnpm install
-pnpm agent-loop role ...
+npm link
+agent-loop install
 ```
 
-`pnpm agent-loop` runs the CLI entry from the repository root. To expose the `agent-loop` command on `PATH`, add the pnpm global bin directory to `PATH`, then register the `bin` field globally from the repository root:
-
-```bash
-pnpm setup   # restart the shell afterwards
-pnpm add -g .
-```
+`npm link` writes its bin shim to the global prefix bin directory, so that
+directory must be on `PATH` for `agent-loop` to resolve. It is the
+`npm prefix -g` directory on Windows and `$(npm prefix -g)/bin` on macOS and
+Linux.
 
-pnpm v11 removed `pnpm link --global` and keeps global bins under `PNPM_HOME`; `pnpm add -g .` fails with `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` until `pnpm setup` puts that directory on `PATH`. Without a global install, call the CLI entry directly and quote the repository path so a path with spaces works:
+Entries rendered from a clone point at that clone. After the clone moves, run
+`npm link --force` from the new location, then `agent-loop install` again. A
+plain `npm link` fails with `EEXIST` on Windows when a shim already exists;
+`--force` overwrites the shim.
+`pnpm link` is not a supported path: pnpm 12 `link` has no global mode. Without a
+link, call the CLI entry directly and quote the repository path so a path with
+spaces works:
 
 ```bash
-node "<repo>/src/cli.mjs" role ...
+node "<repo>/src/cli.mjs" install --harness claude --yes
 ```
 
+`pnpm agent-loop` still runs the CLI entry from the repository root. The
+repository Git hooks run formatting and linting on commit and push; they need
+`pnpm install` to have completed, because its `prepare` script installs husky.
+
 ## Usage
 
 ```bash
@@ -183,11 +255,16 @@ agent-loop role dispatch --role reviewer --cwd /path/to/work-tree --prompt-file
 Operations: `dispatch` (default), `finish`, `abort`.
 
 - The run state lives at a fixed path derived from the resolved `--cwd` (`<os tmpdir>/agent-loops/runs/<sha256 of cwd, shortened>/state.json`, with `state.lock` beside it). There is no `--state` flag; `AGENT_LOOP_RUNS_ROOT` overrides the root for tests only.
+- The init call requires `--parent-session`: the CLI refuses an init without it,
+  and refuses an unexpanded placeholder such as `${CLAUDE_SESSION_ID}` or
+  `%CODEX_THREAD_ID%`, before any state is written. A run through `role` is
+  therefore always guarded; the headless `agent-loop` command is the explicit
+  unguarded path.
 - The init call writes a session index entry at `<root>/sessions/<parent-session>` pointing at the state file, so a parent guard hook (#57) can look the run up by session id even when `--cwd` is a different work tree. A later init call from the same session overwrites the entry.
 - Prompts come from stdin by default, or `--prompt-file`. `finish` reads the five-key summary as JSON on stdin; `abort` takes `--reason`.
 - The state file records `task`, `mode`, `cwd`, `parentSession`, `maxSteps`, `timeout`, `stepsUsed`, `lifecycle`, `roles.{worker,reviewer}.{kind,model,effort,sessionId}` (`roles.worker` is null in `review-only`), `lastDispatch`, and `lastResult`, plus `summary` or `reason` when terminal and `resumeDecision` when a maintainer resumed an interrupted run. Updates are atomic (temp file plus rename); exclusive access uses `state.lock` with a stale-lock check on the owner pid.
 - Lifecycle values: `active`, `dispatched`, `interrupted`, `halted`, `finished`, `aborted` (terminal: `halted`, `finished`, `aborted`). A turn interrupted between the CLI start and the state write leaves `dispatched` with a dead lock owner; the first call after the crash marks it `interrupted`, exits non-zero, and never repeats the turn, even with `--resume-interrupted`. From `interrupted`, only `abort` or an explicit `dispatch --resume-interrupted` is accepted.
-- The lock is fail-closed on ambiguity: a contender that finds a lock it cannot read (created moments ago, content not yet written) exits non-zero and never removes it; only an unparseable lock older than a grace window, or one whose recorded pid is dead, is treated as stale.
+- The lock is fail-closed on ambiguity: a contender that finds a lock it cannot read (created moments ago, content not yet written) exits non-zero and never removes it; only an unparseable lock older than a grace window, or one whose recorded pid is dead, is treated as stale. Lock creation is an atomic hard link, with an exclusive-create fallback on filesystems that have no hard links (FAT/exFAT, some network mounts); a lock temp file left by a crashed process is pruned on the next acquisition.
 - The reviewer turn runs under the same `withMutationCheck` as the headless loop: a detected mutation or snapshot error is fatal, keeps the charged step, and sets `halted`. No further dispatch is possible; the next run needs a new init call, which archives the halted file as `state.<timestamp>.json`.
 - `mode: review-only` rejects `--role worker` as a hard guard and does not require `--worker` at init. `finish` is completion of the requested work, not code acceptance: it is accepted from `active` in any mode, and the five-key summary carries the reviewer verdict and unresolved findings.
 - The reviewer is required to end with one explicit `Verdict:` line (`accept` or `reject`, parsed case-insensitively) inside its closing block. The verdict word alone, the word closed by a sentence period (`reject.`), or the word followed by a separator and a trailing clause (`reject — the state does not pass`) parses to that word, unless the clause names either verdict as a whole word. Any other malformed value, including a missing line or a line that names both verdicts, yields `verdict: unknown`; process success never implies acceptance.
@@ -215,113 +292,114 @@ includes it rather than copying it. Role activation never goes into `AGENTS.md`
 or `CLAUDE.md`, because dispatched children read those files; activation
 happens only through explicit invocation.
 
-| Harness         | Entry point                          | Invocation                                    |
-| --------------- | ------------------------------------ | --------------------------------------------- |
-| Claude Code     | `.claude/skills/agent-loop/SKILL.md` | `/agent-loop <task and role settings>`        |
-| OpenCode        | `.opencode/plugins/parent-guard.ts`  | `/agent-loop <task and role settings>`        |
-| Codex CLI       | `.agents/skills/agent-loop/SKILL.md` | `$agent-loop <task and role settings>`        |
-| Copilot CLI     | `src/entrypoints/copilot.mjs`        | `agent-loop-copilot <task and role settings>` |
-| Antigravity CLI | universal fallback (below)           | first prompt references the file              |
-
+| Harness         | Installed entry point                                  | Invocation                                    |
+| --------------- | ------------------------------------------------------ | --------------------------------------------- |
+| Claude Code     | `~/.claude/skills/agent-loop/SKILL.md`                 | `/agent-loop <task and role settings>`        |
+| OpenCode        | `~/.config/opencode/plugins/parent-guard.ts`           | `/agent-loop <task and role settings>`        |
+| Codex CLI       | `~/.agents/skills/agent-loop/SKILL.md`                 | `$agent-loop <task and role settings>`        |
+| Copilot CLI     | `agent-loop-copilot` (packaged bin)                    | `agent-loop-copilot <task and role settings>` |
+| Antigravity CLI | `~/.gemini/antigravity-cli/skills/agent-loop/SKILL.md` | `/agent-loop <task and role settings>`        |
+
+`agent-loop install` writes these files from the templates under
+`src/install/templates/`, and each rendered entry point points at the installed
+`docs/orchestrator-instructions.md` by absolute path, so it works outside a
+clone. Each skill renders the CLI by absolute path and runs every `agent-loop`
+command in the instructions with that resolved invocation, so a Git Bash session
+that cannot resolve the `agent-loop` command still starts a guarded run (#151).
+`harness-check` exits 0 for a match, 3 when another harness is the nearest
+ancestor, and 1 when the check cannot run or finds no harness ancestor, so the
+skill separates a refusal from a check that did not decide. See
+[Parent guard details](docs/parent-guard.md) for every guard target.
+
+- The `~/.agents/skills` directory is shared. Copilot CLI and OpenCode also
+  discover personal skills there, so the installed Codex skill appears in both.
+  The Codex selection owns that directory; install and uninstall for Copilot
+  never touch it. The Codex skill sets `metadata.opencode/autoinvoke: false`, so
+  OpenCode drops it from the model's skill list and the model cannot auto-invoke
+  it for an `/agent-loop` request; the OpenCode plugin command then owns
+  `/agent-loop`. The skill also refuses to start a run when the nearest harness
+  process is not Codex, so a Copilot or OpenCode session that inherits
+  `CODEX_THREAD_ID` cannot start a run through it.
 - The Claude Code skill sets `disable-model-invocation: true`, so only the
   maintainer activates it with `/agent-loop`, and it omits `context: fork`, so
-  the skill runs in the current session. Its body passes `${CLAUDE_SESSION_ID}`
-  as `--parent-session` on the init dispatch call.
-- The OpenCode entry point is a local plugin (`.opencode/plugins/parent-guard.ts`),
-  loaded automatically from `.opencode/plugins/`. Stored command templates expose
-  no session id, so the plugin registers the `/agent-loop` command itself: its
-  executor reads `CommandInvocation.sessionID` and carries that id into the
-  orchestrator prompt, and the init dispatch call passes it as
-  `--parent-session`.
-- The Codex CLI skill (`.agents/skills/agent-loop/SKILL.md`) activates only through
-  `$agent-loop`. It passes `CODEX_THREAD_ID` as `--parent-session`. Use
-  `$env:CODEX_THREAD_ID` in PowerShell and `$CODEX_THREAD_ID` in POSIX shells.
-  In PowerShell, pass `--cwd $worktree` after setting
-  `$worktree = (Get-Location).Path`.
-  The CLI rejects an empty `--parent-session` before it initializes a run.
-  This environment variable is an undocumented dependency and can change on
-  upgrade. When it is absent, do not start a guarded run. Run `/hooks` once to
-  review and trust the repository hook. Do not use
-  `--dangerously-bypass-hook-trust` for normal use.
-- The Copilot CLI entry point is `src/entrypoints/copilot.mjs`, exposed as
-  `agent-loop-copilot`. It mints a UUID, starts
-  `copilot --session-id <uuid> --interactive <prompt>`, and includes the
-  instruction file, task, and same id for `--parent-session` in the first
-  prompt. The current CLI documentation exposes no custom command-template
+  the skill runs in the current session. OpenCode also discovers
+  `~/.claude/skills`, so a foreign OpenCode session lists this same copy to the
+  model. The skill sets `metadata.opencode/autoinvoke: false`, so OpenCode drops
+  it from the model's skill list and the model cannot auto-invoke it for an
+  `/agent-loop` request; the OpenCode plugin command then owns `/agent-loop`.
+  Before the init dispatch call the skill runs the installed CLI by absolute path
+  with `harness-check claude`; exit 3 stops the run because another harness owns
+  the session, and any other non-zero exit stops the run because the check could
+  not run or found no harness ancestor. Both cover the literal
+  `${CLAUDE_SESSION_ID}` that OpenCode leaves unexpanded. The resolved invocation
+  then replaces `agent-loop` for the init dispatch and every later command, so the
+  run does not need the `agent-loop` command on PATH. Its body passes
+  `${CLAUDE_SESSION_ID}` as `--parent-session` on the init dispatch call.
+- The OpenCode entry point is a user plugin at
+  `~/.config/opencode/plugins/parent-guard.ts`, loaded automatically from that
+  directory. Stored command templates expose no session id, so the plugin
+  registers the `/agent-loop` command itself: its executor reads
+  `CommandInvocation.sessionID` and carries that id into the orchestrator
+  prompt, and the init dispatch call passes it as `--parent-session`. The shared
+  Claude and Codex skills set `metadata.opencode/autoinvoke: false`, so OpenCode
+  drops them from the model's skill list and the plugin command is the only
+  `/agent-loop` entry point.
+- The Codex CLI skill (`~/.agents/skills/agent-loop/SKILL.md`) activates only
+  through `$agent-loop`. Before the init call it runs the installed CLI by
+  absolute path with `harness-check codex`, which uses the same exit codes. Exit
+  3 means another harness is the nearest ancestor; any other non-zero exit means
+  the check could not run or found no harness ancestor. Either stops the run: an
+  environment check cannot
+  decide it, because a nested harness inherits `CODEX_THREAD_ID`. The resolved
+  invocation replaces `agent-loop` for every command in the instructions. The
+  skill passes `CODEX_THREAD_ID` as `--parent-session`. Use `$env:CODEX_THREAD_ID` in
+  PowerShell and `$CODEX_THREAD_ID` in POSIX shells. In PowerShell, pass
+  `--cwd $worktree` after setting `$worktree = (Get-Location).Path`. The CLI
+  requires `--parent-session` and rejects an empty or unexpanded value before it
+  initializes a run. This
+  environment variable is an undocumented dependency and can change on upgrade.
+  When it is absent, do not start a guarded run. Run `/hooks` once to review and
+  trust the installed user hook; a changed hook command needs a new trust step.
+  Do not use `--dangerously-bypass-hook-trust` for normal use.
+- The Copilot CLI entry point is the packaged `src/entrypoints/copilot.mjs`,
+  exposed as `agent-loop-copilot`. It mints a UUID, starts
+  `copilot --session-id <uuid> --add-dir <docs dir> --interactive <prompt>`, and
+  includes the instruction file, task, and same id for `--parent-session` in the
+  first prompt. The current CLI documentation exposes no custom command-template
   session-id placeholder, so the launcher is the native entry point.
-- Universal fallback (Antigravity): reference
-  `docs/orchestrator-instructions.md` in the first prompt and follow it. A
-  native entry point is added only after that harness documents an explicit
-  extension mechanism.
-- On Copilot CLI, `.github/hooks/parent-guard.json` registers PascalCase `PreToolUse`, so the payload carries
-  `session_id` and `tool_name`; the hook prints the flat `permissionDecision` object that Copilot CLI consumes.
-  Repository hooks require a trusted folder. GitHub documents the `.github/hooks/*.json` path for Windows, macOS, and
-  Linux, and a live probe on Windows with Copilot CLI 1.0.87-0 confirmed the hook loaded and reported `tool_name:
-Write`; no macOS runtime was available for this change. Copilot also loads `.claude/settings.json` as repository
-  settings and sets `CLAUDE_PROJECT_DIR` to the repository root, so the Claude hook runs the same guard there and
-  Copilot honors the Claude `hookSpecificOutput.permissionDecision` response. Every Copilot `Edit`/`Write` therefore
-  runs two parent guards: the Claude-compat one and the `.github/hooks` one. Both deny the registered parent and both
-  stay silent for any other session. The `.github/hooks` hook stays as the documented, version-stable path.
+- The Antigravity CLI entry point is a skill at
+  `~/.gemini/antigravity-cli/skills/agent-loop/SKILL.md`, activated as
+  `/agent-loop` in an interactive session. It runs the installed CLI by absolute
+  path with `harness-check antigravity` before the init call, and it replaces
+  `agent-loop` with that resolved invocation for every command in the
+  instructions. Then it passes
+  `ANTIGRAVITY_CONVERSATION_ID` as `--parent-session`; use
+  `$env:ANTIGRAVITY_CONVERSATION_ID` in PowerShell. This environment variable is
+  an undocumented dependency and can change on upgrade, and child processes
+  inherit it. When it is absent, or when the harness check stops the run, do not
+  start a run.
+- Universal fallback: reference `docs/orchestrator-instructions.md` in the first
+  prompt and follow it when the harness entry point is not installed. The
+  fallback must still pass the harness session id as `--parent-session`; the CLI
+  refuses an init without it. The headless `agent-loop` command is the explicit
+  unguarded path.
+- On Copilot CLI, the installed `~/.copilot/hooks/parent-guard.json` registers
+  PascalCase `PreToolUse`, so the payload carries `session_id` and `tool_name`,
+  and the hook prints the flat `permissionDecision` object that Copilot CLI
+  consumes. A live probe on Windows with Copilot CLI 1.0.87-0 confirmed the
+  repository form of this hook loaded and reported `tool_name: Write`; no macOS
+  runtime was available for that change. Copilot reads the shared subset of a
+  _repository_ `.claude/settings.json`, which does not cover a Claude user
+  guard, so Copilot gets its own user hook file; install never relies on Copilot
+  reading the Claude user settings.
 - The parent-edit guard (#57) reads `--parent-session` from the state index
-  (see Parent guard below). For any run without `--parent-session`, the parent
-  stays unguarded.
+  (see [Parent guard details](docs/parent-guard.md)). Every `role` init requires
+  `--parent-session`; a legacy state written without one keeps its parent
+  unguarded.
 
 ## Parent guard: hard read-only for the parent session
 
-The parent rule ("the orchestrator never edits files") is prompt-only, so a drifting parent session can still edit. Four harnesses add a hard guard for the file-edit tools: Claude Code through a `PreToolUse` hook in `.claude/settings.json`, Codex CLI through a `PreToolUse` hook in `.codex/hooks.json`, OpenCode through a `permission` `evaluate` plugin hook, and GitHub Copilot CLI through a repository `PreToolUse` hook in `.github/hooks/parent-guard.json`. All share the decision logic in `src/hook/decision.mjs`, so they deny and release under the same rule.
-
-- Matchers: Claude Code uses
-  `Edit|Write|MultiEdit|NotebookEdit`. Codex CLI uses
-  `apply_patch`, which its hook input reports as `tool_name: "apply_patch"`.
-  Copilot CLI uses `Edit|Write`, which covers the current built-in edit and create
-  tools. `Bash` stays allowed because the parent needs it to run `agent-loop role`;
-  a shell-based edit bypasses all guards. Full enforcement needs a harness that
-  exposes only orchestration tools.
-- The hook (`src/hook/parent-guard.mjs`) reads the hook input on stdin and uses only `session_id`. It resolves the state file through the session index written by the init call, never through the hook `cwd`, so a parent whose run targets a different `--cwd` stays guarded wherever it edits. No environment variable is required at parent start-up; the harness entry points (#56) pass their session id as `--parent-session` on init.
-- Deny only when the hook `session_id` equals `parentSession` in the registered state and the lifecycle is non-terminal (`active`, `dispatched`, `interrupted`). The guard releases only on `finish`, `abort`, or a `halted` state; during `interrupted` it stays engaged, and `dispatch --resume-interrupted` keeps it engaged because the resumed run is non-terminal again.
-- Everything else allows: a worker dispatched by `role` in the same cwd (a different session id), a second interactive session in the same cwd, a state without `parentSession`, and a missing or corrupt index entry or state file. The guard fails open by design: it supplements the prompt-only rule, so an unknown record never blocks a tool call.
-- Without a state file the hook does one absent-file read, prints nothing, and exits 0; the normal permission flow applies. The deny reason names orchestrator mode and points at `role dispatch` / `finish` / `abort`.
-- The Claude hook is registered as a shell-form `command` with no `args`, the form both Claude Code and Copilot's Claude-compatible settings loader execute through a shell. An exec-form `command` (`node` + script `args`) fails under Copilot, which ignores the Claude `args` field and runs `node` with the hook payload on stdin; `node` then exits 1 and Copilot fail-closes the tool call. With the shell form, Copilot imports the guard, which exits 0 with no output for every session that is not the registered parent.
-- On OpenCode, `.opencode/plugins/parent-guard.ts` registers a `permission` `evaluate` hook. It reads `PermissionEvaluation.sessionID`, resolves the state through the same session index, and sets `effect: "deny"` with the same reason under the same rule. A live probe against OpenCode v0.0.0-dev-19933 showed the `edit`, `write`, and `apply_patch` tools all raise the `edit` action, so the guard's action set (one set entry, `edit`) covers every built-in file-edit tool; a tool served by an MCP server raises its own action name and passes the guard. `shell` raises a different action and stays allowed, as `Bash` does on Claude Code. The guard exists only while the plugin is loaded, so a session that disables it stays unguarded.
-- The plugin runs inside the OpenCode server process, so it resolves `AGENT_LOOP_RUNS_ROOT` from that process's environment; the Claude Code hook inherits the parent shell's environment instead. The override is test-only, but using it outside tests would point the plugin and the `agent-loop` CLI at different roots and disable the guard silently.
-
-### Pre-tool hook availability by harness
-
-Surveyed 2026-09-21 against current vendor docs, current binaries, and the installed Copilot CLI 1.0.87-0 binary. A session-keyed guard needs both a pre-tool hook and a documented way for the parent to learn its own session id at init time; the guard ships only where both exist.
-
-| Harness            | Pre-tool hook                                                                                                                          | Guard                     |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| Claude Code        | `PreToolUse`, deny supported, `session_id` in input                                                                                    | Implemented (this repo)   |
-| Codex CLI          | `PreToolUse`, deny supported, `session_id` in input; entry point depends on undocumented `CODEX_THREAD_ID`                             | Implemented (best effort) |
-| Antigravity CLI    | `PreToolUse` hooks (workspace or global `hooks.json`), `conversationId` in input                                                       | Not implemented           |
-| GitHub Copilot CLI | PascalCase `PreToolUse`, deny supported, `session_id` and `tool_name` in input; repository `.github/hooks/*.json` loads in current CLI | Implemented (this repo)   |
-| OpenCode           | `permission` `evaluate` plugin hook can set `deny`; event carries `PermissionEvaluation.sessionID`                                     | Implemented (this repo)   |
-
-Codex CLI now uses its `PreToolUse` hook with the session id in hook input. Its
-entry point relies on `CODEX_THREAD_ID` from the shell environment, which is not
-documented and can break on upgrade. The guard fails open when the variable is
-absent or unusable. Antigravity still lacks a documented parent-session channel.
-Copilot uses the documented session-keyed launcher and repository hook described
-above. OpenCode has both: a command reads `CommandInvocation.sessionID`, and the
-permission hook reads `PermissionEvaluation.sessionID`.
-
-The guard path blocked `apply_patch` on Codex CLI 0.156.0-alpha.14 for this
-Windows check. This is a known-good runtime, not a stable minimum version.
-Codex hook denial was not enforced in CLI 0.133.0 or Desktop 0.138.0-alpha.7.
-See [openai/codex#27833](https://github.com/openai/codex/issues/27833). Verify
-that the installed Codex version blocks `apply_patch` before relying on this
-guard. The hook is a best-effort guardrail, not a complete enforcement boundary.
-
-The full skill-to-edit check passed on Codex CLI 0.157.0-alpha.1 on Windows: the
-`$agent-loop` skill registered the Codex thread as the parent, `apply_patch`
-returned `GUARD_DENY_REASON`, `role abort` set the lifecycle to `aborted`, and
-`apply_patch` then succeeded. The probe ran with
-`sandbox_mode = "danger-full-access"`; the `role finish` release path is covered
-by `tests/hook/parent-guard.test.mjs`. The `workspace-write` leg stays
-unverified on Windows: Codex's unelevated Windows sandbox blocks the child
-`git` spawn (`EPERM`) before run initialization
-([openai/codex#37415](https://github.com/openai/codex/issues/37415)). Run that
-leg on macOS or Linux, or under the elevated Windows sandbox.
+The parent rule ("the orchestrator never edits files") is prompt-only, so a drifting parent session can still edit. Five harnesses add a hard guard for the file-edit tools, and all share the decision logic in `src/hook/decision.mjs`. See [Parent guard details](docs/parent-guard.md) for the per-harness matchers, the session-field mapping, and the pre-tool hook availability survey.
 
 ## Reviewer safety
 
@@ -360,7 +438,7 @@ Known limits:
 
 - Ignored files (matching `.gitignore`) are not tracked.
 - Mutations reverted within the same turn are not detected.
-- Only paths within `--cwd` are monitored.
+- A change anywhere in the repository that contains `--cwd` aborts a read-only turn, even outside `--cwd`.
 
 ## Transcript
 
@@ -449,6 +527,8 @@ npm stage view <stage-id>
 npm stage approve <stage-id>
 ```
 
+A manual dispatch must run on the release tag, for example `gh workflow run release.yml --ref v<version>`. A dispatch on a branch is rejected, because npm records provenance from the run ref, not the checked-out commit.
+
 The version goes live only after approval. Staged publishing needs npm 11.15.0 or later and 2FA on the account.
 
 ## Manual smoke test
@@ -480,5 +560,5 @@ Features considered for future development once the hybrid loop stabilizes:
 - Per-role extra CLI arguments and flags
 - GitHub pull request mode
 - Configurable validation commands and automated gates
-- Persistent controller state and session resume across process restarts
-- Streaming transcript logs and usage metadata
+- Persistent headless-loop state and session resume across process restarts
+- A streamed headless transcript

package/docs/orchestrator-instructions.md

@@ -1,10 +1,10 @@
 # Orchestrator instructions (harness-neutral)
 
 You are the parent orchestrator for an `agent-loop role` run. Per-harness entry
-points (the Claude Code and Codex CLI skills, the OpenCode plugin command)
-include this file instead of copying it. The headless prompt in
-`src/prompts/orchestrator.mjs` states the same role rules in JSON-action form;
-this file is the source for shared rules.
+points (the Claude Code, Codex CLI, and Antigravity CLI skills, the OpenCode
+plugin command, and the Copilot launcher) include this file instead of copying
+it. The headless prompt in `src/prompts/orchestrator.mjs` states the same role
+rules in JSON-action form; this file is the source for shared rules.
 
 ## Role
 
@@ -32,24 +32,26 @@ The command blocks below call `agent-loop` directly. Install the CLI globally:
 npm install -g @andromarces/agent-loops
 ```
 
-From a clone, register the `bin` field globally instead. Add the pnpm global
-bin directory to PATH first:
-
-```bash
-pnpm setup   # restart the shell afterwards
-pnpm add -g .
-```
-
-pnpm v11 removed `pnpm link --global` and keeps global bins under `PNPM_HOME`;
-`pnpm add -g .` fails with `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` until
-`pnpm setup` puts that directory on PATH. Without a global install, replace
-`agent-loop` with `node "<repo>/src/cli.mjs"` and quote the repository path so
-a path with spaces works, or run `pnpm agent-loop` from the repository root.
+Then run `agent-loop install` once to write the harness entry points and guards
+at user scope.
+
+From a clone, run `npm link` in the clone, then `agent-loop install`. `npm link`
+writes the bin shim to the global prefix bin directory and points the rendered
+entries at the clone. That directory must be on PATH for `agent-loop` to
+resolve: it is the `npm prefix -g` directory on Windows and
+`$(npm prefix -g)/bin` on macOS and Linux. After the clone moves, run
+`npm link --force` from the new location, then `agent-loop install` again; a
+plain `npm link` fails with `EEXIST` on Windows when a shim already exists.
+`pnpm link` is not a supported path: pnpm 12 `link` has no global mode. Without a
+link, replace `agent-loop` with `node "<repo>/src/cli.mjs"` and quote the
+repository path so a path with spaces works, or run `pnpm agent-loop` from the
+repository root.
 
 ## Starting a run
 
-The first dispatch carries the init flags, including `--parent-session` when
-the harness provides a session id:
+The first dispatch carries the init flags, including the required
+`--parent-session`. The subcommand refuses an init without it, so an interactive
+run is never left unguarded:
 
 ```bash
 printf '%s' "<first child prompt>" | agent-loop role dispatch \
@@ -147,9 +149,10 @@ printf '%s' '{"changed":"...","verified":"...","deferred":"...","notDone":"...",
   terminal and the subcommand rejects further operations, including `abort`.
   Report the failure and the modified paths from the envelope, then stop.
 - Every run ends in exactly one terminal lifecycle: `finished`, `aborted`, or
-  `halted`. The parent-edit guard (#57, Claude Code, Codex CLI, and OpenCode)
-  releases on any of them; any run without `--parent-session` keeps its parent
-  unguarded.
+  `halted`. The parent-edit guard (#57, Claude Code, Codex CLI, Copilot CLI,
+  OpenCode, and Antigravity CLI) releases on any of them. Every `agent-loop role`
+  init requires `--parent-session`, so the guard always has a parent to match.
+  The headless `agent-loop` command is the explicit unguarded path.
 
 ## Recovery after compaction or restart
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andromarces/agent-loops",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Run a task loop across several CLI coding agents.",
   "homepage": "https://github.com/andromarces/agent-loops#readme",
@@ -51,5 +51,5 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@12.4.1"
+  "packageManager": "pnpm@12.6.0"
 }

package/src/agents/agy.mjs

@@ -1,5 +1,6 @@
 import { parseJson } from "../lib/json.mjs";
 import { exec } from "../lib/exec.mjs";
+import { setMainLoopUsage } from "./shared.mjs";
 
 export async function runAgy(state, prompt, options = {}) {
   const { cwd, readOnly, timeout, signal, role } = options;
@@ -30,17 +31,7 @@ export async function runAgy(state, prompt, options = {}) {
   }
 
   state.sessionId = result.conversation_id;
-  setUsage(state, result);
+  setMainLoopUsage(state, result?.usage);
 
   return String(result.response ?? "").trim();
 }
-
-function setUsage(state, result) {
-  const usage = {};
-  if (result?.usage) usage.mainLoop = result.usage;
-  if (Object.keys(usage).length > 0) {
-    state.usage = usage;
-  } else {
-    delete state.usage;
-  }
-}

package/src/agents/codex.mjs

@@ -1,5 +1,6 @@
 import { parseJsonLines } from "../lib/json.mjs";
 import { exec } from "../lib/exec.mjs";
+import { resumeMismatchError, setMainLoopUsage } from "./shared.mjs";
 
 export async function runCodex(state, prompt, options = {}) {
   const { cwd, readOnly, timeout, signal, role } = options;
@@ -36,20 +37,11 @@ export async function runCodex(state, prompt, options = {}) {
   }
 
   if (state.sessionId && returnedId !== state.sessionId) {
-    throw new Error(
-      [
-        "Codex did not resume the expected thread.",
-        `Expected: ${state.sessionId}`,
-        `Received: ${returnedId}`,
-      ].join("\n"),
-    );
+    throw resumeMismatchError("Codex", "thread", state.sessionId, returnedId);
   }
 
   state.sessionId = returnedId;
-  setUsage(
-    state,
-    events.find((event) => event.type === "turn.completed"),
-  );
+  setMainLoopUsage(state, events.find((event) => event.type === "turn.completed")?.usage);
 
   const messages = events
     .filter((event) => event.type === "item.completed" && event.item?.type === "agent_message")
@@ -62,12 +54,3 @@ export async function runCodex(state, prompt, options = {}) {
 
   return String(messages.at(-1)).trim();
 }
-
-/** Sets top-level turn usage, or removes stale usage when Codex omits it. */
-function setUsage(state, completedTurn) {
-  if (completedTurn?.usage) {
-    state.usage = { mainLoop: completedTurn.usage };
-  } else {
-    delete state.usage;
-  }
-}

package/src/agents/copilot.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { parseJsonLines } from "../lib/json.mjs";
 import { exec } from "../lib/exec.mjs";
+import { resumeMismatchError, setMainLoopUsage } from "./shared.mjs";
 
 export async function runCopilot(state, prompt, options = {}) {
   const { cwd, readOnly, timeout, signal, role } = options;
@@ -29,13 +30,13 @@ export async function runCopilot(state, prompt, options = {}) {
     ({ stdout } = await exec("copilot", args, { cwd, input: prompt, timeout, signal, role }));
   } catch (error) {
     const failed = parseJsonLines(error?.stdout ?? "");
-    setUsage(state, findResultEvent(failed));
+    setMainLoopUsage(state, objectUsage(findResultEvent(failed)));
     throw error;
   }
 
   const events = parseJsonLines(stdout);
   const resultEvent = findResultEvent(events);
-  setUsage(state, resultEvent);
+  setMainLoopUsage(state, objectUsage(resultEvent));
 
   const returnedId = resultEvent?.sessionId ?? resultEvent?.session_id;
   if (!returnedId) {
@@ -43,13 +44,7 @@ export async function runCopilot(state, prompt, options = {}) {
   }
 
   if (requestedSessionId && requestedSessionId !== returnedId) {
-    throw new Error(
-      [
-        "Copilot did not resume the expected session.",
-        `Expected: ${requestedSessionId}`,
-        `Received: ${returnedId}`,
-      ].join("\n"),
-    );
+    throw resumeMismatchError("Copilot", "session", requestedSessionId, returnedId);
   }
 
   state.sessionId = returnedId;
@@ -76,11 +71,8 @@ function readAssistantMessage(event) {
   return typeof content === "string" ? content : "";
 }
 
-function setUsage(state, resultEvent) {
-  if (resultEvent && resultEvent.usage && typeof resultEvent.usage === "object") {
-    state.usage = { mainLoop: resultEvent.usage };
-    return;
-  }
-
-  delete state.usage;
+/** Copilot reports usage as an object; any other shape counts as absent. */
+function objectUsage(resultEvent) {
+  const usage = resultEvent?.usage;
+  return usage && typeof usage === "object" ? usage : undefined;
 }