Evolve harness executors into a versioned session adapter contract

Traceability

• Spec ID: harness-executor-session-adapter
• Status: Implemented

Intent

The v0.2 execution layer is a one-shot batch surface: HarnessExecutor exposes a single execute(revision, bundle, task) that runs one prompt to completion and returns a HarnessRunResult. This blocks three outcomes:

• Interactive surfaces (harness-studio, TUIs) cannot hold a conversation against a resolved revision; every exchange pays full session startup.
• The executor interface is unversioned, so any change to its shape couples DSL/IR evolution to adapter evolution.
• Runtime-time capability gaps are reported as free-form warnings[] strings instead of typed signals the resolver's degradation model can consume.

Reshape the execution layer after the adapter design of AI SDK 7's HarnessV1 specification (versioned spec tag, harness/session/turn split, capability signalling via optional-method presence plus a typed capability-unsupported error, framework-owned working directory), while keeping what is deliberately different: our adapters bind to natively running hosts, so there is no sandbox-ownership requirement, and the DSL, IR, and resolver semantics do not change.

Acceptance Scenarios

• AC-1: A HarnessAdapterV1 interface exists with specificationVersion: "harness-adapter-v1" (literal), a stable adapterId matching the runtime's adapter package convention, and doStart(options) returning a session. The existing HarnessExecutor batch surface remains exported and behaviourally unchanged, reimplemented as a wrapper that starts a session, runs one prompt turn, and stops.
• AC-2: A HarnessAdapterSession supports multiple sequential doPromptTurn calls against one live host session (conversation state is owned by the host runtime), plus doStop() and doDestroy(). Each turn accepts an abort signal and an event listener; per-turn events reuse the HarnessRunEmitter framing invariants (one run-started first, one run-finished last, framed text, paired tool calls).
• AC-3: A typed HarnessCapabilityUnsupportedError (carrying adapterId and capability) signals a behaviour that is unavailable at run time — for example a turn abortSignal on the Pi SDK, which exposes no abort surface (turn-abort). The batch wrapper degrades an unsupported graceful stop to a doDestroy() fallback plus a warnings[] entry on the result instead of failing the run; the per-turn event stream is already sealed by run-finished at that point, so the degradation is carried on the result, not as a late event.
• AC-4: The framework, not the adapter, owns the working directory: doStart receives a workDir (defaulting to the caller's cwd exactly as today) and adapters use it without deriving their own paths. Behavioural parity: for a single-prompt run, HarnessRunResult (receipt, metrics, events, exit codes) is unchanged for both existing executors.
• AC-5: The Qoder SDK and Pi SDK executors are reimplemented on the adapter contract, and the existing package test suites for exec and compare pass without weakening assertions.
• AC-6: assertRevisionHost still guards every turn: a session started for a revision rejects turns when revision.target.runtime does not match the adapter's host, with the same HarnessHostMismatchError.

Non-goals

• No sandbox provider, bridge mode, or remote execution; adapters keep running in-process against local hosts. Sandbox contracts are a separate future spec if ever needed.
• No interop wrapper for @ai-sdk/harness-* packages in this cycle; this spec only makes our contract shape-compatible so such a wrapper stays cheap later.
• No turn suspension/continuation (doSuspendTurn / doContinueTurn equivalents) or durability across process restarts.
• No DSL grammar, IR version, resolver, or binding-strength change; materialized strength stays capped at advisory.
• No change to harness-studio or harness-ui in this spec; they adopt the session surface in follow-up work.

Plan and Tasks

1. Add src/exec/adapter.ts: HarnessAdapterV1, HarnessAdapterSession, HarnessAdapterStartOptions (revision, bundle, workDir, listener), HarnessCapabilityUnsupportedError, and the runOnce batch wrapper (placed here rather than in executor.ts because events.ts already imports from executor.ts, and the wrapper needs the emitter at runtime).
2. Keep src/exec/executor.ts unchanged: HarnessExecutor, HarnessRunResult, receipt/metrics types, and the preamble builders stay the shared vocabulary of both surfaces.
3. Reimplement src/exec/qoder-sdk.ts and src/exec/pi-sdk.ts as HarnessAdapterV1 implementations; their exported executor factories delegate to the wrapper. Preserve runtime profiles, receipts, redaction, and metrics mapping.
4. Extend src/exec/events.ts only if turn framing requires it; reuse the existing emitter invariants per turn rather than inventing a second event vocabulary.
5. Update src/exec/index.ts exports; deprecate nothing silently — the README section for programmatic execution documents both surfaces.
6. Port test/exec.test.ts coverage to the adapter path and add session tests: multi-turn sequencing, host mismatch per turn, capability unsupported mapping, abort propagation.

Decision rationale: the session split follows AI SDK 7's HarnessV1 (packages/harness/src/v1 in the upstream repo) because it is the closest proven contract for wrapping third-party coding-agent runtimes; we drop its sandbox-ownership precondition because binding to natively running hosts is this DSL's core scenario, and we omit suspend/continue because no current consumer needs slice-boundary recovery.

Test and Review Evidence

• AC-1/AC-4/AC-5: npm run build && npx vitest run in packages/harness — 10 files, 103 tests pass; the pre-existing test/exec.test.ts (17 tests), test/skill.test.ts, and test/compare.test.ts pass against the wrapper without assertion changes.
• AC-2/AC-3/AC-6: new test/adapter.test.ts (10 tests) drives stub host SDKs through multi-turn sessions, asserting event framing invariants per turn (expectFramedTurns), preamble policy per host (persistSession false re-sends, true and Pi send first-turn only), typed capability-unsupported rejection (turn-abort on Pi), graceful-stop degradation to destroy-plus-warning, abort-signal bridging onto the Qoder abort controller, host mismatch before SDK load, turn rejection after stop, and the legacy start-failure event sequence.
• Risk: the Qoder/Pi SDK message loops move from per-run functions into session objects; regression risk is bounded by keeping the batch result shape identical and asserting receipt/metrics equality in existing tests.
• Risk: interface naming (harness-adapter-v1) is new public API surface in @qoder-ai/harness; the README documents the session surface as experimental until harness-studio adopts it.