agent-hitch 0.2.1 → 0.2.2

package/README.md

@@ -6,185 +6,126 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-**Content-addressed version control and evidence storage for agent harnesses.**
+**Reproducible runs for agent harnesses.**
 
-Hitch makes every agent run traceable to an exact harness revision. It resolves
-harness references to immutable identities, prepares content-addressed runnable
-artifacts, executes them through a stable interface, and preserves the
-trajectory and evaluation evidence produced by each run.
-
-Git can identify the harness source that changed. Hitch carries that identity
-through build and execution:
+Hitch runs Codex, Claude Code, Pi, OpenCode, and DeepSeek Harness from exact
+versions or Git commits. Every run links the harness revision, immutable
+artifact, workspace, trajectory, logs, and evaluation evidence.
 
 ```text
-Harness ref
-  -> resolved revision
-  -> prepared artifact
-  -> run / eval
-  -> trajectory
-  -> feedback and evaluation evidence
-
-Hitch controller
-  -> content-addressed runtime bundle
-  -> referenced by containerized evals
+version or commit -> immutable artifact -> run or eval -> verifiable evidence
 ```
 
-Hitch is infrastructure for systems that develop, compare, and evolve agent
-harnesses. It owns version resolution, runnable artifacts, execution records,
-and evidence. Candidate generation, comparison policy, and promotion decisions
-belong to the system using Hitch.
+```bash
+npm install --global agent-hitch
 
-> **Status:** pre-alpha. The core identity and evidence path is implemented,
-> including immutable revision resolution, prepared artifact caching, direct and
-> daemon-backed runs, Harbor-backed evals, content-addressed controller runtimes,
-> DSH-compatible canonical trajectories, and message feedback.
+hitch run \
+  --harness codex@version:0.92.0 \
+  --prompt "Inspect this repository"
+```
 
-## Why harness version control?
+> **Status:** pre-alpha. The core run, provenance, trajectory, feedback,
+> daemon, and Harbor evaluation paths are implemented.
 
-An agent harness is more than a source commit. What actually ran can also depend
-on the package release, build output, controller code, workspace mode, native
-adapter, and mutable executable installed on a machine. A score or transcript
-without those identities is difficult to audit and harder to reproduce.
+## Why Hitch?
 
-Hitch preserves an explicit chain from a requested harness reference to the
-evidence generated by its execution:
+Git tells you which source changed. Hitch tells you exactly what ran and which
+evidence it produced.
 
-| Record | What it identifies |
-| --- | --- |
-| Harness reference | The version, commit, local source, or installed executable requested by the caller |
-| Resolved revision | The immutable source identity selected for the run |
-| Prepared artifact | The validated, content-addressed runnable build |
-| Controller runtime | The exact Hitch runtime uploaded for a containerized eval |
-| Run or eval record | The request, workspace, lifecycle, result, and links between identities |
-| Canonical trajectory | The agent messages and tool activity in a stable DSH-compatible format |
-| Feedback and eval evidence | Message-level feedback, verifier output, rewards, and backend records |
+- **Reproduce** a run from an exact package version or source commit.
+- **Compare** harnesses and models through one execution contract.
+- **Audit** results with immutable artifacts, native events, canonical
+  trajectories, logs, feedback, and eval records.
 
-This is a local versioning and evidence layer, not a replacement for Git and not
-yet a remote artifact registry. Hitch does not currently provide branches,
-tags, diffs, candidate promotion, or rollback policy.
+Hitch is useful for teams building agent evals, harness experiments, coding
+agent infrastructure, and automated promotion pipelines.
 
 ## Quick start
 
-Hitch requires Node.js 22 or newer. Install it from npm:
+Hitch requires Node.js 22 or newer.
 
 ```bash
 npm install --global agent-hitch
 hitch --version
-hitch list --json
-```
-
-Resolve and prepare an exact harness version:
-
-```bash
-hitch resolve codex@version:0.92.0 --json
-hitch prepare codex@version:0.92.0 --json
 ```
 
-Run that exact version in an isolated Git worktree:
+Run an exact harness version in an isolated Git worktree:
 
 ```bash
 hitch run \
   --harness codex@version:0.92.0 \
-  --model gpt-5.6-terra \
-  --cwd /workspace/project \
   --workspace-mode worktree \
-  --prompt-file task.md \
+  --prompt "Inspect this repository" \
   --output jsonl
 ```
 
-Every run writes an atomic manifest and result, raw process logs, normalized
-events, and a canonical trajectory below `~/.hitch/runs/RUN_ID`. Inspect the
-trajectory through the CLI:
+The output includes a run ID. Use it to inspect the saved trajectory:
 
 ```bash
-hitch trajectory inspect RUN_ID --json
+hitch trajectory inspect RUN_ID
 ```
 
-For development from a checkout:
+Every run is stored below `~/.hitch/runs/RUN_ID` with its manifest, result,
+events, logs, and trajectory.
 
-```bash
-npm install
-npm run check
-npm link
-hitch list --json
-```
+## Pin any harness revision
 
-## Harness references
-
-Harness selection is explicit for every run. Exact package versions and Git
-commits resolve to immutable identities and are prepared in Hitch's artifact
-store.
+Harness selection is explicit for every run:
 
 ```bash
-# Use and fingerprint the executable already installed on this machine.
+# Fingerprint and use the executable already installed on this machine.
 hitch run --harness codex@installed --prompt "Inspect this repository"
 
-# Resolve, prepare, or run an exact published version.
-hitch resolve codex@version:0.92.0 --json
-hitch prepare codex@version:0.92.0 --json
+# Resolve and run an exact published version.
 hitch run --harness codex@version:0.92.0 --prompt "Inspect this repository"
 
-# Build a commit from the registered upstream repository.
+# Build and run an exact commit from a registered upstream repository.
 hitch run --harness codex@commit:0123456789abcdef --prompt "Inspect this repository"
-
-# Build a clean commit from a local harness repository.
-hitch run \
-  --harness 'pi@git+file:///workspace/pi#0123456789abcdef' \
-  --prompt "Inspect this repository"
 ```
 
-Bare names such as `codex` are compatibility aliases for `codex@installed`.
-Installed executables are useful for local work, but exact version or commit
-references should be preferred when portability matters.
+| Harness | Installed | Exact package version | Source commit |
+| --- | :---: | :---: | :---: |
+| Codex | ✓ | ✓ | ✓ |
+| Claude Code | ✓ | ✓ | — |
+| Pi | ✓ | ✓ | ✓ |
+| OpenCode | ✓ | ✓ | — |
+| DeepSeek Harness | ✓ | ✓ | ✓ |
 
-Version selectors require exact semantic versions; ranges and mutable tags such
-as `latest` are not accepted. Short commit IDs are expanded and must be
-unambiguous. Local Git repositories must be clean. Codex, Pi, and DeepSeek
-Harness support source-commit preparation; Claude Code and OpenCode currently
-support installed and exact-version sources.
-
-Preparation executes registered package lifecycle or source-build commands with
-the permissions of the Hitch process. Content addressing makes an artifact
-auditable and cacheable; it does not make untrusted build code safe.
+Exact versions and commits are prepared as validated, content-addressed
+artifacts and reused from Hitch's local cache. Installed executables are useful
+for local work; immutable references are better when portability matters.
 
 ## Evidence from every run
 
-Hitch keeps lifecycle events and agent trajectories as two related but distinct
-records:
+Hitch records the chain from request to result:
+
+- requested reference and immutable resolved revision;
+- validated, content-addressed runnable artifact;
+- workspace, model identity, lifecycle, and terminal result;
+- normalized control-plane events and raw process logs;
+- redacted provider-native events where supported;
+- DSH-compatible canonical trajectory with SHA-256-bound files; and
+- versioned message feedback and evaluation evidence.
 
-- normalized JSONL events describe Hitch's control plane, including resolution,
-  preparation, process lifecycle, cancellation, and terminal status;
-- supported adapters preserve redacted provider-native events before any
-  translation, while a DSH-compatible canonical trajectory remains available
-  as a derived view;
-- `trajectory.ref.json` V2 binds every trajectory file by relative path, byte
-  size, role, and SHA-256 digest; and
-- feedback sidecars attach versioned positive or negative ratings and notes to
-  assistant messages without rewriting the immutable trajectory.
+Use the CLI to query runs and attach feedback without rewriting the trajectory:
 
 ```bash
-hitch trajectory inspect RUN_ID
-hitch runs list --context-kind benchmark_task --json
-hitch compare model --benchmark BENCHMARK --task TASK --json
+hitch runs list --json
 hitch feedback list RUN_ID --json
 hitch feedback put RUN_ID \
   --message MESSAGE_ID \
   --rating positive \
-  --note "Kept the change focused" \
-  --json
+  --note "Kept the change focused"
 ```
 
 Machine-contract schemas are versioned in [`docs/schemas`](docs/schemas).
-Runtime validation rejects unknown request fields and preserves typed errors
-across the daemon HTTP boundary.
 
-## Harbor-backed evals
+## Reproducible agent evals
 
-Hitch can evaluate an exact, portable harness revision with
-[Harbor](https://github.com/harbor-framework/harbor):
+Hitch integrates with [Harbor](https://github.com/harbor-framework/harbor) to
+evaluate an exact, portable harness revision in Docker:
 
 ```bash
-# Installs pinned Harbor into ~/.hitch/tools without changing system Python.
 hitch eval setup harbor
 hitch eval doctor
 
@@ -192,164 +133,55 @@ hitch eval run \
   --backend harbor \
   --dataset terminal-bench@2.0 \
   --harness codex@version:0.92.0 \
-  --model openai/gpt-5.6 \
-  --attempts 1 \
-  --max-concurrent 4
-
-hitch eval list
-hitch eval inspect EVAL_ID --json
+  --model openai/gpt-5.6
 ```
 
-Harbor owns task discovery, Docker lifecycle, verification, and rewards. Its
-custom Hitch agent uploads a minimal, SHA-256-addressed Hitch controller runtime
-into each task container and executes the selected harness revision in `/app`.
-The resulting eval record links the request, resolved revision, controller
-runtime, backend configuration and logs, normalized result, reward summary, and
-trajectory evidence.
+Each eval links the resolved harness revision, content-addressed Hitch
+controller runtime, backend configuration, rewards, logs, and trajectory
+evidence. See [Harbor-backed agent evals](docs/evals.md) for setup and
+portability rules.
 
-Eval accepts exact `version:` refs, registered `commit:` refs, and explicit
-local `git+file:///absolute/repo#<full-lowercase-commit>` refs. For local Git,
-Hitch transports a verified exact-commit object pack into each Harbor trial;
-uncommitted files, Git config, credentials, and unrelated history are excluded.
-The local repository must be clean and abbreviated commits, branches, tags,
-`HEAD`, and installed executables are rejected. Common provider credentials are
-forwarded by environment-variable reference; use `--pass-env NAME` for an
-additional variable.
+## Built for automation
 
-See [Harbor-backed agent evals](docs/evals.md) for setup, portability rules, and
-the execution boundary.
+- JSON and JSONL output with versioned schemas and typed errors
+- Direct execution or a persistent daemon with bounded concurrency
+- Shared, detached Git worktree, and independent-copy workspace modes
+- Timeouts, cancellation, process-tree cleanup, and interrupted-run recovery
+- Local state isolation through `--root <path>` or `HITCH_ROOT`
 
-## Stable execution layer
-
-Versioned artifacts still need a consistent way to run. Hitch provides adapters
-for Codex CLI, Claude Code, Pi, OpenCode, and DeepSeek Harness and normalizes
-their invocation and lifecycle behavior behind one machine-oriented contract.
-
-```text
-caller -> Hitch CLI / daemon -> shared run engine -> Codex CLI
-                                             \----> Claude Code
-                                             \----> Pi
-                                             \----> OpenCode
-                                             \----> DeepSeek Harness
-```
-
-The direct CLI and persistent daemon use the same run engine, so revision
-resolution, records, timeout, cancellation, and event behavior do not drift.
-The runtime currently provides:
-
-- executable discovery, version probing, and executable fingerprints;
-- exact package-version and Git-commit resolution;
-- immutable prepared artifacts with integrity-aware caching;
-- direct execution with normalized JSONL events;
-- a persistent local daemon with bounded concurrency;
-- queued and active-run cancellation, timeouts, and process-tree cleanup;
-- managed shared, Git worktree, and independent-copy workspace modes;
-- atomic manifests and results plus raw stdout and stderr logs; and
-- conservative recovery of interrupted records after daemon restart.
-
-Run through the daemon when a long-lived queue is useful:
+Start a queue when you need long-lived execution:
 
 ```bash
 hitch daemon start --max-concurrent 4
-
-hitch run \
-  --daemon \
-  --harness codex@version:0.92.0 \
-  --cwd /workspace/project \
-  --prompt-file task.md \
-  --output jsonl
-
-hitch daemon status --json
-hitch daemon stop
-```
-
-Asynchronous submission and cancellation are also available:
-
-```bash
-hitch daemon submit \
-  --harness claude@version:EXACT_VERSION \
-  --cwd /workspace/project \
-  --prompt-file task.md
-
-hitch daemon cancel RUN_ID
+hitch run --daemon --harness codex@version:0.92.0 --prompt-file task.md
 ```
 
-## State and isolation
-
-State is stored below `~/.hitch` by default. Use `--root <path>` or
-`HITCH_ROOT` to relocate it. Each root owns its artifact store, controller
-runtime store, run and eval records, daemon token, and queue.
-
-Native executable overrides use `HITCH_CODEX_PATH`, `HITCH_CLAUDE_PATH`,
-`HITCH_PI_PATH`, `HITCH_OPENCODE_PATH`, and `HITCH_DEEPSEEK_PATH`.
-
-Workspace modes make mutation boundaries explicit:
-
-- `shared` runs directly in the source directory;
-- `worktree` creates a detached Git worktree from a clean `HEAD`; and
-- `copy` creates an independent filesystem copy.
-
-Workspace isolation is not a process security sandbox.
-
-## Design principles
-
-- **Traceable by default:** every run links the requested reference, resolved
-  revision, runnable artifact, execution record, and evidence.
-- **Immutable resolution:** mutable input is resolved before preparation or
-  execution, then recorded by identity.
-- **Content-addressed reuse:** validated artifacts and controller runtimes are
-  reused by digest rather than copied per run.
-- **Evidence without lossy abstraction:** stable canonical records coexist with
-  raw harness output and explicit trajectory fidelity.
-- **Machine-first contracts:** structured output, versioned schemas, and typed
-  failures are the public interface.
-- **Policy lives above Hitch:** mutation, ranking, promotion, and rollback remain
-  explicit decisions for the calling system.
-- **Safe interruption:** cancellation targets the complete subprocess tree, and
-  interrupted workspace-mutating runs are never replayed implicitly.
-
-## Planned work
-
-- [x] Strict model/harness comparison primitives over run evidence
-- [ ] Named candidate and champion references
-- [ ] Promotion and rollback records without embedding promotion policy
-- [ ] Remote artifact and evidence synchronization
-- [ ] Additional harness adapters
-- [ ] Additional API provider support
-- [ ] Local model inference support
-
-## News
-
-- **2026-08-20:** Hitch 0.2 development moved the project to strict TypeScript
-  compiled to ESM, added a shared SHA-256 controller runtime cache, recorded a
-  DSH-compatible canonical trajectory for every run, and introduced
-  lifecycle-bound message feedback.
-- **2026-08-13:** Hitch added DeepSeek Harness support.
-
 ## Documentation
 
-- [Hitch 0.2 development spec](docs/hitch-0.2-development-spec.md)
-- [Design document](docs/design.md)
-- [Agent daemon analysis and port](docs/daemon.md)
-- [Workspace isolation](docs/workspaces.md)
+- [Design and architecture](docs/design.md)
 - [Harbor-backed evals](docs/evals.md)
+- [Workspace isolation](docs/workspaces.md)
+- [Daemon design](docs/daemon.md)
+- [Hitch 0.2 development spec](docs/hitch-0.2-development-spec.md)
 - [Release process](docs/releasing.md)
 
-## Community
+## Project status
 
-Join the [Hitch community on Discord](https://discord.gg/cZ4NBbHDk) to ask
-questions, share feedback, and discuss agent-harness infrastructure.
+Hitch is a pre-alpha local versioning and evidence layer. It complements Git;
+it does not currently provide a remote artifact registry, branches, tags,
+candidate promotion, or rollback policy.
 
-## Acknowledgements
+Remote artifact synchronization, named candidates, promotion records, and more
+harness adapters are planned.
 
-Hitch draws inspiration from [Multica](https://github.com/multica-ai/multica) and
-uses [Harbor](https://github.com/harbor-framework/harbor) as its evaluation
-backend. We are grateful to both projects for the foundations they provide.
+## Community
 
-## Naming
+Join the [Hitch community on Discord](https://discord.gg/cZ4NBbHDk) to ask
+questions, share feedback, and discuss agent-harness infrastructure.
 
-The repository is named `agent-hitch`; the product and executable are named
-`Hitch` and `hitch`.
+Hitch draws inspiration from [Multica](https://github.com/multica-ai/multica)
+and uses [Harbor](https://github.com/harbor-framework/harbor) as its evaluation
+backend.
 
 ## License