@agentskit/harness 0.12.0 → 0.14.0

package/docs/ADR-0019-human-decision-attestation.md

@@ -13,7 +13,10 @@ Record `approval.recorded` and `authorization.recorded` events in the existing
 hash-chained lifecycle log. Each event contains the decision, resulting state,
 verification digest, source revision, contract hash, and human actor; tracking
 authorization also contains its declared target. Rejections are recorded too,
-so every human terminal decision is auditable.
+so every human terminal decision is auditable. The default tracking mode is
+goal-scoped: one human approval covers the declared tracking effect and emits
+both events. A project may set `tracking.authorization: "separate"` when an
+independent tracking decision is required.
 
 The existing freshness and verification-attestation checks run before either
 decision is accepted. The `run.json` fields remain a convenient projection,
@@ -22,6 +25,8 @@ but the event is the audit record.
 ## Consequences
 
 Consumers can independently prove which verified result was approved and which
-external tracking target was authorized. Legacy logs remain readable and are
-reported as legacy until they contain the new hashed event protocol. This is an
-audit attestation, not a digital signature or external notarization.
+external tracking target was authorized. Humans do not need to copy a run ID or
+digest: approval commands resolve the latest pending run, while the identifiers
+remain in the audit record. Legacy logs remain readable and are reported as
+legacy until they contain the new hashed event protocol. This is an audit
+attestation, not a digital signature or external notarization.

package/docs/MODULE-BOUNDARIES.md

@@ -86,15 +86,16 @@ modules, not a provider dependency.
 | `src/loop/routing.ts` | Composition | Tiered role → provider/model selection over provider availability | `model-policy`, `providers` (type-only), `config` | None |
 | `src/loop/cooldown.ts` | Composition | Provider cooldown store with exponential backoff | stdlib, `providers` | `<stateDir>/provider-cooldowns.json` |
 | `src/loop/doctor.ts` | Composition | Loop readiness report: Orca, providers, routing, slots, workers, queue | adapters, `config`, `cooldown`, `routing`, `slots` | Orca CLI via runner |
-| `src/loop/contract.ts` | Composition | Task contract schema, orchestrator prompt (issue text as untrusted data), marked-JSON parsing, dispatchability assessment, candidate fallback with auth/quota classification, contract cache | `errors`, `hash`, `resilience`, `doc-bridge`, `config`, `routing` (type-only), `zod` | Headless coding-agent CLI via runner |
+| `src/loop/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`, `fs-atomic`, `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/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/fs-atomic.ts` | Composition | Atomic JSON write (temp file + rename) so a reader of `dispatch.json`/`delivery.json`/`contract.json` never observes a truncated file from a crash mid-write or a concurrent read | stdlib | The target file's own directory (temp file created and renamed there) |
+| `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`, `fs-atomic`, `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`, `fs-atomic`, `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` |
@@ -163,7 +164,7 @@ How these seams are wired into the keep-pushing loop (and what is still only a k
 | --- | --- | --- | --- |
 | Doc Bridge | `src/adapters/doc-bridge.ts` | Reads a local index | Keep behind `ContextProvider`; measure context hit/quality separately. |
 | Orca | `src/adapters/orca.ts` | None; produces argv and lifecycle projections only | Keep lease/worktree/issue-lock/SHA planning provider-neutral; execution belongs to the orchestrator. |
-| Linear/GitHub/other tracker | `src/adapters/tracking.ts` callback | Caller-owned network mutation | Require idempotency key and explicit tracking authorization. |
+| Linear/GitHub/other tracker | `src/adapters/tracking.ts` callback | Caller-owned network mutation | Require idempotency key; goal approval covers declared tracking by default, with `tracking.authorization: "separate"` as an explicit opt-out. |
 | 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` (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. |

package/loop.config.example.yaml

@@ -23,10 +23,33 @@ orca:
   minVersion: 1.4.200
   timeoutMs: 20000
 
+# Revisão mais rigorosa só nas fatias que pedem, por label. A revisão É o gate quando não há CI, e um
+# contrato que congela evidência não deve ser julgado com o mesmo orçamento de um ajuste de copy.
+# Primeira entrada que casa vence, e só os campos nomeados são trocados.
+# reviewOverrides:
+#   - anyLabels: [layer:L2, layer:L3]
+#     votes: 2
+#     minSeverity: nit
+#     reason: caminho crítico do MVP
+
+# Suítes já vermelhas na branch base. O harness NÃO roda o verifyCommand — o worker roda, na worktree
+# dele — então tolerar falha conhecida é informação no briefing, não parsing de saída. A issue de
+# rastreamento é obrigatória: quarentena sem dono vira permanente.
+# knownFailures:
+#   - path: packages/foo/tests/bar.test.ts
+#     issue: ENG-123
+#     reason: corrida de escrita em arquivo, pré-existente
+
 linear:
   workspaceId: <linear-workspace-id> # orca linear team list --workspace all --json
   teamKey: ENG
-  person: my-linear-display-name     # the ONLY queue this machine drains
+  person: my-linear-display-name     # the queue this machine drains (and, under unassigned ownership, the name it claims with)
+  queueOwnership: person             # person = the issues assigned to `person`. unassigned = the issues nobody holds,
+                                     # with the assignee as a transient claim the loop writes on dispatch and clears on
+                                     # return, so several machines share one priority-ordered queue.
+                                     # Switching to unassigned REQUIRES clearing the backlog's assignees: with `person`
+                                     # and an unassigned backlog the queue comes back empty and the loop looks healthy
+                                     # while doing nothing.
   people:                            # display name -> Linear user id (orca linear team members …)
     my-linear-display-name: <linear-user-id>
   rotation:
@@ -35,7 +58,11 @@ linear:
     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: []
+  requireLabels: []                  # ALL of these (AND); empty = no constraint
+  anyLabels: []                      # at least ONE of these (OR) — how a machine declares the slices it
+                                     # drains, e.g. [layer:L2, layer:L3]. requireLabels cannot say this:
+                                     # it demands every label on the same issue, so two layers there
+                                     # match nothing and the queue comes back silently empty.
   projects: []                       # empty = all projects
   order: [priority, updatedAt]       # urgent first; priority 0 (none) sorts last
   maxQueue: 50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/harness",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Portable, evidence-backed development harness for coding agents.",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "build": "tsup && node -e \"console.log(JSON.stringify({status:'passed',criteria:['package']}))\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "pnpm typecheck && vitest run --config vitest.config.ts test && node -e \"console.log(JSON.stringify({status:'passed',criteria:['package']}))\"",
+    "test:coverage": "vitest run --config vitest.config.ts --coverage test",
     "test:contract": "pnpm typecheck && vitest run --config vitest.config.ts test/contract.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['protocol']}))\"",
     "test:extensibility": "pnpm typecheck && vitest run --config vitest.config.ts test/extensibility.test.ts && node -e \"console.log(JSON.stringify({status:'passed',criteria:['extensibility']}))\"",
     "test:event-log": "pnpm typecheck && vitest run --config vitest.config.ts test/extensibility.test.ts test/harness.test.ts -t \"ordered append-only lifecycle log|complete typed task through human approval|authorization only when tracking|human rejection\" && node -e \"console.log(JSON.stringify({status:'passed',criteria:['event-log','verification-attestation','approval-attestation']}))\"",
@@ -67,6 +68,7 @@
     "test:boundaries": "pnpm typecheck && vitest run --config vitest.config.ts test/boundaries.test.ts && node scripts/verify-dependency-directions.mjs",
     "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:loop-watch-sigint": "pnpm typecheck && pnpm build >/dev/null && node scripts/verify-loop-watch-sigint.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-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']}))\"",
@@ -85,18 +87,20 @@
     "prepublishOnly": "pnpm typecheck && pnpm build && pnpm test"
   },
   "dependencies": {
-    "commander": "^14.0.0",
+    "commander": "^14.0.3",
     "ink": "7.1.1",
     "react": "19.3.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.6.2"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.20.3",
     "@types/react": "^19.3.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.7.2",
-    "vitest": "^4.1.10"
+    "@vitest/coverage-v8": "4.1.11",
+    "ink-testing-library": "4.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
   },
   "license": "MIT",
   "packageManager": "pnpm@10.34.4",

package/release/manifest.json

@@ -2,9 +2,9 @@
   "type": "agentskit-harness-release-manifest",
   "schemaVersion": 1,
   "package": "@agentskit/harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "channel": "latest",
-  "sourceRevision": "922d2444ef48bfc89e58ccbe0553efc06a09c877",
+  "sourceRevision": "7eed0dcb3162a8808a27e38290356cf005d7c94e",
   "requiredChecks": [
     "typecheck",
     "test",
@@ -32,5 +32,5 @@
     "pilot-benchmark"
   ],
   "nextBaseline": "benchmarks/harness-0.4.0-baseline.json",
-  "digest": "439805502a4fdd074491269cf733b4144f968ac2ef4b32a6271a4c21102ecc7a"
+  "digest": "599670762fa2f8b1c4bd6bf1a0aa9c0dfa40cffbf77781d6cf15ee048cc79000"
 }

package/release/notes.md

@@ -1,3 +1,15 @@
+# 0.13.0 release candidate
+
+A full-codebase test-coverage sweep (every module in `src/kernel/`, `src/execution/`, `src/adapters/`, and most of
+`src/loop/` brought to 90%+ statements/branches) that surfaced eight real bugs, each fixed in its own focused PR:
+atomic writes for per-issue state files (`dispatch.json`/`delivery.json`/`contract.json`), a lock around
+`events.ndjson` rotation, PII-scanner coverage for current-format secrets (OpenAI project keys, fine-grained GitHub
+PATs, Google/Stripe keys, PEM blocks, AWS secret keys), a fixed `Ctrl-C` for `loop watch`, raw throws in
+`retro.ts`/`doc-bridge.ts` reclassified as `HarnessError`, two `execution/agent.ts` session-recorder bugs (dead
+code; a swallowed invalid-runtime-result error), an execute-bit check in `findExecutable`, and a `loop debrief
+--issue X` fix for a normal not-yet-dispatched issue. Everything else in this release is test-only. Publication
+remains gated on a merge to `main` through npm Trusted Publishing.
+
 # 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