@agentskit/harness 0.10.0 → 0.12.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-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

package/docs/MODULE-BOUNDARIES.md

@@ -100,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

@@ -32,7 +32,7 @@ linear:
   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
+    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: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.10.0",
+  "version": "0.12.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 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: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,9 +2,9 @@
   "type": "agentskit-harness-release-manifest",
   "schemaVersion": 1,
   "package": "@agentskit/harness",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "channel": "latest",
-  "sourceRevision": "b8cfe596e5f30f2c373b89f00f271079b296feaf",
+  "sourceRevision": "922d2444ef48bfc89e58ccbe0553efc06a09c877",
   "requiredChecks": [
     "typecheck",
     "test",
@@ -32,5 +32,5 @@
     "pilot-benchmark"
   ],
   "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
-  "digest": "231258f2636bbc19cd5b202f37c87146f7892cd5b79a41b97e12f4301c4573d4"
+  "digest": "439805502a4fdd074491269cf733b4144f968ac2ef4b32a6271a4c21102ecc7a"
 }

package/release/notes.md

@@ -1,3 +1,22 @@
+# 0.12.0 release candidate
+
+Reuses Orca instead of reinventing it, where Orca's own tooling gives a better answer than the harness's own
+heuristics: `loop deliver` escalations now fold in the dispatched worker's own terminal output (best-effort,
+`terminal read --screen`) so a human sees the worker's own diagnosis instead of a generic idle/no-PR message; slot
+assessment prefers Orca's `diagnostics memory` (macOS's real memory-pressure reading) and real per-session RSS over
+the harness's own `vm_stat` approximation and static per-agent guess, which were measured roughly 2x more
+conservative at the same instant. Also ships an installable `ak-harness-loop` Orca Skill documenting the loop's
+commands and the operational constraints this release's investigation confirmed (Orca's orchestration mutations —
+`run-create`/`task-create`/`worker-start`/`send` — require a live coordinator terminal pane and cannot be called
+from the loop's headless `tick`/`deliver`, verified from every angle tried). Publication remains gated on a merge
+to `main` through npm Trusted Publishing.
+
+# 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.