harnex 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9142cc69cec0a0cf0dc3961ccc27dc3728baea445c7d83b4c2d69a34b7e6a499
-  data.tar.gz: b89c616cb2484d48e74ef88985a438f7ebb1c22b1af17dd44cbaab3ee0c020cd
+  metadata.gz: 4158bd117bb14da526926a4f80e61c0d4809b5fb401ff718c2b64ddeb0075730
+  data.tar.gz: 6c2b75a37fbe9dbc9236b02898e9672c30af2bf72716c1c83152006760ff67de
 SHA512:
-  metadata.gz: 220566d1c646ca49b7f41f8ed053b2909dda8468ab3dc877bfcfe5f47b52988492d54b9d2fcc42ff0e42154921fde97af0824688b27df69e94bd9fc49b77c2f8
-  data.tar.gz: e52eca128c1f078171ab991acd25bafa810e8341a7f6c8f199535cd03b7a881ee03f2c4193afb01ece92cc00d0a8025a6bdb564739aeb13cbe6a02a4f4d87d0a
+  metadata.gz: 016be4a78e559a075d8477e99343290098025f0e0cf70538da97b647c281a94c8fbf3f704276dd5ba6d00d8d3f92321c16b4f875e6849e302037fb6bb2199cac
+  data.tar.gz: 8cec64fc830b8a37238b5ea1d0068d4422190ffb76dc0f936a10de95b6928512fdf25cf032ec5990e8c3a6e32d2012d4d0fac41f5946f68ad4e74b2e25ebce3a

data/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## [0.9.0] - 2026-08-03 | 01:11 AM | IST
+
+Minor bump: the durable dispatch row family is now v2, `--summary-out` changes
+from a default destination to an explicit mirror, and retention/phase policy add
+operator-visible behavior.
+
+### Added
+
+- **Price-table cost for token-reporting adapters** (#63, plan 33
+  Phase 2; subsumes #58's cost gap): new `lib/harnex/pricing.rb` holds a
+  static per-1M-token USD rate table keyed by provider + model, each entry
+  `as_of`-dated and hand-copied from the provider pricing pages
+  (OpenAI gpt-5.x/codex and Anthropic Claude families, rates as of
+  2026-08-02; update procedure documented in the file header).
+  `build_summary_usage` applies it only when `cost_usd` is null, usage
+  status is `observed`/`zero`, and the effective model matches the table —
+  then `cost_source: "price_table"` and a new always-present
+  `usage.cost_price_as_of` field record provenance. Unknown models stay
+  null; provider-reported cost (Pi) is never overwritten; costs are never
+  backfilled.
+- The codex app-server adapter now captures the effective model from the
+  schema-required `model` field on `thread/start` / `thread/resume`
+  responses, so `agent.model_effective` (and price-table lookup) resolves
+  without the caller passing `--meta '{"model": ...}'`.
+- Token-semantics are capture-path-aware: new adapter hook
+  `usage_input_includes_cached?` distinguishes codex app-server JSON
+  (cached ⊆ input → billable input = input − cached) from the codex PTY
+  transcript line (input excludes cached → cached prices additively).
+  Verified against the captured schema fixtures and a live app-server row.
+- Price-table lookup now covers Holm's effective `gpt-5.5` model and keys its
+  tier-sensitive rates by the recorded service tier (`standard`, `flex`, or
+  `fast`; `priority` aliases fast). Because published `gpt-5.5` rates split at
+  272K active context, Harnex also requires an observed peak below that boundary;
+  missing/long-context evidence remains unpriced rather than applying the wrong
+  short-context rate.
+- Optional repo phase policy in `.harnex/config.json`: an allowlist can `warn`
+  or `reject` non-canonical effective `meta.phase` values before spawn. Explicit
+  malformed policy files fail closed; no config preserves existing behavior.
+- Bounded events/output retention: 45-day and 1-GiB defaults per directory,
+  repo config plus environment overrides, current/live-session protection,
+  oldest-first age/size pruning, one-hour automatic throttle, and bounded
+  last-prune metadata. `harnex doctor` reports size/limits; `--prune --dry-run`
+  previews bounded candidate paths and `--prune` applies the policy.
+
+### Changed
+
+- **Single tracked telemetry stream** (#63, plan 33 Phase 1): a dispatch
+  now writes exactly two rows to the repo-tracked `.harnex/dispatch.jsonl`
+  — the `dispatch_start` row and one unified v2 `dispatch_end` row that
+  merges the thin envelope (top-level `schema_version: 2`, `record_type`,
+  `id`, `status`, `tier`, timing, `tmux_state`, …) with the rich summary
+  sections (`meta`, `predicted`, `actual`, `agent`, `usage`, `context`,
+  `attribution`, `outcome`, `attempt`, `reliability`, `queue?`,
+  `orchestration?`, artifact-report keys). Start rows stamp
+  `schema_version: 2` as well. Readers accept v1 and v2 rows mixed in one
+  file; `harnex history` keeps skipping pre-0.7.3 envelope-less rows.
+- `--summary-out` is now an explicit-only mirror: no default path. When
+  set, the identical v2 end record is appended there in addition to the
+  tracked stream. Consumers that redirected `--summary-out` to keep rich
+  rows should drop the flag — the tracked stream now carries everything.
+  `Harnex.default_summary_out_path` is removed; every writer and reader
+  resolves the stream through `DispatchHistory.path_for` (git-root walk,
+  global fallback), so non-git roots stream to the global file instead of
+  a repo-local `.harnex/` directory.
+- The `summary` event now points `path` at the tracked stream and carries
+  `mirror_path` when a mirror is configured.
+- `TerminalStatus` resolves a v2 end row as both summary and history in
+  one shot (branching on `record_type` first), so `wait --until done` and
+  `status --id` fall back to the unified stream; legacy duck-types remain
+  for pre-v2 files.
+- Cross-dispatch attempt fields are harness-derived from the canonical stream:
+  `attempts_total`/succeeded/failed, `fallback_triggered`, and
+  `reliability.recovered` follow bounded parent links and degrade safely on
+  missing, duplicate, malformed, or cyclic history. `fallback` is now a public,
+  live-parent-guarded attempt kind; in-run `retry_count` remains separate.
+- Public telemetry/configuration references under `docs/*.md` are now packaged
+  in the gem. README, GUIDE, TECHNICAL, agent guides, and event/telemetry docs
+  use the same canonical-stream, mirror, native-watch, pricing, phase-policy,
+  and retention terminology.
+
+### Fixed
+
+- `harnex history` no longer renders blank rows for pre-0.7.3
+  `{meta, predicted, actual}`-schema telemetry rows in
+  `.harnex/dispatch.jsonl`: rows recognized as neither start nor end
+  records are skipped in both table and `--json` output. The raw file is
+  untouched — legacy rows remain available for forensics.
+
 ## [0.8.0] - 2026-08-02 | 08:46 PM | IST
 
 Minor bump: two behavior changes below (`wait --until done` exit codes,

data/GUIDE.md

@@ -8,11 +8,11 @@ Treat harnex as a local supervisor harness, not as a conversation
 bus between agents.
 
 - Start a fresh worker for each step, usually with `--tmux`
-- Send one clear task, often by pointing the worker at a file
-- Use `--wait-for-idle` as a fence, then inspect with `harnex pane`
-- Ask the worker to write its output to a file when the next step
-  needs structured input
-- Stop the worker when that step is done
+- Give one clear startup task with `--context`; add `--auto-stop` for one-shot work
+- Monitor existing visible work with `harnex watch --until done`
+- Use `--wait-for-idle` only as a follow-up-send fence, then verify the artifact
+- Ask the worker to write its output to a file when the next step needs it
+- Stop completed interactive workers promptly
 
 For multi-step flows, chain fresh workers with file handoffs:
 Codex writes a plan, another Codex implements it, Claude reviews it,
@@ -49,14 +49,18 @@ automatically when the agent is ready. You don't have to wait
 or retry. Queueing exists, but the default workflow should still be
 one task per fresh worker.
 
-For unattended dispatch, prefer built-in monitoring over external poll loops:
+For unattended visible dispatch, prefer the native work-level watcher over
+external poll loops:
 
 ```bash
-harnex run codex --id impl --tmux impl --watch --preset impl
+harnex run codex --id impl --tmux impl \
+  --context "Read and execute /tmp/task-impl.md" --auto-stop
+harnex watch --id impl --until done --max-wait 90m
 ```
 
-This adds a foreground watcher that checks idle activity and performs bounded
-force-resume nudges. For full flag behavior and event-stream consumers, see
+`harnex run --watch --preset impl` is a separate foreground launch-and-stall
+babysitter; do not combine it with `--tmux` or `--detach`. For full flag
+behavior and event-stream consumers, see
 [TECHNICAL.md](TECHNICAL.md) and the built-in monitoring section in
 [README.md](README.md).
 
@@ -262,4 +266,7 @@ harnex agents-guide        # deeper agent-facing guidance
 ## What's next
 
 For the full command reference, flags, HTTP API, and internals,
-see [TECHNICAL.md](TECHNICAL.md).
+see [TECHNICAL.md](TECHNICAL.md). The packaged
+[dispatch telemetry](docs/dispatch-telemetry.md) and
+[configuration](docs/configuration.md) references cover the canonical v2 stream,
+phase allowlists, and log retention.

data/README.md

@@ -60,9 +60,10 @@ job, watch it work, stop it when done.
 ### Run from a temporary/public bundle
 
 Use `--cwd DIR` when the worker should see a specific directory rather than
-the orchestrator's current repo. Harnex starts the wrapped agent in `DIR`, sets
-that directory as the session root, and resolves default telemetry such as
-`.harnex/dispatch.jsonl` there:
+the orchestrator's current repo. Harnex starts the wrapped agent in `DIR` and
+uses it for session attribution. Canonical dispatch telemetry is written to the
+enclosing git root's `.harnex/dispatch.jsonl`; a non-git directory uses the
+global `~/.local/state/harnex/dispatch.jsonl` fallback:
 
 ```bash
 harnex run codex --cwd /tmp/leximaze_eval_run_001 \
@@ -252,14 +253,18 @@ Schema details and compatibility policy are documented in
 
 ## Dispatch history
 
-Every finished `harnex run` writes dispatch records. By default, the terminal
-summary JSONL path is `<session-root>/.harnex/dispatch.jsonl`; `--cwd DIR` makes
-`DIR` the session root, including for non-git temporary bundles. The compact
-history record is repo-local in a git tree and falls back to
-`~/.local/state/harnex/dispatch.jsonl` outside git.
-`harnex history` reads the compact records from that location, and
-`harnex status --id ID --json` / `harnex wait` can use the same durable
-terminal summaries when the live session registry is already gone.
+Every `harnex run` writes exactly one v2 `dispatch_start` row at registration
+and one rich v2 `dispatch_end` row at teardown. Both use the canonical stream:
+`<git-root>/.harnex/dispatch.jsonl` inside a git repo, or
+`~/.local/state/harnex/dispatch.jsonl` otherwise. The end row combines the
+history envelope with usage, context, attribution, outcome, attempt,
+reliability, queue/orchestration, and optional artifact-report sections.
+
+`--summary-out PATH` has no default. It is an explicit compatibility mirror
+that copies the identical `dispatch_end` row to another JSONL file; do not pass
+it merely to preserve rich telemetry. `harnex history`,
+`harnex status --id ID --json`, and `harnex wait` all read the canonical stream
+when the live registry is gone. Mixed legacy v1 and v2 rows remain readable.
 
 Use `harnex history` to inspect it:
 
@@ -312,17 +317,17 @@ harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 \
   --phase implement --intent queue-work --require-attribution ...
 ```
 
-Soft budget metadata is copied into summary `meta`; queue/agent/reliability
-metadata is copied into top-level `queue`, `agent`, and `reliability` summary
-blocks. Every terminal row also has `usage` (so null is distinguishable from
-explicit zero or an estimate), `attribution`, `outcome`, and a joinable
-per-session `attempt` block. Terminal summary `actual` records timing, exit
-classification, token usage when the adapter can capture it, adapter-reported
-`cost_usd` when reliably available, git deltas, task-completion state,
-operational counters (`stalls`, `force_resumes`, `disconnections`,
-`tool_calls`, `commands_executed`), output/event log paths, and rough volume
-measurements such as `lines_changed`, `output_lines`, `output_bytes`, and
-`event_records`.
+Soft budget metadata is copied into end-row `meta`; queue/agent/reliability
+metadata is copied into top-level `queue`, `agent`, and `reliability` blocks.
+Every end row also has `usage` (so null is distinguishable from explicit zero or
+an estimate), `attribution`, `outcome`, and a joinable `attempt` block. When an
+adapter reports tokens but no cost, Harnex may compute provider list-price cost
+only for an exact maintained provider/model/service-tier/context-rate match; such rows use
+`usage.cost_source: "price_table"` and carry `usage.cost_price_as_of`.
+Provider-reported cost remains authoritative, estimates remain labelled, and
+unknown rates stay null. `actual` also records timing, exit classification, git
+deltas, task-completion state, harness-derived cross-dispatch attempt counts,
+operational counters, output/event paths, and bounded volume measurements.
 
 Long queue runners can also opt into logical primary-orchestrator rollups:
 
@@ -423,7 +428,7 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex history` | List completed dispatches from `.harnex/dispatch.jsonl` |
 | `harnex wait --id <id>` | Block until process exit by default; use `--until done` for unattended work completion or `--until task_complete` for exact structured turn completion |
 | `harnex artifact-report init\|validate PATH` | Create or validate bounded `harnex.artifact_report.v1` proof; use `validate --final` before strict completion |
-| `harnex doctor` | Run adapter dependency preflight checks; add `--sweep` for read-only session drift diagnostics |
+| `harnex doctor` | Run dependency and retention diagnostics; `--sweep` reports session drift, `--prune --dry-run` previews retention, and `--prune` applies it |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
 | `harnex recipes` | List and read tested workflow patterns (`show 01`, `show buddy`) |
@@ -442,6 +447,8 @@ longer used. Remove stale `~/.claude/skills/harnex-*` or
 
 - [GUIDE.md](GUIDE.md) — getting started walkthrough with examples
 - [TECHNICAL.md](TECHNICAL.md) — full command reference, flags, HTTP API, architecture
+- [docs/dispatch-telemetry.md](docs/dispatch-telemetry.md) — v2 dispatch stream and field contract
+- [docs/configuration.md](docs/configuration.md) — phase allowlists and events/output retention
 
 ## License
 

data/TECHNICAL.md

@@ -29,6 +29,9 @@ harnex run codex -- --cd ~/other/repo
 | `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
 | `--context TXT`     | Give the agent a task on startup                                    |
 | `--auto-stop`       | With `--context`, stop after accepted task completion               |
+| `--meta JSON`       | Attach bounded caller metadata                                      |
+| `--summary-out PATH` | Mirror the canonical v2 dispatch end row to another JSONL file     |
+| `--phase TEXT`      | First-class phase attribution (optionally repo-allowlisted)          |
 | `--artifact-report PATH` | Expose and ingest a bounded v1 proof sidecar                   |
 | `--require-artifact-report` | Fail closed unless the sidecar is accepted final proof      |
 | `--fast`            | For Codex, use `service_tier="fast"` instead of default `flex`      |
@@ -39,6 +42,20 @@ activity, Git delta, or fresh accepted/no-change report as
 `completed_no_activity`. Strict artifact-report mode works across transports
 and returns non-zero for missing, invalid, rejected, or stale proof.
 
+### `harnex doctor` — Preflight, drift, and retention
+
+```bash
+harnex doctor
+harnex doctor --sweep
+harnex doctor --prune --dry-run
+harnex doctor --prune
+```
+
+Plain output includes adapter prerequisites and events/output retention status.
+`--sweep` adds read-only live-session/tmux drift diagnostics. `--prune --dry-run`
+previews age/size-cap deletions; `--prune` applies them while preserving current
+and live-session files. See [docs/configuration.md](docs/configuration.md).
+
 ### `harnex artifact-report` — Initialize and validate proof
 
 ```bash
@@ -115,8 +132,10 @@ harnex history
 harnex history --json | jq .
 ```
 
-Reads `<repo>/.harnex/dispatch.jsonl`, where `<repo>` is found by walking up
-until `.git/` is present. Use `--global` for the no-repo fallback file.
+Reads the canonical v2 stream at `<git-root>/.harnex/dispatch.jsonl`; use
+`--global` for `~/.local/state/harnex/dispatch.jsonl` outside a repo. Each run
+has one `dispatch_start` plus one rich `dispatch_end`. `--summary-out` is an
+explicit-only end-row mirror, not a second default stream.
 
 ### `harnex logs` — Read session transcripts
 
@@ -246,8 +265,9 @@ Transport file (append-only JSONL):
 ```
 
 Each row uses schema v1 with envelope fields `schema_version`, `seq`, `ts`,
-`id`, and `type`. Emitted today: `started`, `send`, `exited`. `send.msg` is a
-200-character preview with `msg_truncated` when shortened.
+`id`, and `type`. Lifecycle, send, usage, git, summary, attempt, completion,
+and adapter-specific events are additive; consumers must ignore unknown event
+types. `send.msg` is a 200-character preview with `msg_truncated` when shortened.
 
 Schema details and compatibility guarantees are in [docs/events.md](docs/events.md).
 
@@ -300,7 +320,8 @@ When you run `harnex run codex --id worker`:
       hash(repo_root + id) % port_span + base_port
       walk forward until a free port is found
  6. Start HTTP server on 127.0.0.1:<port>
- 7. Write registry file:
+ 7. Opportunistically enforce configured age/size retention for events/output,
+      preserving current and live-session files; then write registry file:
       ~/.local/state/harnex/sessions/<repo_hash>--<id>.json
       and open transcript file:
       ~/.local/state/harnex/output/<repo_hash>--<id>.log

data/docs/codex-appserver.md

@@ -0,0 +1,172 @@
+# Codex `app-server` adapter
+
+harnex 0.6.0 talks to Codex over JSON-RPC 2.0 instead of scraping a
+PTY pane. The adapter spawns `codex app-server` as a subprocess,
+exchanges newline-delimited JSON-RPC messages on stdin/stdout, and
+fans server notifications into the harnex events log.
+
+## Transport
+
+- Subprocess: `codex app-server` (CLI ≥ 0.128.0 — verify with
+  `harnex doctor`).
+- Wire format: one JSON object per line.
+- Encoding: UTF-8.
+- One `Adapter#transport` value: `:stdio_jsonrpc`.
+
+## Handshake
+
+Mirrors `codex-plugin-cc/plugins/codex/scripts/lib/app-server.mjs`.
+
+```ruby
+client.request("initialize", {
+  clientInfo: { title: "harnex", name: "harnex", version: Harnex::VERSION },
+  capabilities: {
+    experimentalApi: false,
+    optOutNotificationMethods: %w[
+      item/agentMessage/delta
+      item/reasoning/summaryTextDelta
+      item/reasoning/summaryPartAdded
+      item/reasoning/textDelta
+    ]
+  }
+})
+client.notify("initialized", {})
+```
+
+After the handshake the client is ready to issue `thread/start` and
+`turn/start` requests.
+
+## Notification → event mapping
+
+| Server notification         | harnex event       | Notes |
+|-----------------------------|--------------------|-------|
+| `thread/started`            | (metadata)         | Stashes `threadId` |
+| `turn/started`              | `turn_started`     | Carries `turnId` |
+| `turn/completed`            | `task_complete` or `task_failed` | Failed/interrupted statuses emit `task_failed` with the Codex error. A completed `--context` turn emits `task_complete` only with structured command/tool activity, Git delta, or fresh accepted/no-change report proof; otherwise it emits typed `completed_no_activity`. |
+| `item/started`              | (silent)           | Streaming deltas opted out |
+| `item/completed`            | `item_completed` + synthesized transcript | See "tmux/STDOUT" below |
+| `error`                     | `error`            | Turn-level Codex error notification; preserves nested `error.message` and does not count as a transport disconnect. |
+| `thread/status/changed`     | (state only)       | Drives state machine |
+| `thread/tokenUsage/updated` | (status field)     | Surfaced via `harnex status --json` |
+| `thread/compacted`          | `compaction`       | Increments `compactions` counter |
+| `account/rateLimits/updated`| (silent, status)   | Visible in `status --json` |
+
+### How disconnects are detected
+
+Disconnects are detected from subprocess exit / EOF on stdout and parse errors
+when the server emits a malformed line. Request-level JSON-RPC error responses
+reject only the in-flight request; they do not by themselves imply that the
+transport disconnected. Schema-defined `error` notifications are turn-level
+Codex errors and feed `last_error` / `task_failed` rather than the disconnect
+counter.
+
+Unexpected transport loss emits `disconnected` and increments
+`auto_disconnects`. Normal auto-stop teardown after `task_complete` /
+`task_failed` is treated as a clean structured close. There is no need for the
+screen-text regex that the legacy adapter relied on.
+
+## tmux / STDOUT — synthesized transcript
+
+Without a PTY, `harnex run codex --tmux` and `harnex pane --id …`
+would otherwise see an empty pane. The JSON-RPC path renders a
+synthesized transcript built from `item/completed` notifications:
+
+- `agent_message` items render their text payload
+- `tool_call` items render as `tool: <name> <one-line summary>`
+
+The synthesized transcript is written to BOTH the output log AND
+STDOUT, so:
+
+- `harnex run codex` (foreground) — user sees the transcript live
+- `harnex run codex --tmux` — the tmux window shows the transcript
+- `harnex pane --id <session>` — captures the synthesized text
+- `harnex logs --id <session>` — replays the same transcript
+
+For interactive debugging where the original Codex TUI is wanted,
+`codex resume <thread-id>` opens the same thread in a real Codex
+CLI.
+
+## `harnex wait --until done` / `task_complete` / `task_failed`
+
+For unattended monitors, block until Codex work completes, fails, or the session exits:
+
+```
+harnex wait --id cx-i-242 --until done --timeout 300
+```
+
+When you need the exact successful structured turn event, wait for `task_complete`:
+
+```
+harnex wait --id cx-i-242 --until task_complete --timeout 300
+```
+
+`--until done` returns non-zero when it sees `task_failed` or failed terminal
+telemetry. This includes acknowledgment-only autonomous `--context` turns
+(`outcome_class=completed_no_activity`) and strict sidecar failures
+(`report_missing`, `report_invalid`, or `report_rejected`). Harnex classifies
+these from app-server item counters, Git state, and the configured report path;
+it does not inspect final-answer prose. The task-complete/task-failed waiters
+tail the events JSONL — not the API socket — so they keep working across
+restarts and are adapter-agnostic.
+
+For blind dispatches that require report proof, combine
+`--artifact-report PATH --require-artifact-report`. Only a fresh valid sidecar
+at `PATH` can satisfy the contract; report-shaped JSON printed in an
+`agentMessage` is ordinary transcript text and is ignored. Use
+`harnex artifact-report init PATH` and `harnex artifact-report validate PATH
+--final` to avoid hand-authoring the schema.
+
+## `harnex doctor`
+
+Verifies the Codex CLI is installed and at version ≥ 0.128.0. JSON
+output, exit 0 if healthy.
+
+```
+$ harnex doctor
+{"ok":true,"checks":[{"name":"codex","required":">= 0.128.0","ok":true,"found":"0.128.0"}]}
+```
+
+## Long-term fallback: `--legacy-pty`
+
+The pre-0.6.0 PTY adapter remains available as a long-term supported
+fallback:
+
+```
+harnex run codex --legacy-pty
+```
+
+It's the right tool when you want the full Codex TUI live in tmux —
+status bars, tool diffs, ANSI panels — that the headless `app-server`
+backend doesn't render. JSON-RPC remains the default and is recommended
+for autonomous worker dispatches; legacy-pty is for interactive/TUI use.
+
+## Troubleshooting
+
+- **`task_complete` never fires.** Check `harnex events --id <session>` first:
+  failed Codex turns emit `task_failed` with the provider/model error. If there
+  is neither `task_complete` nor `task_failed`, run `harnex doctor`; Codex <
+  0.128.0 is unsupported.
+- **Empty tmux pane.** Codex hasn't emitted any `item/completed`
+  yet — the agent is reasoning. The pane fills as soon as the
+  first item completes.
+- **`task_failed` immediately after dispatch.** Check
+  `harnex events --id <session>`. Provider/model failures retain their Codex
+  error message. `completed_no_activity` means the turn ended with no
+  command/tool or Git/report proof; `report_missing` / `report_invalid` /
+  `report_rejected` identify strict sidecar defects. Common provider failures
+  include auth environment variables (for example `OPENAI_API_KEY` /
+  `AZURE_OPENAI_API_KEY`) and model unavailability.
+
+## Schema fixtures
+
+`test/fixtures/codex_appserver/schema/` holds hand-pruned subsets
+of `ServerNotification` and `ClientRequest` for the methods harnex
+issues / consumes. Regenerate via:
+
+```
+codex app-server generate-json-schema --out /tmp/codex-schema-X
+```
+
+then re-prune. The full bundle is ~3 MB; the pruned subsets are
+< 50 KB and serve as a compact reference for what's actually wired
+through the adapter.

data/docs/configuration.md

@@ -0,0 +1,111 @@
+# Repository Configuration
+
+Harnex has one optional repository configuration file:
+
+```text
+<git-root>/.harnex/config.json
+```
+
+It is resolved with the same git-root rule as the canonical dispatch stream.
+Non-git launches use the global dispatch stream and do not invent a global
+configuration file. An absent file is valid. An explicitly present malformed
+file fails before agent spawn so policy is never silently ignored.
+
+## Phase allowlist
+
+Repositories can normalize queue/work phase names:
+
+```json
+{
+  "phase": {
+    "allowlist": [
+      "plan-write",
+      "plan-review",
+      "plan-fix",
+      "test-suite",
+      "implement",
+      "code-review",
+      "code-fix",
+      "mapping",
+      "triage",
+      "docs"
+    ],
+    "policy": "reject"
+  }
+}
+```
+
+The effective value is the first-class `harnex run --phase TEXT` value, or
+`--meta.phase` when no first-class override is supplied.
+
+- No `phase` configuration: any phase passes.
+- Allowlisted phase: dispatches silently.
+- `policy: "warn"`: prints a warning and dispatches.
+- `policy: "reject"`: exits non-zero before spawn and writes no dispatch row.
+
+The allowlist must be an array of non-empty strings. Policy must be `warn` or
+`reject`.
+
+## Events and output retention
+
+Per-session event JSONL and output transcripts live under Harnex's local state
+directory and are not the durable dispatch stream:
+
+```text
+~/.local/state/harnex/events/
+~/.local/state/harnex/output/
+```
+
+Defaults apply independently to each directory:
+
+- maximum age: 45 days;
+- maximum total size: 1 GiB.
+
+Override them in repo configuration:
+
+```json
+{
+  "retention": {
+    "events": {
+      "max_age_days": 45,
+      "max_bytes": 1073741824
+    },
+    "output": {
+      "max_age_days": 45,
+      "max_bytes": 1073741824
+    }
+  }
+}
+```
+
+Environment variables take precedence:
+
+```text
+HARNEX_EVENTS_MAX_AGE_DAYS
+HARNEX_EVENTS_MAX_BYTES
+HARNEX_OUTPUT_MAX_AGE_DAYS
+HARNEX_OUTPUT_MAX_BYTES
+```
+
+Limits must be positive integers. Harnex deletes only regular files directly
+owned by the `events` and `output` directories: expired files first, then the
+oldest unprotected files until the size cap is met. It never follows paths
+outside those directories. Files for the current session, live registry PIDs,
+and alive uncompleted dispatch-start rows are protected. If protected files
+alone exceed a cap, Harnex reports the directory over cap rather than deleting
+them.
+
+A bounded prune runs opportunistically when a dispatch starts. Inspect or force
+the same policy with `doctor`:
+
+```bash
+harnex doctor                    # sizes, limits, and last-prune status
+harnex doctor --prune --dry-run  # preview bounded candidate paths, do not delete
+harnex doctor --prune            # apply now
+```
+
+`--dry-run` is valid only with `--prune`. Manual prune bypasses the automatic
+cadence but preserves the same live/current safety rules.
+
+Set `HARNEX_STATE_DIR` before launching Harnex when tests or isolated automation
+need a disposable local-state root.