@agentskit/harness 0.8.0 → 0.10.0

package/docs/ADR-0029-loop-resilience-pinning-intake.md

@@ -0,0 +1,68 @@
+# ADR-0029: Loop resilience, brief pinning, worktree setup, effort routing, and GitHub intake
+
+- Status: Accepted
+- Date: 2026-09-12
+
+## Context
+
+The 2026-09-11/12 pilot ran the keep-pushing loop (ADR-0027) unattended for ~7 hours and surfaced two production
+defects and, separately, a review of `ColeMurray/background-agents` (an open-source clone of Ramp's Inspect
+background-agent system) suggested transferable ideas already partially covered by this harness's own mechanisms.
+
+Measured from `events.ndjson`: `classifyProviderFailure` did not recognise real Claude/Codex usage-limit phrasing
+("You've hit your session limit", "usage limit reached") or Grok's ("Overloaded", "temporarily limiting requests"),
+so every such failure fell through to `other` and `onProviderFailure` never fired — no cooldown was ever recorded.
+The same gap existed on the review path (`agentskit-review` exit classified without checking the same patterns).
+Result: 19 unclassified `contract.failed` retries across 4 issues and 12 incomplete reviews over 7h, with no cap
+anywhere — nothing counted consecutive failures on an issue or a stage, so a single misclassified error retried
+forever.
+
+## Decision
+
+1. **Failure classification** (bug fix, no schema change): `classifyProviderFailure` (`src/loop/contract.ts`) checks
+   a `QUOTA_PATTERN` covering the phrasing above before falling back to the kernel's generic `classifyFailure`, and
+   `extractResetsAt` parses a relative (`resets in 3h`) or clock-time (`resets 10:40pm`) reset out of the message.
+   `deliver.ts`'s review-incomplete path applies the same classification and marks the **reviewer's own provider id**
+   (`ctx.reviewer.provider`, e.g. `codex`) cooling down — not the review-CLI transport id (`review.provider`, e.g.
+   `codex-cli`), which `rankModels`/`detectProviders` never look up. This was the second, related pilot bug.
+2. **Per-issue and per-stage auto-pause** (new `src/loop/resilience-state.ts`, Composition, no kernel change):
+   `resilience.maxConsecutiveFailures` (default 3) pauses a single issue — one deduplicated Linear comment, the
+   `resilience.pausedLabel` — after that many consecutive `contract.failed`/`worker.dispatch-failed` events; a
+   successful dispatch clears the counter. `resilience.stagePauseAfterRuns` does the same for a `loop stage
+   tick|deliver` run that *throws* (not a normal idle/ok/blocked report) repeatedly. Both are separate from, and do
+   not replace, the existing `blocked`/`stuck` escalation via `linear.excludeLabels` (ADR-0027 §6) — those already
+   self-exclude a terminal outcome; this closes the two pre-dispatch paths that had no ceiling at all.
+3. **Skills pinned into the worker brief** (new `src/loop/skills.ts`): `brief.skills` lists Markdown files, read
+   once at dispatch time, sha256-digested, truncated at `brief.maxSkillChars` with a visible note, and embedded in
+   a new brief section. A missing file fails the dispatch closed. This is deliberately a separate mechanism from
+   the existing Doc Bridge `contract.briefScopes` (path/title pointers resolved per issue) — skills are full pinned
+   content with a cryptographic digest recorded in `dispatch.json`, and a handoff never re-reads them, so editing a
+   skill file after dispatch cannot affect an in-flight worker.
+4. **Worktree setup command**: `project.setup.command` (argv, no shell) runs once between `orca worktree create`
+   and opening the worker terminal — e.g. `pnpm install --frozen-lockfile` — bounded by `project.setup.timeoutSec`
+   (reserved out of the tick time budget so it cannot itself blow the budget). `project.setup.required` (default
+   true) routes a failing/timing-out setup through the same worktree-cleanup and consecutive-failure path as any
+   other dispatch failure.
+5. **Reasoning effort per role**: `models.effort.<role>` is rendered into `tui`/`headless` only for a provider that
+   declares `providers.<id>.effortFlag`; a provider without one silently ignores it, so the feature is opt-in per
+   provider and safe to default-enable. `agentskit-review` has no such flag, so `models.effort.reviewer` is
+   recorded (for `loop retro` grouping and future use) without being wired into the review CLI call.
+6. **GitHub label intake** (new `src/loop/github-intake.ts`): `github.intakeLabel` lets a human ask the loop to
+   review a PR it never dispatched (tracked as `pr-<n>`, no Linear issue). It reuses the same checks/review/fix-round
+   decisions as a normal dispatch, but every nudge becomes a PR comment (no worker terminal exists) and
+   `github.reviewOnly` is pinned `true` in the schema — this loop merges only PRs it dispatched itself, never one it
+   was only asked to review, however clean that review comes back.
+
+## Consequences
+
+- No kernel change; `pnpm test:boundaries` stays green. All six changes are Composition (`src/loop/*`) or a small
+  Adapter addition (`githubOpenPullRequests` gains `label?`, plus `githubLabelRemove`, in `src/adapters/github-cli.ts`).
+- `loop.config.yaml` gains six new top-level/nested blocks (`resilience`, `brief`, `project.setup`, `models.effort`,
+  `providers.<id>.effortFlag`, `github`), all with safe defaults (`.prefault({})`) so an existing 0.8.0 config keeps
+  its exact prior behaviour unless a project opts in.
+- New CLI surface: `ak-harness loop resume [issue] [--stage tick|deliver]` and `ak-harness loop paused`.
+- `loop doctor` gained a `brief.skills` check; `loop retro`'s `dispatches.byProvider` now groups by
+  `provider/model@effort` when an effort was recorded.
+- Explicitly out of scope (from `background-agents`): a remote control plane, sandboxed/remote worktrees
+  (Modal/E2B/Daytona), prebuilds/snapshots, a multiplayer web UI, and Slack/GitHub-App bots. This harness's runtime
+  stays Orca + local worktrees; none of the above changes that.

package/docs/ADR-0030-loop-event-bus-orchestration-hooks.md

@@ -0,0 +1,54 @@
+# ADR-0030: Loop event bus and orchestration hooks, not model-loop middleware
+
+- Status: Accepted
+- Date: 2026-09-12
+
+## Context
+
+Comparing the loop against frameworks that build a "custom agent harness" in-process (e.g. LangChain's
+`create_agent` + middleware: hooks before/after every model call and every tool call) surfaced a real gap: this
+harness had no deterministic extension point at all. `appendLoopEvent` (`src/loop/tick.ts`) only appends to
+`<stateDir>/events.ndjson` — nothing can react in real time, and nothing can say "stop, don't do this" before a
+consequential action.
+
+The gap is real, but the shape of the fix is not "add middleware like LangChain's": this harness orchestrates
+external CLI agents (claude/codex/grok) as opaque processes inside an Orca worktree. There is no in-process
+model↔tool loop to hook into — the worker's own context window, its own tool calls, are invisible to us by design
+(ADR-0027). Building a `before model call` hook here is not possible without controlling that loop, which is
+explicitly out of scope.
+
+What we *do* control, end to end, is the orchestration around that opaque worker: whether we dispatch it, whether
+we act on its review, whether we merge its PR. That is the level at which a deterministic extension point is both
+useful and achievable.
+
+## Decision
+
+1. **`src/loop/event-bus.ts`** (Composition): a local, in-process pub/sub over the loop's existing free-form event
+   vocabulary (`contract.failed`, `worker.dispatched`, `pr.reviewed`, …) plus a small, fixed set of **orchestration
+   lifecycle hooks**: `beforeDispatch`, `afterDispatch`, `beforeReview`, `afterReview`, `beforeMerge`, `afterMerge`,
+   `onPause`, `onEscalate`. A `before*` hook may return `{ block: true, reason }` to stop the action; every other
+   hook is notification-only. A listener or hook that throws is swallowed (logged as a note, never fatal) — a
+   broken local plugin must not take down tick or deliver.
+2. **Not `kernel/plugins.ts`.** The kernel's plugin registry is tied to `HARNESS_EVENT_TYPES`, the harness's own
+   run-lifecycle vocabulary, and carries plugin ids/versions/dependency ordering appropriate for a shared kernel
+   contract. The loop's event vocabulary is an open set of strings owned by composition, not the kernel, so
+   `event-bus.ts` is a separate, simpler primitive with the same "who's listening" ergonomics rather than a reuse
+   of that contract.
+3. **`plugins.modules`** (`loop.config.yaml`): local `.mjs` files, relative to `project.root`, loaded once at the
+   start of `tick`/`deliver`. Same trust level as `agents.registry.yaml` today — files already checked into the
+   project's own repo, never fetched over a network. Each module exports `{ id, apply(bus) }`.
+4. **`appendLoopEvent` gains an optional third `bus` parameter.** Every existing call site (`retro.ts`, tests) is
+   unaffected; `tick.ts`/`deliver.ts` pass their bus so every event written to disk is also emitted live.
+5. **`loop doctor` gains a `plugins.modules` check** using the same `loadLoopPlugins` the runtime uses, so a typo
+   or a broken module surfaces before a tick silently drops a plugin.
+
+## Consequences
+
+- No kernel change; `pnpm test:boundaries` stays green.
+- `loop.config.yaml` gains one new block (`plugins: { modules: [] }`), empty by default — zero behavior change for
+  every existing config.
+- This directly enables the human-approval gate (`delivery.merge.requireHumanApproval`, ADR follow-up in the same
+  release) and the PII-scan wiring as bus consumers, without a bespoke mechanism for each.
+- Explicitly **not** delivered: hooking into the worker's own model/tool loop (structural — the worker is an
+  opaque CLI), a distributed/external event bus (webhook, message broker) as a first consumer, and dynamic module
+  loading from anywhere other than the local repo.

package/docs/LOOP.md

@@ -113,6 +113,7 @@ For every issue the loop dispatched (`<stateDir>/issues/<id>/dispatch.json`) and
 | 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 touches `secretFilePatterns` (`.env`, `*.pem`, `*.key`, `id_rsa`, `credentials.json`, … by default) | **held**: same as `selfEditPaths` — the loop cannot inspect diff content, only filenames, so this holds on the filename shape alone even if the content is innocuous |
 | 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 |
@@ -120,12 +121,66 @@ For every issue the loop dispatched (`<stateDir>/issues/<id>/dispatch.json`) and
 | 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` |
+| Review clean, `merge.requireHumanApproval` set, no GitHub approval yet | **held**: reuses `pr.reviewDecision` already fetched with the PR snapshot — no extra GitHub call; merges automatically as soon as `reviewDecision` becomes `APPROVED` on a later run |
 | 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.
 
+## GitHub label intake: reviewing PRs the loop never dispatched
+
+The loop's normal queue is Linear issues; `github.intakeLabel` (default `loop:review`, set to `null` to disable)
+lets a human ask it to review a PR it had nothing to do with — a contributor's PR, a manual branch, anything —
+without filing a Linear issue for it. Every `deliver` run lists open PRs carrying the label
+(`gh pr list --label <intakeLabel>`) and starts tracking any not seen before as `pr-<n>` under
+`<stateDir>/issues/pr-<n>/intake.json` (`{ pr, headRef, source: 'github-label', addedAt }`); tracking is
+idempotent, so discovery never re-adds a PR it already knows about.
+
+An intake PR runs the same checks → review → fix-round decisions as a normal dispatch (see the table above), with
+two differences forced by having no Linear issue and no worker terminal:
+
+- Every nudge (conflict, red CI, review findings) is posted as a **PR comment** instead of sent to a worker
+  terminal — there is no worker to nudge.
+- `github.reviewOnly` is a fixed guarantee, not a knob (the schema pins it to `true`): a clean review always ends
+  in **held**, commented as "merge is human", the label removed, and `finishedAt` recorded — this loop merges only
+  PRs it dispatched itself, never one it was only asked to review. If the label is removed on GitHub before the
+  loop finishes, it stops tracking the PR the same way (held, no further comments).
+
+## Event bus and orchestration hooks
+
+`appendLoopEvent` writes every loop event to `<stateDir>/events.ndjson`, but nothing could react to one *while it
+happens*, and there was no deterministic way to say "don't do this" before a consequential action. `plugins.modules`
+(`loop.config.yaml`, empty by default — zero behavior change until configured) lists local `.mjs` files, relative to
+`project.root` (same trust level as `agents.registry.yaml`: files already in this repo, never fetched over a
+network), loaded once at the start of `tick`/`deliver`. Each exports `{ id, apply(bus) }`:
+
+```js
+export default {
+  id: 'slack-notify',
+  apply(bus) {
+    bus.on('worker.dispatched', (event) => { /* … */ })
+    bus.hook('beforeMerge', (payload) => {
+      if (isFrozeWindow()) return { block: true, reason: 'release freeze' }
+    })
+  },
+}
+```
+
+- `bus.on(type | '*', listener)` subscribes to the loop's existing event vocabulary (`contract.failed`,
+  `worker.dispatched`, `pr.reviewed`, `provider.cooldown`, `issue.paused`, …) live, in addition to the ndjson log.
+- `bus.hook(name, listener)` subscribes to an **orchestration lifecycle hook**: `beforeDispatch`, `afterDispatch`,
+  `beforeReview`, `afterReview`, `beforeMerge`, `afterMerge`, `onPause`, `onEscalate`. A `before*` listener may
+  return `{ block: true, reason }` to stop the action (surfaced as a `skipped`/`waiting`/`held` result with the
+  reason); every other hook is notification-only. This is deliberately **not** a hook into the worker's own
+  model/tool loop — the worker is an opaque external CLI (ADR-0027) and that loop is invisible to us. These hooks
+  fire around the orchestration decisions we actually make: dispatch, review, merge.
+- A listener or hook that throws is swallowed (never fatal — a broken plugin must not stop tick or deliver) and,
+  for a hook, its error is reported back through `runHook`'s `errors`.
+- `loop doctor` runs a `plugins.modules` check confirming every configured module exists and loads cleanly.
+
+See `src/loop/event-bus.ts` for the full API (`createLoopEventBus`, `loadLoopPlugins`).
+
 ## One tick
 
 1. **Intake** — `orca linear list-issues` once per configured state, filtered and ordered locally; issues already
@@ -148,6 +203,114 @@ terminal handle, provider/model and lease for the deliver stage.
 
 Start from [`loop.config.example.yaml`](../loop.config.example.yaml) at the package root.
 
+## Resilience: auto-pause after repeated failures
+
+Two failure paths have no natural ceiling elsewhere in the pipeline — contract generation failing on every
+candidate, and a worktree/worker dispatch failing outright — because the issue never gets a worktree, a lease that
+would otherwise expire, or a label that would exclude it from the queue. Left alone, a single misclassified or
+persistent error (a quota message the classifier didn't recognise, a broken `orca worktree create`) retries every
+tick forever. (The 2026-09-11/12 pilot logged 19 such retries across 4 issues in 7h before this existed.)
+
+- `resilience.maxConsecutiveFailures` (default 3): after this many **consecutive** `contract.failed` or
+  `worker.dispatch-failed` events on the *same* issue, the loop stops retrying it: one deduplicated Linear comment
+  explaining why, the `resilience.pausedLabel` (default `loop:paused`), and the issue is skipped locally on every
+  later tick regardless of whether that label is in `linear.excludeLabels`. A successful dispatch clears the
+  counter. State lives in `<stateDir>/issues/<id>/failures.json` (`loop paused` lists every paused issue).
+- **Resuming** an issue: remove the `loop:paused` label on Linear (the next tick notices via `list-issues` and
+  clears the local state itself) or run `ak-harness loop resume <issue>`, which also best-effort removes the label.
+- `resilience.stagePauseAfterRuns` (default 3): a scheduled `loop stage tick|deliver` run that *throws* (a config or
+  adapter crash, not a normal idle/ok/blocked report) this many times in a row pauses that stage — `loop stage`
+  then short-circuits to a `{"status":"paused", ...}` report instead of running, so a crash loop cannot spend budget
+  or provider usage under Orca. `ak-harness loop resume --stage tick|deliver` clears it; a single successful run
+  clears it automatically. State lives in `<stateDir>/paused.json`.
+
+Neither mechanism touches the existing `blocked`/`stuck` escalations (fix-round exhaustion, an idle worker with no
+PR) — those already label the issue and route it out of the queue via `linear.excludeLabels`.
+
+## PII/secret scanning
+
+`security.pii.enabled` (default `false` — enabling it never changes behavior for a project that doesn't need it)
+scans issue text before it enters the orchestrator prompt (`contract.ts`) and the worker brief (`brief.ts`) for
+PII-shaped patterns: emails, common provider API-key prefixes (`sk-…`, `ghp_…`, `AKIA…`, Slack tokens), phone
+numbers, card-number-shaped digit runs (`src/kernel/pii.ts`, pure and dependency-free). `security.pii.action`
+controls what happens on a match:
+
+- `redact` (default when enabled): each match is replaced with `[REDACTED:<kind>]` before the text is embedded.
+- `warn`: the text is sent unchanged; a `security.pii-detected` event is still recorded (source `issue-text` or
+  `worker-brief`, with the matched kinds and count — never the matched value itself).
+- `block`: the dispatch fails closed instead of ever sending the text anywhere, with a message naming the kinds
+  found (not the values). Recorded like any other dispatch failure, so `resilience.maxConsecutiveFailures` still
+  applies if it keeps happening.
+
+This is a pattern scanner, not a claim of completeness — it catches common shapes, not every possible secret.
+
+## Cost/time circuit breakers
+
+The loop cannot count a worker CLI's own model or tool calls — it is an opaque process, not a loop we run
+ourselves — so there is no way to cap "cost" the way an in-process agent harness would. Two proxies close most of
+the gap, both unset (disabled) by default so an existing config is unaffected:
+
+- **`delivery.maxDispatchMinutes`**: a hard wall-clock ceiling on one dispatch, independent of idle detection.
+  `delivery.workerIdleTimeoutMin` only catches a worker that stopped producing output; this catches one that is
+  still active but has run far longer than any real task on the project should. Past the ceiling, `deliver` stops
+  nudging/reviewing/merging the issue and escalates it exactly like a stuck worker (Linear comment + label +
+  `returnState`, worktree preserved for inspection, lease released) — recorded as a `max-duration.tripped` event.
+- **`resilience.maxUsageDeltaPercent`**: a cost proxy from Orca's own usage reporting. The builder's remaining
+  usage percent (`RankedModel.remainingPercent`) is snapshotted at dispatch time (`dispatch.json`'s
+  `initialRemainingPercent`); every later `deliver` run compares it against that provider's *current* remaining
+  usage. If it dropped by at least this many percentage points while the issue was in flight, the dispatch is
+  stopped the same way — recorded as `cost-guard.tripped`. This is deliberately usage-delta, not call-count: it is
+  the only per-issue cost signal Orca actually reports for an opaque worker CLI.
+
+## Dynamic outcome progress
+
+The contract's outcome list (`brief.ts`) is a static plan frozen before dispatch — it cannot become a live todo
+list without controlling the worker's own loop, which this harness deliberately does not do (ADR-0027). The brief
+documents a lightweight, optional convention instead: as the worker finishes or starts an outcome, it writes
+`progress.json` at the root of its own worktree, e.g. `{"o1": "done", "o2": "in-progress"}` (ids match the
+outcome list). `loop debrief` reads it back best-effort (`readOutcomeProgress`, `src/loop/progress.ts`) — a
+missing, unreadable, or malformed file is never an error, since nothing enforces the worker keeps it current and
+older dispatches never wrote one at all. When present, it shows as `N/M outcome(s) done` per in-flight issue
+instead of a flat "in flight".
+
+## Skills pinned into the worker brief
+
+`brief.skills` (default `[]`) lists Markdown files, relative to `project.root`, that every worker brief embeds
+verbatim under a `## Skills (pinned)` section — house conventions the orchestrator's contract can reference but a
+worker starting cold has no other way to see (e.g. `AGENTS.md`, `CLAUDE.md`, `docs/for-agents/INDEX.md`).
+
+- Reading and hashing happens once, at dispatch time (`loadPinnedSkills`, `src/loop/skills.ts`): each file is
+  sha256-digested and truncated at `brief.maxSkillChars` (default 6000) with a visible `[truncated N chars]` note so
+  one large file cannot exhaust the brief budget. A configured path that does not exist or cannot be read **fails
+  the dispatch** (fail-closed) rather than silently sending a worker without guidance it was told it would have —
+  the same worktree-cleanup and consecutive-failure accounting as any other dispatch failure applies.
+- The rendered brief is persisted to `<stateDir>/issues/<id>/brief.md`, and `dispatch.json` records `briefDigest`
+  (hash of the full brief) plus `skills: [{path, digest}]` — enough to prove after the fact exactly which revision
+  of a skill file a given worker saw.
+- **Pinning is by design, not by accident:** a handoff (`renderHandoffBrief`) reuses the worktree/branch state, not
+  the original brief, and never re-reads `brief.skills` — so editing a skill file after dispatch affects only
+  *future* dispatches, never a worker (or its handoff) already in flight.
+- `loop doctor` runs a `brief.skills` check confirming every configured file currently exists and is readable, so a
+  typo or a moved file surfaces before the next dispatch fails.
+
+## Worktree setup command
+
+A freshly created Orca worktree is a bare checkout — no `node_modules`, no build output, nothing a worker can run
+tests against until it installs dependencies itself, wasting the first several minutes of every dispatch on the
+same shell commands. `project.setup.command` (unset by default; an argv array, e.g.
+`[pnpm, install, --frozen-lockfile]` — no shell, so no `&&`/`|`) runs once in the new worktree between
+`orca worktree create` and opening the worker's terminal.
+
+- `project.setup.timeoutSec` (default 600) bounds the run; the loop's per-tick time budget already reserves this
+  much time before attempting a dispatch, so a configured setup command cannot itself blow the tick budget.
+- `project.setup.required` (default `true`): a non-zero exit or a timeout removes the just-created worktree, never
+  opens a terminal, and fails the dispatch — recorded as a `worker.dispatch-failed` event and counted by the
+  per-issue consecutive-failure tracker above, exactly like a contract or worktree-create failure. Set it to
+  `false` to have a failing setup only log a note and still hand the worker its terminal.
+- Every run (pass or fail) is recorded as a `worker.setup` event and, when the dispatch succeeds, as `setup:
+  {command, exitCode, durationMs, timedOut}` on `dispatch.json` — enough to see in `loop retro` whether a slow or
+  flaky setup command is costing more dispatches than it saves.
+
 ## What the doctor checks
 
 | Check | Source | Blocking |
@@ -157,6 +320,9 @@ Start from [`loop.config.example.yaml`](../loop.config.example.yaml) at the pack
 | `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 |
+| `brief.skills` | existence + readability of each `brief.skills` path under `project.root` | yes when any are unreadable — dispatch would fail closed anyway |
+| `plugins.modules` | each configured module exists and `import()`s without throwing | yes when any fails to load |
+| `mcp.allowlist` | only runs when `mcp.enabled`; builds the default-deny bridge from `mcp.allowTools` and self-tests it (no live MCP server involved — ADR-0028) | warning on an empty allowlist, failed if the allow/deny wiring itself misbehaves |
 
 
 ## Dynamic model routing
@@ -181,11 +347,28 @@ its binary is on PATH, its auth is not known to be missing, no Orca usage window
 
 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.
+`codex -m {model} -s workspace-write -a never`) and launched in the worker terminal. The explicit
+approval policy keeps YOLO runs non-interactive while the workspace sandbox limits changes to the assigned worktree.
 
 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.
 
+### Reasoning effort per role
+
+`models.effort.<role>` (`low | medium | high | xhigh`; defaults: orchestrator/reviewer `high`, builder `medium`,
+watcher `low`) is only applied for a provider that declares `providers.<id>.effortFlag` — a template such as
+`-c model_reasoning_effort={effort}` (codex) or `--reasoning-effort {effort}` (grok); a provider without one
+ignores it entirely, so leaving `effort` at its default is always safe. The flag (with `{effort}` substituted) is
+appended to `tui` as literal text, and appended as its own argv elements (split on whitespace, since headless argv
+is never shell-joined) to `headless`. `agentskit-review` has no reasoning-effort flag, so `models.effort.reviewer`
+is not currently wired into the review CLI call — it is validated and recorded for symmetry and for a future
+reviewer transport that supports it.
+
+Whichever effort a dispatched builder actually used is recorded as `effort` on `dispatch.json` and the
+`worker.dispatched` event; `loop retro`'s `dispatches.byProvider` groups by `provider/model@effort` (falling back
+to plain `provider/model` for older events with no effort recorded) so a retro can tell a slow `gpt-5.6-luna@high`
+run from a fast `@medium` one.
+
 ## Machine slots
 
 `maxAgents = max(floor, min(adaptiveConcurrency(ceiling), ramBound, wslCap?))` where `ceiling` defaults to
@@ -208,7 +391,7 @@ the published dependency tree. `@agentskit/harness` stays dependency-light (`com
 | Trigger | `.doc-bridge/index.json` exists under `project.root` |
 | Knob | `contract.maxContextReferences` (default `6`; `0` disables) |
 | Behaviour | Query is `"<issue id> <title>"`. Up to N deterministic references are appended to the orchestrator prompt. Missing or malformed index → **no refs** (loop continues). |
-| Boundary | No `@agentskit/doc-bridge` import; the adapter only reads the local index contract ([ADR-0003](ADR-0003-doc-bridge-context-binding.md)). Index build/refresh stays with Doc Bridge (`pnpm docs:bridge:index` in repos that use it). |
+| Boundary | No `@agentskit/doc-bridge` import; the adapter only reads the local index contract ([ADR-0003](ADR-0003-doc-bridge-context-binding.md)). Contract resolution rejects indexes older than `contract.docBridgeMaxAgeHours`; exact source freshness remains a Doc Bridge gate. Index build/refresh stays with Doc Bridge (`pnpm docs:bridge:index` in repos that use it). |
 
 ### Code Review (`agentskit-review`)
 

package/docs/MODULE-BOUNDARIES.md

@@ -44,6 +44,7 @@ modules, not a provider dependency.
 | `src/kernel/learning.ts` | Kernel | Retrospective parsing and human learning promotion | stdlib, `errors` | None |
 | `src/kernel/status.ts` | Kernel | Deterministic status snapshot and digest | `errors`, `hash`, `block`, `types` (type-only) | None |
 | `src/kernel/model-policy.ts` | Kernel | Role-to-model binding and validation | `errors`, `hash` | Provider is data, not an SDK |
+| `src/kernel/pii.ts` | Kernel | Deterministic PII/secret pattern scan + redaction over a plain string | None | None |
 | `src/execution/machine.ts` | Execution support | Machine sampling and adaptive concurrency | stdlib, `types`, `errors` | Host CPU/memory metrics |
 | `src/execution/coordination.ts` | Execution support | Atomic issue/worktree claims and dispatch ledger | stdlib, `errors`, `hash` | Local state directory only |
 | `src/kernel/resilience.ts` | Kernel | Failure classification and bounded retry/recovery policy | `errors` | Operation callback supplied by caller |
@@ -87,8 +88,13 @@ modules, not a provider dependency.
 | `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/resilience-state.ts` | Composition | Per-issue consecutive-failure counter + pause/resume, and per-stage (`tick`/`deliver`) crash-loop pause/resume | stdlib | `<stateDir>/issues/<id>/failures.json`, `<stateDir>/paused.json` |
+| `src/loop/skills.ts` | Composition | `brief.skills` file loading: sha256 digest, truncation at `maxSkillChars`, fail-closed on a missing file | stdlib (`crypto`) | Local Markdown files under `project.root` |
+| `src/loop/github-intake.ts` | Composition | GitHub label-based intake: discovers open PRs carrying `github.intakeLabel` and tracks them as `pr-<n>` (no Linear issue) | `github-cli` | GitHub via the injected runner; `<stateDir>/issues/pr-<n>/intake.json` |
+| `src/loop/event-bus.ts` | Composition | Local pub/sub over the loop's event vocabulary plus orchestration lifecycle hooks (`beforeDispatch`, `beforeReview`, `beforeMerge`, …); loads local `plugins.modules` files | stdlib (`node:path`, `node:url`, dynamic `import()`) | Local `.mjs` files under `project.root`, never fetched over a network |
+| `src/loop/progress.ts` | Composition | Best-effort read of `progress.json` from a worktree — the worker's optional, dynamic outcome-progress report | stdlib | The worktree filesystem only |
+| `src/loop/tick.ts` | Composition | One keep-pushing tick: intake, admit (slots + dispatch ledger claim), contract, optional worktree setup command, skills pinning, dispatch into an Orca worktree, Linear transition, escalation, per-issue failure tracking, precheck | adapters, `coordination`, `errors`, `brief`, `config`, `contract`, `cooldown`, `doctor`, `resilience-state`, `routing`, `skills`, `slots` | Orca CLI + Linear via runner; `<stateDir>` files |
+| `src/loop/deliver.ts` | Composition | Deliver stage per dispatched issue and per label-intake PR: PR detection, self-edit hold, conflict/CI/review fix rounds via terminal (or PR comment for intake), review at head, optimistic squash-merge (dispatched issues only — intake is review + comment, never merge), Linear Done, cleanup, stuck/abandoned escalation | adapters, `coordination`, `errors`, `config`, `cooldown`, `doctor`, `github-intake`, `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` |
@@ -159,7 +165,7 @@ How these seams are wired into the keep-pushing loop (and what is still only a k
 | 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. |
+| GitHub | `src/adapters/github-cli.ts` via `CommandRunner` | `gh pr view/list` (optionally `--label`), `gh api PUT …/merge` with `sha=<reviewed head>`, `gh pr comment`, `gh pr edit --remove-label` | Merge is refused by GitHub when the head moved; every call argv-based and bounded; label intake never calls the merge argv. |
 | 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. |

package/loop.config.example.yaml

@@ -9,6 +9,11 @@ project:
   baseBranch: main
   root: .                            # relative to this file
   stateDir: .codex/loop              # ledger, cooldowns, contracts
+  setup:
+    # command: [pnpm, install, --frozen-lockfile]  # argv (no shell), run once in a freshly created worktree
+                                                     # before the worker terminal opens; unset = skip
+    timeoutSec: 600
+    required: true                    # failing/timing-out setup removes the worktree and counts as a dispatch failure
 
 orca:
   bin: orca                          # on Linux outside Orca terminals use orca-ide (bare `orca` is the GNOME screen reader)
@@ -24,6 +29,10 @@ linear:
   person: my-linear-display-name     # the ONLY queue this machine drains
   people:                            # display name -> Linear user id (orca linear team members …)
     my-linear-display-name: <linear-user-id>
+  rotation:
+    enabled: false                   # set true to advance through owners when the current dispatchable queue drains
+    owners: [my-linear-display-name] # ordered display names; the first entry is the initial owner
+    advanceWhenEmpty: true           # never switch while an active lease remains
   states: [Todo, Ready]              # dispatchable states; anything already started is left alone
   excludeLabels: [blocked, needs-info]
   requireLabels: []
@@ -57,6 +66,12 @@ models:
     maxMin: 240                      # …up to 4 h
     probeBeforeReenable: true
     exhaustedPercent: 100
+  # Reasoning effort requested per role. Only applied for providers below that declare `effortFlag`; others ignore it.
+  effort:
+    orchestrator: high
+    reviewer: high                  # currently unused: agentskit-review has no reasoning-effort flag (see reviewProvider below)
+    builder: medium
+    watcher: low
   providers:
     claude:
       bin: claude
@@ -64,12 +79,15 @@ models:
       envKeys: [ANTHROPIC_API_KEY]   # optional API-key fallback
       tui: "claude --model {model} --permission-mode auto"
       headless: [claude, -p, "{prompt}", --model, "{model}", --permission-mode, plan, --output-format, text]
+      # effortFlag: "--effort {effort}"
     codex:
       bin: codex
       auth: subscription
       envKeys: [OPENAI_API_KEY]
-      tui: "codex -m {model} --full-auto"
+      # Codex 0.154+ uses explicit approval/sandbox flags; --full-auto is not a valid CLI option.
+      tui: "codex -m {model} -s workspace-write -a never"
       headless: [codex, exec, -m, "{model}", -s, read-only, --skip-git-repo-check, "{prompt}"]
+      # effortFlag: "-c model_reasoning_effort={effort}"
     opencode:
       bin: opencode
       auth: none
@@ -81,6 +99,7 @@ models:
       auth: subscription             # `grok login` (OAuth) — no API key needed
       tui: "grok -m {model}"
       headless: [grok, -p, "{prompt}", -m, "{model}"]
+      # effortFlag: "--reasoning-effort {effort}"
 
 machine:
   floor: 1                           # always allow one worker
@@ -110,10 +129,15 @@ delivery:
     auto: true
     method: squash
     requireChecks: true
+    requireHumanApproval: false        # true: also require a human GitHub review approval before merging, even
+                                        # after a clean loop review + green checks
   maxFixRounds: 2
   workerIdleTimeoutMin: 45
+  # maxDispatchMinutes: 240                # hard ceiling on one dispatch regardless of activity; unset = disabled
   handoff: { enabled: true, maxHandoffs: 2, onlyWhenProviderUnavailable: true }
   selfEditPaths: [loop.config.yaml, ".github/**"]   # PRs touching these never auto-merge
+  # secretFilePatterns: [...]              # default already covers .env, *.pem, *.key, id_rsa, credentials.json, etc.
+                                            # PRs touching a matching filename are held, never reviewed or merged
   ignoreChecks: []                   # advisory check names that never block
   requiredChecks: []                 # empty = every reported check must be green
   cleanupWorktree: true              # remove the Orca worktree after merge
@@ -154,6 +178,35 @@ contract:
   maxBriefReferences: 4
   contextProviders: [doc-bridge]      # add rag when rag.enabled
 
+github:
+  intakeLabel: loop:review           # a PR with this label is reviewed even though the loop never dispatched it;
+                                      # null disables intake entirely
+  reviewOnly: true                   # fixed: intake PRs are always review + comment, never auto-merged
+
+plugins:
+  modules: []                        # e.g. [scripts/loop-plugins/notify.mjs] — local .mjs files (relative to
+                                      # project.root, never fetched over the network) loaded once per tick/deliver;
+                                      # each exports { id, apply(bus) } and can subscribe to loop events or block a
+                                      # beforeDispatch/beforeReview/beforeMerge hook — see docs/LOOP.md
+
+security:
+  pii:
+    enabled: false                    # scan issue text / worker brief for PII-shaped patterns before embedding them
+    action: redact                    # redact | warn | block
+
+resilience:
+  maxConsecutiveFailures: 3          # pause an issue after this many consecutive contract/dispatch failures
+  pausedLabel: loop:paused           # applied to the issue in Linear; remove it (or `loop resume <id>`) to retry
+  stagePauseAfterRuns: 3             # pause `loop stage tick|deliver` itself after this many consecutive thrown runs
+  # maxUsageDeltaPercent: 40          # stop a dispatch if its provider's remaining usage drops by this many
+                                      # points while the issue is in flight; unset = disabled (cost circuit breaker)
+
+brief:
+  skills: []                         # e.g. [AGENTS.md, CLAUDE.md, docs/for-agents/INDEX.md] — paths relative to project.root,
+                                      # pinned verbatim into every worker brief (sha256-digested in dispatch.json); a
+                                      # missing file fails the dispatch instead of silently sending a worker without it
+  maxSkillChars: 6000                 # per-file cap; longer files are truncated with a visible note
+
 schedule:
   tick: "*/5 * * * *"
   deliver: "*/10 * * * *"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Portable, evidence-backed development harness for coding agents.",
   "type": "module",
   "bin": {
@@ -68,7 +68,7 @@
     "test:phase-executor": "pnpm typecheck && vitest run --config vitest.config.ts test/phase-executor.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['phase-executor']}))\"",
     "test:artifacts": "pnpm typecheck && vitest run --config vitest.config.ts test/artifacts.test.ts && node scripts/verify-artifact-cli.mjs",
     "test:adapters": "pnpm typecheck && vitest run --config vitest.config.ts test/adapters.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['adapters']}))\"",
-    "test:loop": "pnpm typecheck && vitest run --config vitest.config.ts test/loop.test.ts test/loop-adapters.test.ts test/loop-tick.test.ts test/loop-deliver.test.ts test/loop-install.test.ts test/loop-guided-install.test.ts test/loop-retro.test.ts test/loop-debrief.test.ts test/loop-watch.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['loop-config','loop-providers','loop-routing','loop-doctor','loop-adapters','loop-tick','loop-deliver','loop-install','loop-debrief','loop-watch']}))\"",
+    "test:loop": "pnpm typecheck && vitest run --config vitest.config.ts test/loop.test.ts test/loop-adapters.test.ts test/loop-tick.test.ts test/loop-deliver.test.ts test/loop-install.test.ts test/loop-guided-install.test.ts test/loop-retro.test.ts test/loop-debrief.test.ts test/loop-watch.test.ts test/loop-agent-registry.test.ts test/loop-memory.test.ts test/loop-contract-failure.test.ts test/loop-resilience-state.test.ts test/loop-skills.test.ts test/loop-github-intake.test.ts test/loop-event-bus.test.ts test/loop-progress.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['loop-config','loop-providers','loop-routing','loop-doctor','loop-adapters','loop-tick','loop-deliver','loop-install','loop-debrief','loop-watch','loop-agent-registry','loop-memory','loop-contract-failure','loop-resilience-state','loop-skills','loop-github-intake','loop-event-bus','loop-progress']}))\"",
     "test:review": "pnpm typecheck && vitest run --config vitest.config.ts test/review.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['review-delivery']}))\"",
     "test:quality": "pnpm typecheck && vitest run --config vitest.config.ts test/quality.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['quality-matrix']}))\"",
     "test:eval-battery": "pnpm typecheck && vitest run --config vitest.config.ts test/eval-battery.test.ts test/issues-010-014.eval.test.ts test/optimization.test.ts && pnpm build >/dev/null && node scripts/verify-harness-eval-manifest.mjs && node -e \"console.log(JSON.stringify({status:'passed',criteria:['eval-battery','eval-manifest','eval-coverage']}))\"",

package/release/manifest.json

@@ -2,7 +2,7 @@
   "type": "agentskit-harness-release-manifest",
   "schemaVersion": 1,
   "package": "@agentskit/harness",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "channel": "latest",
   "sourceRevision": "b8cfe596e5f30f2c373b89f00f271079b296feaf",
   "requiredChecks": [
@@ -32,5 +32,5 @@
     "pilot-benchmark"
   ],
   "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
-  "digest": "712347d25fac5a6b0819cf8ba60f11ba9dc37c8d9380fb7df9e834f711509a86"
+  "digest": "231258f2636bbc19cd5b202f37c87146f7892cd5b79a41b97e12f4301c4573d4"
 }