@agentskit/harness 0.9.0 → 0.11.0

package/docs/ADR-0003-doc-bridge-context-binding.md

@@ -6,9 +6,16 @@
 ## Decision
 
 The harness provides a dependency-free `createDocBridgeContextProvider` adapter
-that reads the local `.doc-bridge/index.json` contract. It returns at most
-eight deterministic references, carries the index `contentHash` as source
-provenance, and computes a stable snapshot hash.
+that reads the local `.doc-bridge/index.json` contract. It searches both the
+knowledge corpus and `lookup.ownership` records, deduplicates references by
+path with ownership tie-breaking, returns at most eight deterministic
+references, carries the index `contentHash` as source provenance, and computes
+a stable snapshot hash.
+
+When `contract.docBridgeMaxAgeHours` is greater than zero, the adapter rejects
+an index older than that budget before attaching context. This is an age guard,
+not a source-content proof; the exact Doc Bridge hash gate remains the required
+check for CI and release evidence.
 
 `planRun` accepts resolved context snapshots and freezes them into `run.json`
 with a `contextHash`. The lifecycle log records one `context.attached` event per

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/ADR-0031-loop-observability.md

@@ -0,0 +1,36 @@
+# ADR-0031: Read-only loop observability
+
+## Status
+
+Accepted
+
+## Context
+
+The keep-pushing loop already records durable events and exposes doctor, debrief,
+and retro reports, but operators still have to correlate them manually to find
+stalled workers, missing delivery state, or an idle queue. A daemon or dashboard
+would add another runtime to operate.
+
+## Decision
+
+Add a read-only `loop observe` command and a pure `assessObservability` function.
+The collector reuses existing doctor/debrief/event-log data and read-only Orca
+queries. It reports queue, delivery, machine, provider, memory, cache, and token
+metrics, plus deterministic anomaly rules for:
+
+- connected terminals with no output;
+- active claims without `delivery.json`;
+- completed worktrees with uncommitted files;
+- ready work with a free slot but no recent dispatch; and
+- in-flight worker/review phases past `delivery.workerIdleTimeoutMin`.
+
+`--precheck` provides scheduler-compatible exit semantics (0 actionable, 1
+healthy). The event log remains the source of truth; no new persistence or
+background process is introduced.
+
+## Consequences
+
+Operators and the existing observer can consume one stable JSON/Markdown report,
+while tests exercise the anomaly rules without Orca or network fixtures. A future
+dashboard or MCP read-only surface can consume the same report without changing
+the loop execution path.

package/docs/LOOP.md

@@ -25,6 +25,7 @@ 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 observe [--since 24h] [--json]           # anomaly scan + queue, delivery, machine, memory/cache metrics
 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
 ```
@@ -47,6 +48,12 @@ so it is safe to run from a SessionStart hook or a chat agent that needs context
 
 Use `--once` for a single snapshot; omit it to block until a terminal outcome (or `--timeout <seconds>`).
 
+`loop observe` is the scheduler-friendly health view. It reuses the doctor, debrief and durable event log, then
+checks for a connected terminal with no output, an active claim without `delivery.json`, a finalized dirty worktree,
+a ready queue with an idle slot, and an in-flight review/worker past `delivery.workerIdleTimeoutMin`. It also reports
+machine pressure, provider headroom, delivery counts, fix rounds, memory recalls, cached contracts and observed token
+fields. It is read-only; `--precheck` uses exit 0 for an actionable anomaly and exit 1 when healthy.
+
 ## Running 24/7 with Orca
 
 `loop install` is guided and rendered with Ink when stdin/stdout are terminals (plain lines otherwise). When no
@@ -113,6 +120,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,6 +128,7 @@ 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 |
 
@@ -145,6 +154,40 @@ two differences forced by having no Linear issue and no worker terminal:
   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
@@ -191,6 +234,52 @@ tick forever. (The 2026-09-11/12 pilot logged 19 such retries across 4 issues in
 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
@@ -239,6 +328,8 @@ same shell commands. `project.setup.command` (unset by default; an argv array, e
 | `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
@@ -263,7 +354,8 @@ 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.
@@ -306,7 +398,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 |
@@ -90,6 +91,8 @@ modules, not a provider dependency.
 | `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 |
@@ -97,6 +100,7 @@ modules, not a provider dependency.
 | `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/observability.ts` | Composition | Read-only anomaly assessment and operating metrics built from doctor, debrief, Orca terminal/worktree state, and the durable loop event log | `config`, `doctor`, `debrief`, `deliver`, `retro`, `tick`, `coordination`, `orca-cli` | Orca/Git via injected runner; `<stateDir>` files |
 | `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 |

package/loop.config.example.yaml

@@ -29,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 implementation lease remains
   states: [Todo, Ready]              # dispatchable states; anything already started is left alone
   excludeLabels: [blocked, needs-info]
   requireLabels: []
@@ -80,7 +84,8 @@ models:
       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:
@@ -124,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
@@ -173,10 +183,23 @@ github:
                                       # 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.9.0",
+  "version": "0.11.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 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 && 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']}))\"",
+    "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-observability.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-observability','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.9.0",
+  "version": "0.11.0",
   "channel": "latest",
   "sourceRevision": "b8cfe596e5f30f2c373b89f00f271079b296feaf",
   "requiredChecks": [
@@ -32,5 +32,5 @@
     "pilot-benchmark"
   ],
   "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
-  "digest": "0c87f4ac00da532da6ab4110c8c860938c52965e0e2ef2261e79898eb9826ccc"
+  "digest": "9fd3e219da299dab39477062cb3c17296e18cc6b707bceb42436cdb75afd281b"
 }

package/release/notes.md

@@ -1,3 +1,9 @@
+# 0.11.0 release candidate
+
+Read-only loop observability for the keep-pushing SDLC loop: deterministic anomaly detection and operating metrics
+for queue, delivery, machine pressure, provider headroom, memory, cache, reviews, fix rounds, lead time, and
+observed token fields. Publication remains gated on a merge to `main` through npm Trusted Publishing.
+
 # 0.8.0 release candidate
 
 Worker handoff: continue in-flight tickets on the same Orca worktree/branch with another provider when usage runs out.