relayburn-cli: HarnessAdapter trait + registry + pending-stamp factory (#248 part b)

[willwashburn]

Wave 1 D4 of the Rust port (epic #240, sub-issue #248). Lands the harness substrate that Wave 2's three adapter PRs (claude / codex / opencode) plug into.

Split

#248 is split three ways for parallelism:

• a — CLI scaffold (sibling PR): clap root, subcommand stubs, render helpers (commands/, cli.rs, main.rs, render/).
• b — harness substrate (this PR): HarnessAdapter trait, lazy registry, pending-stamp factory.
• c — golden snapshots: TS-side capture of burn <command> output Wave 2 commands diff against.

Once a + b + c land, Wave 2 can start the eight-PR fan-out. b unblocks the three adapter PRs (#248-d/e/f).

Summary

• HarnessAdapter trait at crates/relayburn-cli/src/harnesses/mod.rs mirrors packages/cli/src/harnesses/types.ts: name, session_root, plan, before_spawn, start_watcher (optional), after_exit. Async methods desugar via async-trait. Supporting types (PlanCtx, SpawnPlan, WatcherController) line up with the TS sibling.
• Lazy compile-time phf::Map registry at crates/relayburn-cli/src/harnesses/registry.rs with lookup / list_harness_names. Slots are reserved but empty with comments naming the Wave 2 PR that populates each one (claude → [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-d, codex → [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-e, opencode → [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-f).
• pending_stamp::adapter factory at crates/relayburn-cli/src/harnesses/pending_stamp.rs mirrors createPendingStampAdapter. Codex + opencode ([Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-e/f) construct adapters through it so the manifest writer + watch-loop wiring lives in one place. before_spawn calls relayburn_sdk::write_pending_stamp; start_watcher returns a controller from relayburn_sdk::start_watch_loop.
• relayburn-sdk re-exports the watch-loop + pending-stamp surface (start_watch_loop, WatchController, write_pending_stamp, PendingStampHarness, …) so the CLI doesn't reach into private SDK modules.
• New [lib] target in relayburn-cli so the harness substrate can be unit-tested with cargo test -p relayburn-cli without disturbing main.rs (owned by the parallel [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-a scaffold PR).

What Wave 2 adapter PRs need to know

• claude ([Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-d): implement HarnessAdapter directly (the eager-stamp path); start_watcher returns None. Add a static CLAUDE_ADAPTER and one row to ADAPTERS in registry.rs.
• codex ([Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-e), opencode ([Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-f): build a PendingStampAdapter config and call pending_stamp::adapter(config) to get an HarnessAdapter. Box-leak it to a &'static; register in ADAPTERS. The ingest_sessions closure should call relayburn_sdk::ingest with the harness's roots only.
• The CLI scaffold ([Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-a) doesn't yet wire mod harnesses; into main.rs; the burn run driver lands in [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-d (Wave 2 D5) and is where harness lookup gets hooked up.

Test plan

• cargo build --workspace clean (no warnings)
• cargo test -p relayburn-cli passes (9 tests: trait round-trip, registry lookup with a static fake, codex/opencode factory round-trips, should_panic on unknown harness, empty-registry invariant, after_exit invokes the supplied ingest fn)
• cargo test --workspace still passes (619 tests total: 9 CLI + 605 SDK lib + 2 SDK integration + 3 doc tests)
• No edits to main.rs / cli.rs / commands/* (owned by the parallel [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-a worktree)
• Manually verify the registry test fails when a stub adapter is added (post-merge sanity check before [Rust port] relayburn-cli: clap CLI + mcp-server subcommand (closes #210) #248-d lands)

Closes part b of #248. Parent epic: #240.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d43e31a-e221-4a9f-b971-5bd5b347a6ff

📥 Commits

Reviewing files that changed from the base of the PR and between 09cc4e0 and 6efc89f.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• CHANGELOG.md
• crates/relayburn-cli/Cargo.toml
• crates/relayburn-cli/src/harnesses/mod.rs
• crates/relayburn-cli/src/harnesses/pending_stamp.rs
• crates/relayburn-cli/src/harnesses/registry.rs
• crates/relayburn-cli/src/lib.rs
• crates/relayburn-sdk/src/lib.rs

---

📝 Walkthrough

Walkthrough

This PR introduces a harness adapter substrate for relayburn-cli, enabling pluggable adapters to manage spawned harness processes through a trait-based lifecycle (before_spawn, start_watcher, after_exit). It includes a phf-based registry for static adapter lookup, a concrete pending-stamp adapter, and expanded SDK re-exports for CLI integration.

Changes

Harness Adapter Infrastructure

Layer / File(s)	Summary
Library Setup & Dependency Graph crates/relayburn-cli/Cargo.toml, crates/relayburn-cli/src/lib.rs	Library target added to Cargo.toml with dependencies on anyhow, async-trait, phf, and tokio. New lib.rs exposes public harnesses module for testing and adapter integration.
Core Trait & Data Structures crates/relayburn-cli/src/harnesses/mod.rs	Defines public HarnessAdapter trait with lifecycle hooks (before_spawn, start_watcher, after_exit). Introduces PlanCtx (harness run context) and SpawnPlan (process spawn specification). Adds WatcherController wrapper around SDK's WatchController.
Static Registry Pattern crates/relayburn-cli/src/harnesses/registry.rs	Implements lazy phf\::Map-based harness registry with lookup(name) and list_harness_names() functions. Includes test scaffolding with FakeAdapter and comments for future Wave 2 adapter wiring.
Pending-Stamp Adapter Implementation crates/relayburn-cli/src/harnesses/pending_stamp.rs	Concrete adapter implementation: writes pending stamp before spawn, configures interval-based watch loop via StartWatchLoopOptions, and invokes supplied ingest callback on process exit. Factory function adapter(config) returns boxed trait object.
SDK Public Surface crates/relayburn-sdk/src/lib.rs	Expanded ingest re-export block to include IngestFn, ErrorSink, PendingStamp, PendingStampHarness, ReportSink, WatchController, StartWatchLoopOptions, and new PendingStampWriteOptions alias. Enables CLI to access SDK types without direct dependency coupling.
Documentation CHANGELOG.md	Added Unreleased section enumerating harness substrate, SDK re-exports, and Wave 2 adapter scaffolding notes with PR references.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI Driver
    participant HA as HarnessAdapter Impl
    participant Proc as Spawned Process
    participant Watch as WatchController
    participant Ingest as Ingest System

    CLI->>HA: plan(ctx)
    HA->>CLI: SpawnPlan
    CLI->>HA: before_spawn()
    HA->>HA: write_pending_stamp()
    CLI->>Proc: spawn(plan)
    Proc-->>CLI: pid
    CLI->>HA: start_watcher()
    HA->>Watch: start_watch_loop(options)
    Watch->>Ingest: watch & ingest sessions
    Ingest-->>Watch: IngestReport
    Proc->>Proc: runs...
    Proc-->>CLI: exit
    CLI->>HA: after_exit(report)
    HA->>Ingest: ingest_sessions_callback()
    Ingest-->>HA: ✓

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Burn #248: Implements the HarnessAdapter trait, phf-based registry, and pending-stamp adapter factory described in the issue for Wave 2 adapter infrastructure.

Possibly related PRs

• AgentWorkforce/burn#299: Expands relayburn-sdk public re-export surface with Ledger/LedgerHandle APIs alongside the ingest re-exports added here.
• AgentWorkforce/burn#296: Adds relayburn-ingest gap-warning and reingest_missing_content APIs that the harness pending-stamp adapter may coordinate with via the ingest callback.

Poem

🐰 Adapters now nest in registries tight,
Harnesses spawn with a phf map's delight,
Pending stamps written before the race,
Watchers ingest at a steady pace,
Five-step lifecycle—a pattern so clean!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically identifies the main changes: HarnessAdapter trait, registry implementation, and pending-stamp factory for relayburn-cli, correctly referencing PR #248 part b.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the harness substrate implementation, split rationale, trait design, registry approach, factory pattern, and SDK re-exports with clear guidance for Wave 2 adapter PRs.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rust-port/cli-harness-adapter

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}