harnex 0.8.0 → 0.10.0

data/docs/codex-appserver.md

@@ -0,0 +1,175 @@
+# 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 or a Git delta; otherwise it emits typed `completed_no_activity`. Harnex writes the observed-state receipt before the successful event. |
+| `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 the rare receipt-write failure
+(`report_invalid`). Harnex classifies completion from app-server item counters
+and Git state; it does not inspect final-answer prose or trust worker claims.
+The task-complete/task-failed waiters
+tail the events JSONL — not the API socket — so they keep working across
+restarts and are adapter-agnostic.
+
+Every blind dispatch receives a harness-authored receipt. No worker report is
+required: Harnex captures command exits, Git state, completion, and usage, then
+writes `HARNEX_ARTIFACT_REPORT_PATH` before emitting `task_complete`. Use
+`--artifact-report PATH` only to choose a fixed destination; otherwise the
+status/end row points to the default state-directory path. Review workers may
+write advisory summary/verdict/P1-P3 counts to `HARNEX_ARTIFACT_CLAIMS_PATH`.
+Claims and report-shaped `agentMessage` text cannot satisfy the activity gate.
+Consumers can run `harnex artifact-report validate PATH --final` afterward.
+
+## `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 activity. `report_invalid` now primarily identifies a
+  harness receipt-write failure; old rows may still contain the legacy
+  `report_missing` / `report_rejected` classes. 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,118 @@
+# 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, output, and receipt retention
+
+Per-session event JSONL, output transcripts, and generated proof receipts live
+under Harnex's local state directory and are not the durable dispatch stream:
+
+```text
+~/.local/state/harnex/events/
+~/.local/state/harnex/output/
+~/.local/state/harnex/receipts/
+```
+
+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
+    },
+    "receipts": {
+      "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
+HARNEX_RECEIPTS_MAX_AGE_DAYS
+HARNEX_RECEIPTS_MAX_BYTES
+```
+
+Limits must be positive integers. Harnex deletes only regular files directly
+owned by the `events`, `output`, and `receipts` 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.