Add omp as a fifth native driver (#346)

* Add omp as a fifth native driver

omp is pi-family (loads pi-style extensions, reads PI_* env fallbacks), so
this follows the pi driver's shape: a typed `omp {}` block, an `omp-session`
wrapper owning the presence lease and the terminal observed-state record, and
an injected `omp-channel.ts` extension delivering inbox messages natively over
the shared newline-JSON frame protocol.

Where omp measurably diverges from pi (v18.0.3, 2026-08-25 captures in
docs/vrs/06-omp-driver/.experiments/), the code diverges deliberately:

- No `agent_settled` event exists, so the idle edge is `agent_end` followed by
  bounded `ctx.isIdle()` polling instead of pi's settled event.
- omp exposes `tool_approval_requested`/`tool_approval_resolved`, which the
  channel projects onto the blocked-on-human axis pi cannot express; the Rust
  channel loop parses the optional blockedOn/ask/reason frame fields for both
  harnesses.
- The delivery-critical surface is versioned behavior rather than API
  contract, so the wrapper hard-gates the provider major (18.x) under the
  codex/opencode admission convention instead of degrading silently.
- The channel asset is forked, not shared: each harness's correctness must not
  depend on the other's branch. Fresh ST2_OMP_CHANNEL_* env names keep a seat
  from adopting stray pi channel configuration.

Verified live on dev3: presence lease, seeded and transitioning observed
state, restored-context seeding, and native message delivery into the running
TUI. VRS for the subsystem lives in docs/vrs/06-omp-driver/ with decision
0007; DQ-OMP-1..5 record the unmeasured residuals (deny path, ask-axis
discrimination, steer/modal visuals, update-banner suppression).

agent-identity: unknown
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.0.3
agent-runtime: OMP 18.0.3
tooling-profile: dotfiles@929dc21

* Tighten omp version gate to exact verified versions; treat a lone omp block as a spec candidate

Review findings: the major-only comparison admitted unverified 18.x minors against OMP-R05's per-minor admission contract, so admission is now an exact verified-version list like the opencode gate; and looks_like_spec now counts an omp driver block as an agent-shaped signal, matching every other provider.

agent-identity: unknown
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.0.3
agent-runtime: OMP 18.0.3
tooling-profile: dotfiles@929dc21

* Bind idle polling to its originating channel session

Codex review: a session replacement during the post-agent_end polling window could let the retired context publish idle into the successor's channel; the poll now drops its result when state.child has moved on.

Author: schickling-assistant

crates/agent-spec/src/kdl_format.rs

@@ -9,7 +9,8 @@
 
 use crate::declared::{DeclaredDocument, DeclaredNode, DeclaredValue};
 use crate::spec::{
-    ClaudeDriver, CodexDriver, OpenCodeDriver, PiDriver, RawResource, RawRestart, RawSpec, RawTask,
+    ClaudeDriver, CodexDriver, OmpDriver, OpenCodeDriver, PiDriver, RawResource, RawRestart,
+    RawSpec, RawTask,
 };
 
 /// Lower an already parsed declaration document into the runner's raw representation.
@@ -173,6 +174,13 @@ fn agent_node_to_raw(node: &DeclaredNode) -> anyhow::Result<RawSpec> {
                 );
                 raw.driver.opencode = Some(opencode_driver_node_to_raw(child)?);
             }
+            "omp" => {
+                anyhow::ensure!(
+                    raw.driver.omp.is_none(),
+                    "agent declares `omp` more than once"
+                );
+                raw.driver.omp = Some(omp_driver_node_to_raw(child)?);
+            }
             "env" => {}
             "pty" => {
                 if let Some(name) = arg_string(child) {
@@ -352,6 +360,16 @@ fn pi_driver_node_to_raw(node: &DeclaredNode) -> anyhow::Result<PiDriver> {
     })
 }
 
+fn omp_driver_node_to_raw(node: &DeclaredNode) -> anyhow::Result<OmpDriver> {
+    let (model, effort, _, prompt, args) = common_driver_fields(node, "omp", false)?;
+    Ok(OmpDriver {
+        model,
+        effort,
+        prompt,
+        args,
+    })
+}
+
 fn opencode_driver_node_to_raw(node: &DeclaredNode) -> anyhow::Result<OpenCodeDriver> {
     let (model, effort, _, prompt, args) = common_driver_fields(node, "opencode", false)?;
     anyhow::ensure!(

crates/agent-spec/src/spec.rs

@@ -79,6 +79,7 @@ pub enum Driver {
     Codex(CodexDriver),
     Pi(PiDriver),
     OpenCode(OpenCodeDriver),
+    Omp(OmpDriver),
 }
 
 impl Driver {
@@ -88,6 +89,7 @@ impl Driver {
             Self::Codex(_) => "codex",
             Self::Pi(_) => "pi",
             Self::OpenCode(_) => "opencode",
+            Self::Omp(_) => "omp",
         }
     }
 }
@@ -143,6 +145,20 @@ pub struct OpenCodeDriver {
     pub args: Vec<String>,
 }
 
+/// Typed fields accepted by an `omp {}` driver block.
+///
+/// omp is pi-family and exposes the same two axes under the same flags: `effort` carries omp's
+/// thinking level verbatim (`--thinking`), exactly as [`PiDriver`] does for pi.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+pub struct OmpDriver {
+    pub model: Option<String>,
+    pub effort: Option<String>,
+    pub prompt: String,
+    #[serde(default)]
+    pub args: Vec<String>,
+}
+
 impl AgentDesiredState {
     pub fn as_str(&self) -> &'static str {
         match self {
@@ -579,6 +595,7 @@ pub(crate) struct RawDriver {
     pub(crate) codex: Option<CodexDriver>,
     pub(crate) pi: Option<PiDriver>,
     pub(crate) opencode: Option<OpenCodeDriver>,
+    pub(crate) omp: Option<OmpDriver>,
 }
 
 impl RawDriver {
@@ -597,6 +614,9 @@ impl RawDriver {
         if let Some(driver) = self.opencode {
             declared.push(("opencode", Driver::OpenCode(driver)));
         }
+        if let Some(driver) = self.omp {
+            declared.push(("omp", Driver::Omp(driver)));
+        }
         match declared.len() {
             0 => Ok(None),
             1 => Ok(Some(declared.pop().expect("length was just checked").1)),
@@ -936,6 +956,7 @@ impl RawSpec {
             // still be a candidate, whichever provider the block names.
             || self.driver.pi.is_some()
             || self.driver.opencode.is_some()
+            || self.driver.omp.is_some()
             || !self.resource.0.is_empty()
             || !self.pty.is_empty()
             || !self.exec.is_empty()
@@ -1317,7 +1338,7 @@ mod tests {
     /// or path-derived discovery silently skips the seat.
     #[test]
     fn a_lone_driver_block_of_any_provider_is_a_spec_candidate() {
-        for provider in ["claude", "codex", "pi", "opencode"] {
+        for provider in ["claude", "codex", "pi", "opencode", "omp"] {
             let block = format!("[{provider}]\nprompt = \"Start the assigned work.\"");
             let raw: super::RawSpec = toml::from_str(&block).unwrap();
             assert!(raw.looks_like_spec(), "[{provider}] must look like a spec");

docs/vrs/.decisions/0007-omp-is-a-fifth-native-driver-with-its-own-channel-and-a-hard-version-gate.md

@@ -0,0 +1,68 @@
+# omp is a fifth native driver with its own channel and a hard version gate
+
+Status: accepted
+
+## Context
+
+st2 maintains four typed drivers (claude, codex, pi, opencode), each pairing a pure KDL
+expansion with a session wrapper that owns presence, publishes observed harness state, and
+delivers inbox messages natively. omp — an earendil-works/pi-family harness in daily use on
+this fleet — has none of this: seats are hand-authored tasks with no presence lease, no
+observed state, and no delivery path. The question was how deep support should go: a full
+native driver, an alias onto the pi driver's machinery, or a documented hand-authored
+pattern.
+
+## Options
+| Option | Result | Reason |
+| --- | --- | --- |
+| Full native driver (fifth expansion arm, own wrapper, own channel) | Selected | The 2026-08-25 capture shows the pi mechanism ports and omp's approval events add an axis pi lacks. Cost: ~pi-driver scale code and a per-minor admission checklist. |
+| Alias onto the pi driver | Rejected | Cheapest, but measured divergence makes it wrong: no `agent_settled` means the observed idle edge never fires or blips at `agent_end`, and version gates would pin the wrong harness. Rejected on evidence, not effort. |
+| Docs-only hand-authored pattern | Rejected | No presence lease, observed state, or native delivery; inconsistent with all four existing drivers — not "first-class". |
+| Blocked axis deferred out of v1 | Rejected | Smaller diff, but omp seats would read busy while actually waiting on a human — exactly what st2's wedged-agent signal exists to catch; both events verified firing (q2). |
+| Warn-only version handling | Rejected | omp releases near-daily; silent degradation reads as healthy while a refused launch is loud (q3). |
+
+## Evidence and Argument
+
+Measured against omp v18.0.3 on 2026-08-25; full record:
+[`06-omp-driver/.experiments/2026-08-25-omp-harness-integration.md`](../06-omp-driver/.experiments/2026-08-25-omp-harness-integration.md).
+
+- **The pi mechanism ports.** omp loads pi-style extensions; its extension argument carries
+  the same `sendUserMessage` / `sendMessage` / `on` calls; a live interactive run delivered
+  an idle message end-to-end and drove a complete model turn without touching a screen.
+- **But it is not pi.** `agent_settled` — the pi channel's entire idle edge — does not exist
+  (absent from the binary); idle must be derived by polling `ctx.isIdle()` after
+  `agent_end`. Conversely omp is *richer* than pi where it matters for st2: it exposes
+  `tool_approval_requested` / `tool_approval_resolved` with a `toolCallId`, giving the
+  blocked-on-human axis pi cannot express at all.
+
+An alias onto the pi driver would bake both divergences into the wrong place: observed state
+would hang waiting for an event that never fires or blip idle at the wrong boundary, and
+each future divergence would become a special case inside "pi". The measured differences
+are exactly why the channel forks rather than shares a file.
+
+## Decision
+
+1. **Full native driver** (`driver omp` block + `omp-session` wrapper + `omp-channel.ts`
+   extension + `omp-channel` process), per OMP-R01.
+2. **Own channel asset, forked from pi's**, not a shared parameterized file — the idle-edge
+   and approval logic differ per harness (OMP-R04).
+3. **Publish the blocked-on-human axis in v1** from the two approval events (OMP-R02) —
+   verified firing, not speculative.
+4. **Hard version gate on the minor** (18.x initially) under the codex/opencode admission
+   convention, because the delivery-critical surface is versioned behavior, not API contract
+   (OMP-R05). Chosen over warn-only despite omp's near-daily releases: a silently degraded
+   fleet reads as healthy; a refused launch reads as what it is.
+5. **No DING screen adapter for omp** in v1 (OMP-T03), matching the other native-channel
+   drivers.
+
+Interview decisions q1–q4 (2026-08-25, Johannes): full native driver; blocked axis included;
+hard gate; VRS lives in [`06-omp-driver/`](../06-omp-driver/).
+
+## Consequences
+
+- A fifth expansion arm, wrapper module, channel process, hook asset, and ding launch
+  classification follow the existing per-harness pattern.
+- Every omp minor bump costs one capture run before admission; the required checklist is in
+  the subsystem spec.
+- The deny path, ask-axis discrimination, steer/modal interactions, and update-banner
+  suppression remain open (`DQ-OMP-1..5`) and bound v1's claims.

docs/vrs/06-omp-driver/.experiments/2026-08-25-omp-harness-integration.md

@@ -0,0 +1,116 @@
+# omp harness integration surface
+
+## Question
+
+Does st2's pi-driver mechanism — an injected TypeScript extension speaking newline-delimited
+JSON frames over stdio to a channel process — port to omp, and what diverges? Sub-questions:
+which lifecycle events exist, when does omp become provably idle, does native delivery drive a
+real turn, and is there any waiting-on-human signal?
+
+Date: 2026-08-25. Binary: omp v18.0.3 (`omp` on dev3 PATH, Nix store
+`zv3xvic38a2gcdpxk3wd5fsk6plsgvbn-omp-18.0.3`). Linux x86_64, driven through live `omp`
+processes (print mode for API probes, a PTY-held interactive TUI for lifecycle and delivery
+runs).
+
+## Method
+
+
+Six throwaway TypeScript extensions, each loaded via `omp -e ./probeN.ts`, writing observations
+to files beside them. Print-mode runs used `--no-session --no-tools --no-lsp --no-skills
+--no-rules`. Interactive runs held the TUI in a supervised PTY session and drove prompts by
+typing into the pane; one run forced approvals with `--approval-mode always-ask`.
+
+## Result
+
+**omp is pi-family.** omp reads pi's env fallbacks (`PI_SMOL_MODEL` documented in `--help`),
+loads pi-style default-export TypeScript extensions unchanged at the module boundary, and its
+extension first argument carries the same three calls st2's pi channel uses:
+`sendUserMessage(content, options?)`, `sendMessage(message, options?)`, `on(event, handler)`.
+The argument additionally carries an internals namespace under `.pi`; irrelevant to st2.
+
+**Lifecycle events use pi's names, minus `agent_settled`.** Observed firing in one interactive
+turn: `session_start`, `agent_start`, `turn_start`, `message_start`, `message_end`,
+`turn_end`, `agent_end`, `session_shutdown`. `agent_settled` never fired and the string does
+not occur anywhere in the binary (1M-string scan). Handler registration for unknown names does
+not throw, so absence is silent.
+
+**The idle edge exists but is sampled, not evented.** In the interactive run,
+`ctx.isIdle()` was still `false` at `agent_end` and flipped `true` by the +251 ms sample. Rule:
+idle is `agent_end` followed by bounded polling until `isIdle()` is true; a queued follow-up
+turn keeps it false, so no spurious idle blip.
+
+**Idle delivery lands and drives a full turn.** Interactive run with tools enabled: extension
+polled a trigger file every 200 ms, called `pi.sendUserMessage(body)` while idle; the model
+received it, acted (wrote the requested file correctly), turn events fired, and the session
+settled back to idle. End-to-end native delivery confirmed without touching any screen.
+
+**Mid-turn steer accepted in print mode.** From inside `message_start`, `sendUserMessage(text,
+{ deliverAs: "steer" })` returned without error. Not yet visually verified in the interactive
+TUI (DQ-OMP-4).
+
+**Approval events exist and fire — omp is richer than pi here.** Under
+`--approval-mode always-ask`, a bash call produced:
+
+```
+tool_approval_requested { type, sessionId, toolName: "bash", toolCallId, approvalMode }
+tool_approval_resolved  { ..., approved: true }
+```
+
+The requested event carries a correlating `toolCallId`, giving the blocked exit edge pi lacks
+entirely. Without forced approval mode the events did not fire (the same command auto-ran).
+
+**Context object differences.** Event-handler `ctx` exposes `{ ui }` only — no abort `signal`
+(pi's channel uses `ctx.signal?.addEventListener` optionally, so the fork loses nothing).
+`ctx.ui.notify` is present.
+
+**Unresolved by this capture:** the update-check banner appeared in every interactive boot;
+whether `PI_OFFLINE`/`PI_SKIP_VERSION_CHECK` suppress it was not established in print mode
+(the banner never renders there) — DQ-OMP-5.
+
+## Conclusion
+
+The pi-driver mechanism ports to omp with one structural divergence: the idle edge must be
+derived by polling `ctx.isIdle()` after `agent_end` instead of listening for `agent_settled`.
+A native omp driver is viable at full parity — presence lease, observed state including the
+blocked-on-human axis pi cannot express, and native delivery. The measured divergences
+justify forking the channel asset rather than parameterizing pi's.
+
+## VRS Impact
+
+Grounds OMP-R02 (observed axes, from the approval-event payloads and idle sampling),
+OMP-R03 (idle edge rule), OMP-R04 (fork rationale), OMP-T01/T02 (deny path and ask axis
+unmeasured), and DQ-OMP-3..5 (steer visual, modal interaction, banner suppression).
+
+## Driver e2e run
+
+The same day, the implemented driver ran end-to-end on dev3: a scratch catalog declared
+`agent "omp-smoke"` with a `driver omp` block; `st2 hooks install` published the set including
+`omp-channel.ts`; `st2 driver omp-session` launched the TUI under the wrapper. Verified: the
+presence record read `available`; the harness-state record seeded `idle` under
+`harness: "omp"`, fenced by the wrapper's session token (`seq 1`, pty session bound); a
+`st2 message send` landed in the live TUI via the channel together with the
+`st2-session-start` restored-context block; observed state cycled active → idle
+(transitions 3→5) around the delivery. The model's reply itself failed with a provider-side
+429 weekly usage limit — outside st2's surface.
+
+## Fleet e2e run (dotfiles integration)
+
+The dotfiles side activated the driver on dev3 through the standing
+`dev3.omp-scratch` seat (launched by the production supervisor via
+`st2 driver omp-session`, st2 repinned to this branch). Verified live: the
+seat materialized into the catalog, reached presence `available`, published
+the harness-state record (`harness: "omp"`, seeded idle, fenced by the
+wrapper's session token), and a `st2 message send` from `dev3.cos` landed in
+its live TUI through the channel with observed state cycling active → idle
+(transitions around the delivery). The model's reply was blocked by a
+provider-side 429 weekly usage limit on the opencode-go workspace - the same
+external quota exhaustion visible across the fleet that day; the
+model-acts-on-delivery step is covered by the manual runs above.
+
+Integration findings recorded on the way: Nix standing seats launch through
+the `axe agent launch` carrier, which spawns the raw harness binary - so a
+driver-backed seat that wants the wrapper's machinery must declare the
+`st2 driver <h>-session` argv directly rather than ride the axe carrier; and
+axe's managed path requires a profile account binding plus a fixed-account
+credential availability probe, which omp satisfies with its install-identity
+file since its native OAuth exposes no projectable credential.

docs/vrs/06-omp-driver/open-questions.md

@@ -0,0 +1,24 @@
+# omp driver open questions
+
+Each entry links a spec `DQ-OMP-*`. Questions leave this file when resolved — into
+[spec.md](./spec.md) as decisions or `.experiments/` as tested hypotheses.
+
+- **DQ-OMP-1 Deny-path semantics.** What omp does after
+  `tool_approval_resolved { approved: false }` — whether the turn ends (Claude's deny path:
+  turn ends eventlessly) or the model continues with a denial result. Until captured,
+  OMP-T01 accepts a possibly brief misprojection of activity after a denial.
+- **DQ-OMP-2 Ask-axis discrimination.** Whether an AskUserQuestion-equivalent surface in omp
+  arrives as `tool_approval_requested` with a distinguishable `toolName`, so v1's coarse
+  `ask: permission` can be split into question vs permission like the Claude driver does.
+  Needs one capture of each prompt kind under forced approval mode.
+- **DQ-OMP-3 Mid-turn steer in the live TUI.** `deliverAs: "steer"` was accepted without
+  error in print mode; the interactive visual (message lands as a queued steer, not a lost
+  send) is unconfirmed. Resolves by repeating the delivery experiment with the trigger fired
+  during an active turn and reading the resulting transcript.
+- **DQ-OMP-4 Modal interaction.** pi's capture showed an open `/model` modal does not corrupt
+  idle delivery; omp's equivalent has not been tested. Same method: open a picker, deliver
+  while idle-true, verify the modal survives.
+- **DQ-OMP-5 Update-banner suppression.** Interactive boots showed the update banner;
+  whether `PI_OFFLINE` / `PI_SKIP_VERSION_CHECK` suppress it was not establishable in print
+  mode. Resolves by one interactive boot with the env set. The wrapper ships the env either
+  way (harmless if inert).