@agentskit/harness 0.4.0 → 0.5.0

package/docs/ADR-0027-keep-pushing-loop.md

@@ -0,0 +1,41 @@
+# ADR-0027: Keep-pushing loop as composition over Orca
+
+- Status: Accepted
+- Date: 2026-09-11
+
+## Context
+
+Teams want a coding-agent loop that drains one person's Linear queue around the clock: pick a ticket, freeze a
+verifiable contract, run a worker in an isolated worktree, review, merge, repeat — while never exceeding the
+machine, never guessing when acceptance criteria are missing, and surviving provider usage limits. The harness already
+owns the deterministic pieces (dispatch ledger, machine pressure, delivery gates, evidence). Orca already owns
+scheduling, worktrees, terminals, Linear access and the visibility surface. Nothing owned the composition.
+
+## Decision
+
+1. The loop lives in this package as **Adapter + Composition** (`src/adapters/{command,orca-cli,providers,linear-orca,
+   github-cli,code-review}.ts`, `src/loop/*`). The kernel is unchanged and never imports it (`pnpm test:boundaries`).
+2. Every project-specific value lives in `loop.config.yaml` (zod-validated). The code carries no repository, person,
+   path or model id. Env variable **names** may appear in config; values never do.
+3. External systems are reached only through argv-based, timeout-bounded process execution injected as a
+   `CommandRunner`. Adapters never spawn a shell; composition supplies the real runner; tests supply fakes.
+4. Orca is the single scheduler and visibility surface: two automations (`<prefix>-tick`, `<prefix>-deliver`), each
+   gated by a read-only `--precheck` that exits 0 only when work exists, run an agent prompt whose sole job is to
+   invoke `ak-harness loop <stage>`. No cron, launchd or daemon of our own.
+5. Model routing is tiered per role (`orchestrator`, `reviewer`, `builder`, `watcher`); within a tier the first
+   provider with usage available wins. Usage comes from `orca account list`; an auth/quota failure marks the provider
+   cooling down (exponential, never before the reset Orca reports) and the next candidate is tried.
+6. Autonomy envelope: the loop may claim tickets, freeze contracts, dispatch workers, nudge them, review, squash-merge on
+   a clean review plus green checks, move Linear states and clean worktrees. It must not merge PRs touching
+   `selfEditPaths`, must not force-push or bypass approvals, must not recover leases (human only, ADR-0021), and must
+   escalate with one deduplicated comment when a contract has no executable acceptance criterion or when fix rounds
+   are exhausted.
+
+## Consequences
+
+- `yaml` and `zod` become runtime dependencies of the package.
+- The loop is verifiable offline: every stage has fixture-driven tests and `--dry-run` prints the exact argv.
+- Provider CLIs (`claude`, `codex`, `grok`, `opencode`) are configuration, not code; adding one is a YAML entry with a
+  TUI template, an optional headless template and an `agentskit-review` provider id.
+- Windows is supported through Node's process model; WSL is detected and capped to one worker because host
+  antivirus load is invisible from the distro.

package/docs/LOOP.md

@@ -0,0 +1,195 @@
+# Keep-pushing loop (`ak-harness loop`)
+
+The loop drains one person's Linear queue through Orca worktrees, 24/7, with role-based model routing and
+usage-aware fallback. The harness supplies the deterministic parts (claims, machine pressure, gates, evidence);
+Orca supplies scheduling, worktrees, terminals, Linear access and visibility. Everything project-specific lives in
+`loop.config.yaml` — switching project or person is a config change, never a code change.
+
+Status: **complete (phases 1–5).** Config, doctor, adapters, the dispatch tick, the deliver stage and the Orca
+automation installer are in place. See [ADR-0027](ADR-0027-keep-pushing-loop.md).
+
+## Commands
+
+```bash
+ak-harness loop validate -f loop.config.yaml          # schema check + effective config + hash
+ak-harness loop doctor   -f loop.config.yaml --json   # readiness report (exit 1 when a blocking check fails)
+ak-harness loop doctor --no-probe                     # skip provider probe commands
+ak-harness loop precheck tick                         # exit 0 when a slot, a builder and a candidate exist (Orca --precheck)
+ak-harness loop tick --dry-run --max 1                # plan the next dispatch, print the exact orca argv, write nothing
+ak-harness loop tick                                  # dispatch up to <free slots> workers
+ak-harness loop contract ENG-123 [--refresh|--dry-run] # freeze or show the orchestrator contract for one issue
+ak-harness loop precheck deliver                      # exit 0 when a dispatched issue is in flight
+ak-harness loop deliver [--dry-run] [--issue ENG-123] # drive dispatched workers to merge
+ak-harness loop install [--yes|--force|--skip-rehearsal|--skip-local-config|--dry-run|--plain]  # guided: overlay → checks → rehearsal → confirm
+ak-harness loop uninstall [--dry-run]                 # remove them
+ak-harness loop status                                # what Orca knows: enabled, trigger, provider, latest run
+ak-harness loop hook                                  # one status line for a SessionStart hook; never mutates
+ak-harness loop debrief [--issue ENG-123] [--since 24h]  # human-facing: what is in flight, held, escalated
+ak-harness loop watch [--issue ENG-123] [--once] [--interval 30]  # poll delivery/PR; DONE|FAILED|ACTION_REQUIRED
+ak-harness loop retro [--since 7d] [--json|--learnings]  # weekly digest + calibration suggestions
+```
+
+### Debrief and watch
+
+`loop debrief` is the human companion to the automations: a read-only Markdown (or `--json`) snapshot of
+in-flight dispatches, delivery phase (waiting for PR / review / fix round / ready to merge), holds that need a
+person, recent escalations and provider cooldowns. It does not call Orca or `gh` — only the loop state directory —
+so it is safe to run from a SessionStart hook or a chat agent that needs context before acting.
+
+`loop watch` polls `delivery.json` (and optionally the live PR via `gh`) and prints line-oriented events:
+
+| Event | Meaning |
+|---|---|
+| `DONE` | Delivery finished as merged (or the PR is MERGED) |
+| `FAILED` | stuck / abandoned / failed / PR closed without merge |
+| `ACTION_REQUIRED` | held for a human, incomplete review twice, or fix-round findings |
+| `PROGRESS` | still moving (waiting for PR, review pending, …) |
+
+Use `--once` for a single snapshot; omit it to block until a terminal outcome (or `--timeout <seconds>`).
+
+## Running 24/7 with Orca
+
+`loop install` is guided and rendered with Ink when stdin/stdout are terminals (plain lines otherwise). When no
+`loop.config.local.yaml` exists next to the config it first offers to create one: it lists the Linear team members from
+Orca, asks whose queue this machine drains and, optionally, how much RAM to keep free and the worker ceiling, then
+writes the gitignored overlay and reloads. It then runs the doctor and the automation-environment checks (harness and review CLIs on
+PATH, `gh auth status`, checkout registered in Orca, queue owner), stops on any failed check unless `--force`,
+offers a dry-run tick rehearsal (one orchestrator call, nothing written), lists the exact automations it will
+create, and asks for confirmation before touching Orca. `--yes` accepts every prompt for scripted setups; without
+a TTY the command refuses unless `--yes` or `--dry-run` is given; `--plain` keeps the old check-free behaviour.
+
+It creates two automations in the Orca runtime, each bound to the main checkout as an existing workspace
+with session reuse:
+
+| Automation | Trigger | Precheck (plain command, exit 0 = run) | Prompt |
+|---|---|---|---|
+| `<prefix>-tick` | `schedule.tick` | `<harnessCommand> loop stage tick -f <config>` (runs the tick, exits 1) | never reached under `runner: precheck` |
+| `<prefix>-deliver` | `schedule.deliver` | `<harnessCommand> loop stage deliver -f <config>` (runs deliver, exits 1) | never reached under `runner: precheck` |
+
+With the default `schedule.runner: precheck` the **precheck command is the stage itself** (`ak-harness loop stage
+tick|deliver`): it runs the harness, prints the JSON report and always exits 1, so Orca records every run as
+`skipped_precheck` with the report in `precheckResult.stdout` and never opens an agent session. This is deliberate:
+Orca caps a precheck at 600 s, so `contract.timeoutMs` (default 300 s) plus dispatch must fit one run; an Orca-launched agent starts in bypass-permissions mode and waits for a human to accept the warning, which leaks one
+stuck session per run. `schedule.runner: agent` keeps the legacy behaviour for providers that run unattended.
+Runs and their output are visible in Orca's Automations view and via `loop status`.
+
+`schedule.harnessCommand` must resolve inside Orca's environment: install the harness globally
+(`npm i -g @agentskit/harness`) or set an absolute command. `loop install` warns when it cannot find it on this shell's PATH.
+
+Optional SessionStart hook for Claude Code (`.claude/settings.json` of the target project):
+
+```json
+{ "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "ak-harness loop hook -f loop.config.yaml", "timeout": 10 }] }] } }
+```
+
+It prints `loop: installed (2/2, last run …)` or the install command; it never installs or changes anything.
+
+## Deliver
+
+For every issue the loop dispatched (`<stateDir>/issues/<id>/dispatch.json`) and has not finished:
+
+| Situation | Action |
+|---|---|
+| No PR, worker terminal alive and active | wait |
+| No PR, idle ≥ `workerIdleTimeoutMin` | one check-in via `terminal send`; idle again after that → **stuck**: lease released, issue → `returnState` + `blocked`, worktree kept |
+| No PR, terminal gone (> 5 min after dispatch) | **stuck** as above |
+| PR touches `selfEditPaths` | **held**: one PR comment, no review, no merge |
+| PR conflicting | rebase instruction to the worker, once per head (does not count as a fix round) |
+| CI red | failing check names to the worker; counts as a fix round |
+| CI pending / required check missing | wait |
+| CI green, head not reviewed | `agentskit-review --pr … --block <minSeverity> --result … [--post]` with the first available reviewer candidate |
+| Review findings ≥ floor | findings to the worker; counts as a fix round; same head is never re-reviewed |
+| Fix rounds exhausted (`maxFixRounds`) | **blocked**: Linear comment + label + `returnState`, PR comment, lease released, worktree and PR kept |
+| Review clean, `merge.auto` | `gh api PUT …/merge` with `sha=<reviewed head>` (GitHub refuses if the head moved) → Linear attach + comment + `doneState`, worktree removed when `cleanupWorktree` |
+| PR merged outside the loop | same completion path |
+| PR closed without merge | **abandoned**: lease released, issue → `returnState`, worktree kept |
+
+State lives in `<stateDir>/issues/<id>/delivery.json` (reviews per head, fix rounds, nudges) and every decision is
+appended to `<stateDir>/events.ndjson`. `--dry-run` reports the decision for each issue without touching anything.
+
+## One tick
+
+1. **Intake** — `orca linear list-issues` once per configured state, filtered and ordered locally; issues already
+   leased, linked to a live worktree or sitting on their branch are *busy* and skipped.
+2. **Admit** — `assessSlots` (machine) and the harness dispatch ledger (`<stateDir>/coordination`) decide how many
+   workers may start; a claim is atomic per issue/worktree/branch.
+3. **Contract** — the orchestrator (first available candidate across `models.orchestrator` tiers) reads the issue and
+   the repository read-only and returns a JSON contract between `<<<LOOP_CONTRACT … LOOP_CONTRACT>>>`. Issue text is
+   wrapped as untrusted data. An auth/quota failure on one candidate marks it cooling down and the next is tried.
+   Contracts are cached under `<stateDir>/issues/<id>/contract.json` while the issue is unchanged.
+4. **Dispatch or escalate** — a contract with at least one executable outcome and no blocking ambiguity becomes a
+   worker: `orca worktree create --linear-issue <url> --base-branch <base> --no-parent` (no `--agent`: Orca's agent
+   launcher runs Claude in bypass-permissions mode and waits for a human), then `orca terminal create --command
+   "<providers.<id>.tui>"`, `terminal wait --for tui-idle`, and the brief goes in through `terminal send`. The issue
+   moves to `In Progress` and one dedicated comment is posted. Otherwise the loop posts one
+   `needs-info` comment (deduped by contract digest), adds the label, and moves on without consuming a slot.
+
+Every side effect is recorded in `<stateDir>/events.ndjson`; `dispatch.json` per issue links the worktree,
+terminal handle, provider/model and lease for the deliver stage.
+
+Start from [`loop.config.example.yaml`](../loop.config.example.yaml) at the package root.
+
+## What the doctor checks
+
+| Check | Source | Blocking |
+|---|---|---|
+| `orca.version` / `orca.runtime` | `orca --version`, `orca status --json` | yes — the loop cannot run without a reachable Orca runtime at or above `orca.minVersion` |
+| `provider.<id>` | PATH lookup, `orca account list` usage windows, `orca agent hooks status`, env key names, optional probe, cooldown store | no — reported per provider |
+| `routing.<role>` | tiers from `models.<role>` filtered by provider availability | yes — a role with no available provider blocks |
+| `machine.slots` | `sampleMachine` + `adaptiveConcurrency`, free RAM reserve, WSL cap, running worktrees | no — 0 free slots is a warning, not a failure |
+| `linear.queue` | `orca linear list-issues` per configured state, filtered and ordered locally | yes — an unreachable Linear blocks |
+
+## Model routing
+
+`models.<role>` is a list of tiers; each tier is a list of `provider/model`. Tiers are tried in order and, inside a
+tier, providers in declaration order. The first provider that is **available** wins. A provider is available when
+its binary is on PATH, its auth is not known to be missing, no Orca usage window is at or above
+`cooldown.exhaustedPercent`, it is not cooling down, and its optional probe passed.
+
+Providers authenticate through their own CLI login (`claude login`, `codex login`, `grok login`); only providers
+declared `auth: api-key` need an environment variable, and the loop never reads its value. Orca has no per-run model flag; the chosen model is rendered into `providers.<id>.tui` (for example
+`codex -m {model} --full-auto`) and launched in the worker terminal.
+
+When a provider runs out of usage the loop records a cooldown in `<stateDir>/provider-cooldowns.json`:
+`initialMin` doubling up to `maxMin`, never earlier than the reset instant Orca reported.
+
+## Machine slots
+
+`maxAgents = max(floor, min(adaptiveConcurrency(ceiling), ramBound, wslCap?))` where `ceiling` defaults to
+`cpus / 2`, `ramBound` fits `agentRssMb` agents into free RAM minus `minFreeRamGb`, and the WSL cap applies only
+inside a WSL distro (host Defender load is invisible there). The loop never lowers a running worker; it only
+decides whether to start another.
+
+## Boundaries
+
+Adapters (`src/adapters/command.ts`, `orca-cli.ts`, `providers.ts`, `linear-orca.ts`) depend on kernel contracts
+only and receive a `CommandRunner`; they never spawn a shell. Composition (`src/loop/*`) supplies the real
+runner and wires adapters together. See `docs/MODULE-BOUNDARIES.md`.
+
+## Security notes
+
+- `loop.config.yaml` holds env variable **names**, never values.
+- Every external call is argv-based with a timeout; `ok: false` envelopes fail closed.
+- Linear text is data. Later phases render it into worker briefs inside delimiters and never execute it.
+
+## Continuous improvement: `loop retro`
+
+`ak-harness loop retro --since 7d` reads `<stateDir>/events.ndjson`, every `issues/<id>/{contract,dispatch,delivery}.json`,
+`provider-cooldowns.json` and (unless `--no-orca`) the Orca run records of the two automations, and prints a Markdown
+digest:
+
+- **Numbers** — contracts frozen, escalation rate, dispatches by provider, merged/blocked/stuck/abandoned/in flight,
+  review outcomes, fix rounds, median dispatch→merge, cooldowns, Orca runs (idle/work/timed out, durations).
+- **Problems** — escalation reasons grouped by shape, blocked/stuck/abandoned issues.
+- **What worked** — merged issues with worker, lead time and fix rounds.
+- **Adjustments — project** — rule-based suggestions about the target project, each with its evidence and the
+  `loop.config.yaml` knob to turn (`escalation-rate`, `review-floor`, `fix-rounds`, `stuck-workers`, `review-incomplete`,
+  `provider-cooldowns`, `idle-loop`, `lead-time`, or `steady`).
+- **Adjustments — harness** — defects or limitations of the library itself, derived from events the loop only emits
+  when its own machinery misbehaved (`worker-relaunch`, `dispatch-failures`, `contract-failures`, `merge-refusals`,
+  `review-tool-errors`, `stage-timeout`), with a pointer to the harness issue tracker. `--target project|harness`
+  filters one side.
+
+The headings follow the harness retro grammar, so `--learnings` prints `LearningRecord`s in `proposed` state; a human
+promotes them with `promoteLearnings` (ADR-0019 keeps that decision human). The calibration loop is: read the digest →
+change one knob in `loop.config.yaml` → next digest measures the effect.

package/docs/MODULE-BOUNDARIES.md

@@ -9,7 +9,7 @@ does not claim that the proposed 0.4.0 boundary has already been accepted.
 
 | Class | Meaning | Dependency rule |
 | --- | --- | --- |
-| Kernel | Deterministic contracts, state transitions, policy and metric projections | May use Node standard library and other kernel modules; must not import adapters, provider SDKs, CLI composition, or credentials. |
+| Kernel | Deterministic contracts, state transitions, policy and metric projections | May use Node standard library and other kernel modules; must not import adapters, provider SDKs, CLI composition, credentials, or UI libraries (`ink`/`react` are composition-only). |
 | Execution support | Local process, filesystem, event, evidence, and run lifecycle plumbing | May depend on the kernel; must expose provenance and fail closed at trust boundaries. |
 | Adapter | Provider-specific or external-system integration | May depend on kernel contracts; must not be imported by kernel modules. |
 | Composition | Package and CLI entry points | May compose kernel, execution support, and adapters; consumers use `src/index.ts`. |
@@ -73,6 +73,30 @@ modules, not a provider dependency.
 | `src/adapters/agent.ts` | Adapter | Structured coding-agent execution with bounded timeout and failure classification | `errors`, `resilience`, `adapter-contract` | Agent/provider callback supplied by caller |
 | `src/adapters/orca.ts` | Adapter | Safe, idempotent Orca dispatch plan | `errors`, `hash`, `preflight` | Orca CLI arguments; no execution |
 | `src/adapters/tracking.ts` | Adapter | Idempotent provider-neutral tracking transition | `errors`, `hash` | User-supplied Linear/GitHub/etc. handler |
+| `src/adapters/command.ts` | Adapter | Shell-free command runner seam, PATH executable lookup, Orca JSON envelope parsing | stdlib | Command runner supplied by composition or tests |
+| `src/adapters/orca-cli.ts` | Adapter | Typed `orca … --json` calls: version/status/account/agent hooks, worktree ps/create/set/rm, terminal list/send/wait/read, automations list/create/edit/remove/run | `errors`, `command` | Orca CLI via the injected runner |
+| `src/adapters/providers.ts` | Adapter | Coding-agent CLI availability: binary, auth, Orca usage windows, exhaustion, cooldown, optional probe | `command` | PATH, env var names, `orca account list` payload |
+| `src/adapters/linear-orca.ts` | Adapter | Linear queue via `orca linear list-issues`, issue detail, status/comment/label/attach writes with deterministic `--write-id`, `TrackingAdapter` over Orca | `errors`, `hash`, `orca-cli`, `tracking`, `command` | Linear through the Orca CLI |
+| `src/adapters/github-cli.ts` | Adapter | Pull request snapshots, check classification, self-edit path guard, optimistic squash-merge and comments via `gh` | `errors`, `command` | GitHub through the `gh` CLI |
+| `src/adapters/code-review.ts` | Adapter | `agentskit-review` argv, `--result` parsing, severity floor, worker-facing findings | `command` (type-only) | AgentsKit code review CLI via runner |
+| `src/loop/config.ts` | Composition | `loop.config.yaml` schema (zod), loading, model reference parsing | `errors`, `hash`, `model-policy`, `yaml`, `zod` | Project config file |
+| `src/loop/process.ts` | Composition | Real shell-free `CommandRunner` with timeout and output caps | stdlib, `command` (type-only) | Child processes |
+| `src/loop/slots.ts` | Composition | Machine slot assessment: adaptive concurrency, RAM reserve, WSL cap, floor | stdlib, `machine`, `config` | Host CPU/memory |
+| `src/loop/routing.ts` | Composition | Tiered role → provider/model selection over provider availability | `model-policy`, `providers` (type-only), `config` | None |
+| `src/loop/cooldown.ts` | Composition | Provider cooldown store with exponential backoff | stdlib, `providers` | `<stateDir>/provider-cooldowns.json` |
+| `src/loop/doctor.ts` | Composition | Loop readiness report: Orca, providers, routing, slots, workers, queue | adapters, `config`, `cooldown`, `routing`, `slots` | Orca CLI via runner |
+| `src/loop/contract.ts` | Composition | Task contract schema, orchestrator prompt (issue text as untrusted data), marked-JSON parsing, dispatchability assessment, candidate fallback with auth/quota classification, contract cache | `errors`, `hash`, `resilience`, `doc-bridge`, `config`, `routing` (type-only), `zod` | Headless coding-agent CLI via runner |
+| `src/loop/brief.ts` | Composition | Worker prompt: frozen contract + repository rules + protected paths + done signal | `contract`, `config`, `linear-orca` (type-only) | None |
+| `src/loop/tick.ts` | Composition | One keep-pushing tick: intake, admit (slots + dispatch ledger claim), contract, dispatch into an Orca worktree, Linear transition, escalation, precheck | adapters, `coordination`, `errors`, `hash`, `brief`, `config`, `contract`, `cooldown`, `doctor`, `routing`, `slots` | Orca CLI + Linear via runner; `<stateDir>` files |
+| `src/loop/deliver.ts` | Composition | Deliver stage per dispatched issue: PR detection, self-edit hold, conflict/CI/review fix rounds via terminal, review at head, optimistic squash-merge, Linear Done, cleanup, stuck/abandoned escalation | adapters, `coordination`, `errors`, `config`, `cooldown`, `doctor`, `routing`, `tick` | Orca, Linear, GitHub, agentskit-review via runner; `<stateDir>` files |
+| `src/loop/install.ts` | Composition | Orca automation specs (`<prefix>-tick`, `<prefix>-deliver`) with read-only prechecks, idempotent create/edit by name, uninstall, status and the SessionStart hook line | `command`, `orca-cli`, `providers`, `errors`, `config`, `cooldown`, `doctor`, `routing` | Orca automations via runner |
+| `src/loop/guided-install.ts` | Composition | Interactive install: doctor + environment preflight, dry-run rehearsal, confirmation, install, status; readline IO injected | `command`, `orca-cli`, `config`, `doctor`, `install`, `tick`, stdlib readline | Terminal prompts; Orca via runner |
+| `src/loop/local-config.ts` | Composition | Per-machine overlay wizard: Linear team members via Orca, queue owner and machine tuning answers, YAML rendering and reload | `orca-cli`, `config`, `yaml` | Orca via runner; writes `loop.config.local.yaml` |
+| `src/loop/retro.ts` | Composition | Retro digest over `events.ndjson`, per-issue state, cooldowns and Orca runs; rule-based calibration suggestions; Markdown that `parseRetro` can lift into learnings | `orca-cli`, `hash`, `learning`, `config`, `contract`, `cooldown`, `deliver`, `install`, `tick` | Orca via runner (optional); `<stateDir>` files |
+| `src/loop/debrief.ts` | Composition | Human-facing read-only snapshot of what the loop is working on (in-flight, holds, escalations, cooldowns) | `config`, `contract`, `cooldown`, `deliver`, `retro`, `tick` | `<stateDir>` files only |
+| `src/loop/watch.ts` | Composition | Poll delivery (+ optional live PR) and emit DONE/FAILED/ACTION_REQUIRED/PROGRESS for agents or humans | `command`, `github-cli`, `config`, `deliver`, `tick` | optional `gh` via runner; `<stateDir>` files |
+| `src/loop/ui/components.tsx` | Composition | Ink components: check rows, sections, banner, spinner, select/confirm/text prompts | `ink`, `react`, `doctor` (type-only) | Terminal |
+| `src/loop/ui/terminal.tsx` | Composition | `createRichIO`: Ink-backed IO for TTYs with a plain-text fallback | `ink`, `react`, `components`, `guided-install` (type-only) | Terminal |
 
 ## Allowed dependency directions and exceptions
 
@@ -130,6 +154,10 @@ Orca, and tracking. No adapter implementation is re-exported wholesale.
 | Doc Bridge | `src/adapters/doc-bridge.ts` | Reads a local index | Keep behind `ContextProvider`; measure context hit/quality separately. |
 | Orca | `src/adapters/orca.ts` | None; produces argv and lifecycle projections only | Keep lease/worktree/issue-lock/SHA planning provider-neutral; execution belongs to the orchestrator. |
 | Linear/GitHub/other tracker | `src/adapters/tracking.ts` callback | Caller-owned network mutation | Require idempotency key and explicit tracking authorization. |
+| Orca CLI (loop) | `src/adapters/orca-cli.ts`, `src/adapters/linear-orca.ts` via `CommandRunner` | Read-only `--json` calls in the doctor; dispatch/mutation arrive in later loop phases | Argv only, never a shell string; every call bounded by a timeout; envelope `ok:false` fails closed. |
+| Coding-agent CLIs | `src/adapters/providers.ts` | PATH lookup and optional probe command | Env keys are names only; usage comes from Orca, never from provider SDKs. |
+| GitHub | `src/adapters/github-cli.ts` via `CommandRunner` | `gh pr view/list`, `gh api PUT …/merge` with `sha=<reviewed head>`, `gh pr comment` | Merge is refused by GitHub when the head moved; every call argv-based and bounded. |
+| AgentsKit code review | `src/adapters/code-review.ts` via `CommandRunner` | `agentskit-review --pr … --result <file> [--post]` | Exit codes 0/1/2 plus the private result file decide clean/findings/incomplete; the floor is `--block`. |
 | Process runtime | `src/execution/runtime.ts` | Starts child processes | Execution support; policy and evidence gates remain kernel decisions. |
 | Docker runtime | `src/execution/runtime.ts` | Starts Docker containers | Optional sandbox selected by config, never a mandatory kernel dependency. |
 | LLM provider/model | Caller/plugin | Provider call and token spend | Bind provider/model in experiment metadata; do not embed SDKs in kernel. |