Guided tour

1. What Ultimate Harness Is

Start with the README to see the core idea: UH is not another coding agent but a harness that sits above agent runtimes and standardizes the durable artifacts around agentic work. A request becomes a mission packet, runs through a runtime adapter inside a sandbox, is verified, reviewed by a human and finally promoted. The package manifest shows how that ships: a single uh bin built from dist/cli.js, Node 20+ for the CLI, and Bun for packaging and the TUI.

README.md: Project overview for Ultimate Harness describing the runtime-agnostic mission lifecycle, the ten runtime adapters and their status, run-control operations, documentation index, install and quick-start commands, runtime overrides, durable artifacts and the safety model.
package.json: npm package manifest for @agenticengineeringagency/ultimate-harness v0.11.0 exposing the uh bin from dist/cli.js, pinning Node 20+/Bun 1.3.14+, and defining dev, build, test, typecheck, docs, TUI spike and Hermes plugin scripts plus OpenTUI, Solid, Commander, YAML and Zod dependencies.

2. The CLI Dispatcher

src/cli.ts is the entry point and has the widest reach in the graph (fan-out 58). It uses Commander to wire every command (mission, run, verify, promote, team, queue, tui and more) to a harness module. The project rule is that it keeps no lifecycle logic of its own, although about 2,400 lines of handler logic still live in it today. The rule: behavior lives in src/harness/, contracts in src/schema/, and runtime-specific execution in src/adapters/, which is the order the rest of this tour follows. It is meant to stay a thin dispatcher, but it has grown to about 3,700 lines on the v0.11 line; splitting it into per-group command modules is the first item on the technical debt register.

src/cli.ts: Commander-based uh CLI dispatcher wiring every command (mission, run, verify, promote, team, queue, experiment, tui, etc.) to harness lifecycle modules and runtime adapter wirings.

3. Zod Artifact Contracts

Every file UH persists under .harness/ is defined first as a Zod schema, and these are among the most depended-on files in the codebase. mission.ts describes the mission packet (acceptance criteria, expected artifacts, runtime requirements, team workers), artifacts.ts covers runtime results, verification and promotion records, and runs.ts defines the per-run index. Any change to persisted YAML or JSON starts here, and every later step validates against these shapes.

src/schema/mission.ts: Central Zod schema for mission.yaml packets: issues, acceptance criteria, expected artifacts, team workers, runtime requirements, decision policy, runtime config and TDD defaults, plus validateMission.
src/schema/artifacts.ts: Core Zod contracts for persisted harness artifacts: skills and sandboxes indexes, verification results, promotions, runtime sessions and runtime results including usage, pricing and verdict records, plus their validators.
src/schema/runs.ts: Zod schemas for per-run artifact directories: the latest.json run pointer, run status enum and the append-only runs/index.json history.
src/schema/runtime-control.ts: Runtime control contracts: tool-guard fields/policy with protected paths, runtime limits, recovery policy, routes, stop codes, steer/cancel requests and Windows job results.

4. The .harness Artifact Store

Building on the schemas, these modules decide where artifacts live and how they are written safely. paths.ts is the most imported file in the project (fan-in 43) and builds every canonical .harness location. run-id.ts gives each run its own directory plus latest.json and runs/index.json, and artifact-transaction.ts provides write-temp-then-rename and an exclusive lock so a crash cannot leave a half-written artifact.

src/harness/paths.ts: Canonical path builders for every .harness location: project.yaml, adapters, workflows, skills, specs, missions, runs, sandboxes, and audit logs.
src/harness/run-id.ts: Per-run artifact directory plumbing (UH-82/UH-90): generates and validates run ids, maintains latest.json and runs/index.json, mirrors the latest runtime result and prunes old runs.
src/harness/artifact-transaction.ts: Atomic artifact write primitives: rename with retry on transient Windows errors, write-temp-then-rename, and an exclusive artifact transaction lock using a named pipe on Windows and a bounded filesystem lock elsewhere.

5. Authoring a Mission

A mission starts here. uh init scaffolds the .harness tree with project.yaml and default workflow profiles, and propose.ts creates a mission packet from CLI options or a spec file. mission.ts holds the shared guards (ids, workflow profiles, symlink and root containment), and mission-check.ts is the pre-launch linter that validates the packet against the Step 3 schema, context files and expected outputs before anything runs.

src/harness/init.ts: Initializes a project’s .harness directory tree with project.yaml, skills and sandbox indexes, an audit log, and default workflow profiles.
src/harness/propose.ts: Creates new mission packets for uh mission propose, either from CLI options or from a uh.spec.v0 spec file, validating the in-memory document before writing, and parses issue-ref and required-check CLI specs.
src/harness/mission.ts: Mission creation and shared mission guards: scaffolds mission.yaml with an optional design.md, and validates mission ids, initialized projects, workflow profiles, symlinks, and root containment.
src/harness/mission-check.ts: Pre-launch mission packet checker that validates YAML, schema self-consistency, context files, runtime overrides, independent-review packets, expected outputs, change-only constraints, and grounding, rendering PASS/FAIL lines.

6. Admission and Routing

Before a process is spawned, UH decides whether and where a mission may run. auto-route.ts picks the cheapest adapter that meets the mission’s runtime requirements, runtime-requirements.ts and capabilities.ts match those requirements against each adapter’s capability manifest, and fleet-policy.ts refuses a model/adapter/role combination the project has not authorized to spend. The manifests follow the adapter-capabilities schema, so admission is a data comparison and not a guess.

src/harness/auto-route.ts: Adapter auto-routing: deterministic Level 0 selection of the cheapest adapter satisfying mission runtime requirements, combined with a bounded Level 1 TypeSafe/JEV semantic recommendation, plus explain and summary formatters and decision receipts.
src/harness/runtime-requirements.ts: Matches a mission’s runtime_requirements (network, shell, fs write, cost class) against adapter capability declarations and asserts eligibility.
src/harness/capabilities.ts: Preflight capability enforcement that matches a mission’s required capability tags against the selected runtime adapter’s manifest, with error, warn, or off severity for run, dry-run, and run-all.
src/harness/fleet-policy.ts: Fleet spend authorization that decides whether a model may run on a given adapter and role according to the project’s fleet policy, refusing runs before any process spawns.
src/schema/adapter-capabilities.ts: Zod schema for uh.adapter-capabilities.v0 manifests describing an adapter’s cost class, tool capabilities and sandbox support, with a validator.

7. Prompt and Sandbox Preparation

An admitted mission gets two things: a prompt and an isolated workspace. dispatch-context.ts is the single builder of the dispatch context shared by all adapters (project brief, verified hive facts, workflow profile, final-message sentinel), and render-prompt.ts turns it into canonical prompt text. sandbox.ts creates the git-worktree or directory sandbox the agent works in, with a lock-serialized index so parallel runs do not collide.

src/harness/dispatch-context.ts: Single shared builder for the pre-inlined mission dispatch prompt used by all runtime adapters, including the capped project brief, verified hive facts, workflow profile, and the final-message sentinel instruction.
src/harness/render-prompt.ts: Renders the canonical mission prompt text from a DispatchContext, preserving legacy section order and adding constraints, acceptance criteria and memory blocks.
src/harness/sandbox.ts: Sandbox lifecycle orchestrator: create, list, status, discard and repair sandboxes with a lock-serialized sandboxes index, exclusive file locks with stale-owner breaking, mission seeding and mission-root routing.

8. Runtime Adapters

Adapters are where UH meets a real agent CLI or API. Each one (Hermes, Codex, oh-my-pi and the others) plans a run from the Step 7 dispatch context, launches or calls the runtime, parses its native output and maps it to a runtime session and result. _artifact-context.ts is the shared helper every adapter uses to resolve and write per-run artifacts with path-escape guards, which keeps adapters thin and interchangeable.

src/adapters/_artifact-context.ts: Shared mission-artifact context for runtime adapters: resolves the per-run .harness/missions/<id>/runs/<run-id>/ paths with symlink and path-escape guards and provides the write helpers every adapter uses to persist prompts, sessions and events.
src/adapters/hermes.ts: Hermes Agent CLI runtime adapter: version gating, run planning with dispatch context and Honcho memory, subprocess execution and parsing of the final block into a runtime session.
src/adapters/codex.ts: Codex CLI runtime adapter with a strict runtime-config schema, CLI check, planner, streaming runner, JSONL event parsing, quota-error detection and session collection that maps exit codes and final result blocks to runtime-result status; optionally integrates Honcho memory.
src/adapters/oh-my-pi.ts: oh-my-pi (omp) runtime adapter, the default executor: plans guarded runs with recovery and snapshots, streams live output, detects quota errors, and collects sessions with route verification.

9. Supervised Execution

Adapters do not supervise themselves; the harness does. runtime-process.ts launches the worker, captures output live and feeds it to runtime-supervision.ts, which watches native events for terminal failures, budget caps, stalls and Tool Guard denials. tool-guard.ts classifies each tool call and blocks writes outside the worker root, git mutations and package installs, and runtime-settlement.ts reconciles the final runtime-result.yaml against the control receipt, so a run always ends in a recorded state.

src/harness/runtime-process.ts: Core runtime process runner: launches a runtime worker (with a Windows guardian job when needed), captures output live, feeds supervision, run digest and loop watchdog, handles cancellation and settles the run.
src/harness/runtime-supervision.ts: Runtime supervision over native events: terminal failure and budget-cap detection, route verification, Tool Guard evidence and denial accounting, protected-root shell mutation checks, and stall/deadline/thinking watchdogs.
src/harness/tool-guard.ts: Runtime tool-call guard that classifies agent tool invocations (shell, write, read, agent-spawn tools) and denies writes outside the worker root, git mutations, deletes, package installs, network or agent clients, protected-root or hive access, guard tampering and containment escapes, parsing shell commands for redirections, cd changes, substitutions and variable assignments.
src/harness/runtime-settlement.ts: Settlement reconciliation: confirms guardian owner-loss receipts, settles native budget caps (including deadline grace), and reconciles runtime-result.yaml against the runtime-control.json receipt.

10. Verification and Review

Finishing a run does not mean the work is accepted. verify.ts runs the mission’s required checks and acceptance-criterion commands inside the sandbox, output-verification.ts confirms the expected artifact really exists, and post-checks.ts adds operator-defined gates. independent-review.ts prepares a separate review mission that snapshots worker outputs with hashes, and verdict.ts records a manual verdict. None of these can promote work on their own.

src/harness/verify.ts: Mission verification pipeline: runs required checks and acceptance-criterion commands (optionally inside the mission’s sandbox) with timeouts, checks expected outputs, gathers diff, hive, independent-review and decision-receipt signals, optionally consults TypeSafe System One, and writes the verification result.
src/harness/output-verification.ts: Verifies a mission’s declared expected artifact is a non-empty regular file inside the workspace (after realpath resolution), optionally checking JSON validity and a completion marker, and returns a verification check record.
src/harness/post-checks.ts: Runs operator-defined post-checks (from a YAML/JSON file outside the mission) after a mission run, records only check names and outcomes into runtime-result.yaml and mission mirrors, and gates the run’s exit code on their results.
src/harness/independent-review.ts: Prepares self-contained independent-review missions that snapshot worker outputs with hashes, and collects and validates review reports for provenance and recommendation without ever approving or promoting work.
src/harness/verdict.ts: Records a manual verdict (UH-76) on an existing runtime-result.yaml while preserving its other fields, and appends a verdict.recorded line to .harness/audit.log.

11. Promotion and Landing

This is the end of the lifecycle from Step 1. promote.ts requires a passed verification and writes a promotion.yaml decision, and land.ts cherry-picks verified worker branches into a target worktree only after checking verification, clean independent reviews bound to the branch tip, forbidden patterns and a hash-chained record. These gates are the reason the earlier steps keep such careful records.

src/harness/promote.ts: Implements uh mission promote: validates a mission id and paths against symlink and traversal attacks, requires a passed verification, and writes a promotion.yaml decision plus a mission event.
src/harness/land.ts: Gated cherry-pick of verified worker branches into a target worktree, enforcing passed verification, clean independent reviews bound to the branch tip, forbidden-pattern scans, checks, and a hash-chained land decision index.

12. Run Control and Teams

Beyond single missions, UH coordinates many runs. live-runs.ts is the registry of in-flight attempts that kill.ts and other operator controls act on. queue.ts launches missions in dependency order under concurrency and memory limits and settles each entry from recorded artifacts, not from child exit codes. team-run.ts runs N adapter-bound workers in separate worktrees and integrates their branches through a leader worktree before verifying the result.

src/harness/live-runs.ts: Project-root registry of in-flight runtime attempts under .harness/live-runs, combined with a bounded scan for runtime-control files to discover runs, compute liveness verdicts, list process trees, and back uh ps.
src/harness/kill.ts: Implements uh kill: resolves run selectors against live runs, stops controllers and owned process trees, settles orphaned runs, marks team state cancelled, and reports proof that native processes are gone.
src/harness/queue.ts: UH queue scheduler: launches missions in dependency order under an orchestrator cap and free-memory floor, settles each entry from recorded run artifacts (never child exit), and persists resumable state under .harness/queue.
src/harness/team-run.ts: Team mission runtime (UH-72) that plans N adapter-bound workers in dedicated git worktrees, runs them under resource waves, integrates their branches through a leader worktree, verifies the integrated result, and persists canonical team state, salvage records and an integration report.

13. Status, MCP and Telemetry

These read-only views expose harness state without running anything. status.ts gives the human summary and status-json.ts produces the stable uh.status.v0 document read straight from disk. mcp-server.ts exposes status and runs as uh_status, uh_runs and uh_run tools over JSON-RPC so other agents can inspect UH. telemetry.ts is opt-in PostHog, sends only aggregate command metadata, and is configured through the placeholders in .env.example.

src/harness/status.ts: Human uh status summary: counts adapters, workflows, missions, audit lines, skills, sandboxes by status, and passed or promoted missions from the harness directory.
src/harness/status-json.ts: LLM-less uh status --json mode (UH-78): produces a stable uh.status.v0 document of adapters, missions, recent runs and live runs read from disk without spawning subprocesses.
src/harness/mcp-server.ts: Read-only MCP server exposing project status, indexed runs, run groups, and run artifacts as uh_status, uh_runs, and uh_run tools over newline-delimited JSON-RPC 2.0, serving both stateless and legacy protocol generations.
src/harness/telemetry.ts: Opt-in PostHog telemetry for the uh CLI: loads config from UH_TELEMETRY/UH_POSTHOG_* env vars, builds an aggregate-only payload (command, status, exit code, duration, version, platform), refuses private capture endpoints, and installs Commander hooks that fire an exit-safe detached beacon.
.env.example: Safe placeholder environment template covering the OpenRouter adapter key, opt-in PostHog telemetry settings, and Hermes dashboard plugin variables (project root, CLI binary, timeouts and artifact size caps).

14. TUI and Hermes Dashboard

The two visual surfaces build on the same artifacts and CLI, not on private internals. The OpenTUI Mission Control (uh tui, run under Bun) reads .harness/ through model.ts and starts runs by spawning uh mission run from run-orchestrator.ts, so adapter logic is never duplicated. The Hermes plugin follows the same rule: plugin_api.py is a FastAPI bridge to the public uh CLI and .harness files, and the small React bundle in App.tsx uses the host SDK’s React without bundling its own.

src/tui/index.tsx: Bun entry point for uh tui: side-effect imports adapters to register runtime checkers, resolves the project root and renders the Dashboard with the resolved theme.
src/tui/model.ts: Renderer-free dashboard snapshot reader that loads harness info, adapters, missions, sandboxes and mission detail from the .harness/ tree, tolerating missing or malformed files.
src/tui/run-orchestrator.ts: Spawns the uh mission run CLI as a child process from the TUI so adapter dispatch logic is never duplicated.
apps/hermes-plugin/dashboard/plugin_api.py: FastAPI router mounted at /api/plugins/uh that bridges the Hermes dashboard to the uh CLI and on-disk .harness/ artifacts: status, missions, runs, SSE event tails, run start/cancel, run comparison, workflows, verification, and mission creation, with safe-id validation, subprocess timeouts, retention pruning, and a uniform JSON error shape.
apps/hermes-plugin/dashboard/src/App.tsx: Root React component of the uh Hermes dashboard plugin that reads the hash route and dispatches to the Delivery Observatory, mission drilldown, wizard, and workflow viewer/editor views.