@naxodev/apnea 0.1.0

package/docs/adr/0001-completion-signaling.md

@@ -0,0 +1,3 @@
+# Completion signaling: artifact front-matter only
+
+A sequential loop has at most one outstanding dispatch. Multiple completion channels (result JSON, pane markers, agent-status parsing) create competing parsers and fail open on the weakest one. We use a single machine channel: the role writes one artifact with YAML front-matter (`status`, optional `verdict`/`nits`). Markers are human-only; Herdr agent-status is liveness only. Absence of the target path (clear-before-dispatch / per-round paths) replaces dispatch-id correlation.

package/docs/adr/0002-orchestrator-authority.md

@@ -0,0 +1,3 @@
+# Orchestrator authority: tools are the state machine
+
+The loop is deterministic; the default orchestrator model is not. Every mutating tool validates `state.json.step` and refuses illegal transitions with a corrective error. `workflow_status` is read-only. Cap reset is not a model-facing tool at all: `reset-rounds` exists only on the CLI and as `/apnea reset-rounds`, and the CLI refuses it unless stdin/stdout are a terminal and the human retypes the gate key. `--i-am-human` overrides for scripts — the guarantee is auditability, not prevention. Hand-editing `state.json` voids the warranty.

package/docs/adr/0003-verify-at-gate.md

@@ -0,0 +1,3 @@
+# Verify commands run at commit, not by trust
+
+Phase packages include verify commands, but a readonly-in-spirit reviewer cannot be the hard gate. `workflow_commit_phase` executes those commands, writes `artifacts/phase-N/round-M/verify.log`, and refuses on non-zero exit in addition to requiring APPROVED. Planner-authored commands are arbitrary code in the project cwd — accepted as the same trust domain as the coder writing sources. Plan review must sanity-read verify commands before approving a plan. No sandbox in v1.

package/docs/adr/0004-artifact-layout-and-naming.md

@@ -0,0 +1,3 @@
+# `.apnea/` layout and per-round paths
+
+Runtime state lives under `.apnea/` (package name, not “pi-herdr”) and is VCS-ignored. Artifacts use `phase-N/round-M/` paths so rework never overwrites audit history. Glossary terms (Run, Phase, Phase package, Dispatch, Round, Verdict, Brief, Artifact, Gate, Profile, Role) are mandatory in briefs and tool errors so foreign harnesses pattern-match one vocabulary.

package/docs/adr/0005-harness-profiles.md

@@ -0,0 +1,5 @@
+# Harness abstraction: profiles with mode variants
+
+Roles do not carry freeform model strings. Global **profiles** define `cmd_interactive` (required for dispatch) and optional `cmd_oneshot` (unused by regular Apnea dispatch). Every worker role opens the interactive harness TUI in a labeled Herdr pane so humans can watch the session. Binding a role to a profile missing `cmd_interactive` hard-errors at start. Project config may only rebind role→profile names.
+
+Each remembered role pane stores a deterministic fingerprint of the effective profile name and interactive command. Dispatch reuses the pane only when that fingerprint still matches resolved config. Legacy pane records have no fingerprint and are recreated once rather than risking an old harness.

package/docs/adr/0006-config-trust-model.md

@@ -0,0 +1,3 @@
+# Config trust: binaries only in global config
+
+Project-local argv is RCE on `workflow_start`. Profiles and all `cmd_*` arrays resolve only from `~/.config/apnea/config.json` (plus package defaults). `.apnea/config.json` may rebind roles to existing profile names and set caps/timeouts. Unknown keys and unimplemented values hard-error. Repo text (tasks, plans, verify commands) remains an accepted prompt-injection surface and is disclosed, not denied.

package/docs/adr/0007-jj-first-commits.md

@@ -0,0 +1,3 @@
+# jj-first commit semantics
+
+If `.jj/` exists, use jj only for mutations (`describe` + `new` after each approved phase). Never run mutating git commands in a jj repo. Git backend: branch `apnea/<slug>` at start, one commit per phase. jj bookmark `apnea/<slug>` is created at **terminus** (when writing/finishing PR description), not at start — bookmarks do not follow `@`. “Clean tree” for start means empty meaningful file diff (jj: empty `@` changes the user cares about; not “op log quiet”). Neither VCS → refuse auto-commit. Coder commits are a protocol violation and must escalate.

package/docs/adr/0008-effect-v4-internals.md

@@ -0,0 +1,3 @@
+# Effect v4 for extension internals
+
+Apnea’s Pi extension mixed `ToolResult` returns with thrown errors, hand-rolled JSON validation, and hard-to-test `fs`/herdr/vcs side effects inside tool functions. We adopt **Effect v4** (pinned beta) for workflow programs and IO services only: pure domain (state machine, paths, front-matter line parse, round keys) stays plain TypeScript; Pi tool params stay TypeBox; adapters map Effect exits to `ToolResult`. Services are custom and thin (FileSystem, RunStore, Config, Vcs, Herdr, Clock) — not `@effect/platform-node`. Each tool call runs with a fresh `AppLive` provide (no process-global runtime). Config/state decode via Effect Schema as runtime source of truth; repo `schemas/*.json` remain human protocol docs, kept honest with fixture tests. Protocol, artifact layout, and config trust are unchanged (ADRs 0001–0007).

package/docs/adr/0009-cli-driver-split.md

@@ -0,0 +1,9 @@
+# CLI driver: one registry, two front-ends
+
+The loop's enforcement lives in `workflows/` + `domain/state-machine.ts`, not in Pi.
+`extension/registry.ts` is the single definition of every operation; `@naxodev/pi-apnea`
+binds it to Pi tools and `extension/cli/` binds it to argv, so the two front-ends cannot
+desync. Any harness that can run a shell command can hold the orchestrator seat. Pi keeps
+its exclusives — streaming `onUpdate` during wait, `sendUserMessage` kick, `/` autocomplete.
+`workflow_wait` is bounded and resumable because host shell timeouts are shorter than role
+timeouts; the authoritative deadline lives in `state.json`, not in process memory.

package/docs/adr/0010-package-split.md

@@ -0,0 +1,23 @@
+# ADR 0010: Split the engine and Pi adapter
+
+## Status
+
+Accepted.
+
+## Context
+
+The original package combined a standalone CLI, workflow engine, protocol resources, and Pi integration. This made the host-neutral CLI depend on Pi-specific launch behavior and prevented consumers from installing the engine alone.
+
+## Decision
+
+Publish the workflow engine and CLI as `@naxodev/apnea`. Publish Pi registration, Pi resources, and Pi-specific role launch behavior as `@naxodev/pi-apnea`.
+
+Both adapters bind the operation registry exported by `@naxodev/apnea`. The Pi adapter calls registry operations in process. It does not invoke the CLI as a subprocess.
+
+The core exposes only the operation registry, result formatting, command parsing, resource-root lookup, and the `ApneaHostAdapter` launch hooks. Pi supplies those hooks when it creates its registry.
+
+`@naxodev/pi-apnea` depends on `@naxodev/apnea` with `^0.1.0`. Compatible core patch releases flow through that range. An incompatible host interface change requires coordinated minor releases of both packages.
+
+## Consequences
+
+The CLI package installs and runs without Pi. Installing the Pi adapter installs the core transitively and registers Pi extensions, skills, and prompts. Protocol documentation, schemas, briefs, and Herdr resources have one owner in the core package.

package/docs/protocol/artifacts.md

@@ -0,0 +1,68 @@
+# Artifacts
+
+## Layout
+
+```text
+.apnea/                          # runtime; ignore in VCS
+  config.json                    # optional project role→profile bindings only
+  state.json                     # step, phase index, rounds per (phase, gate), slug
+  tasks/
+    <dispatch-id>.md             # human/agent-readable task payload
+  artifacts/
+    plan.md                      # or plan-round-N.md on plan rework
+    plan-review/
+      round-1.md
+    phase-01/
+      round-1/
+        phase-package.md
+        coder-result.md
+        code-review.md
+        verify.log               # written by workflow_commit_phase
+    phase-02/
+      ...
+    pr-description.md
+```
+
+Package-owned briefs live in the installed package (`briefs/`), not under `.apnea/`.
+
+## Front-matter schema
+
+Required on every role-produced artifact:
+
+| Field    | Values                  |
+| -------- | ----------------------- |
+| `status` | `done` (v1; no partial) |
+
+Review artifacts also require:
+
+| Field     | Values                           |
+| --------- | -------------------------------- |
+| `verdict` | `APPROVED` \| `CHANGES_REQUIRED` |
+
+Code-review artifacts with `CHANGES_REQUIRED` may also declare:
+
+| Field    | Values                    |
+| -------- | ------------------------- |
+| `rework` | `code` \| `phase_package` |
+
+Missing `rework` means `code`, preserving existing review artifacts. `phase_package` returns the run to phase packaging. The revised package is written under the next `round-N` directory, so the rejected package and review remain available.
+
+Optional:
+
+| Field  | Values                                           |
+| ------ | ------------------------------------------------ |
+| `nits` | freeform markdown string; ignored by commit gate |
+
+Non-review artifacts (plan, phase package, coder result, pr-description): `status: done` only; no `verdict`.
+
+## Clear-before-dispatch
+
+For a given target path, `dispatch_role` deletes or renames away any existing file at that path before sending the pointer so absence means “not done.”
+
+On rework after CHANGES_REQUIRED, the **round number increases** and the path changes (`round-2/...`), so history is preserved.
+
+On crash re-dispatch (same round), the same path is cleared and reused.
+
+## Human markers (optional)
+
+Roles may print `PLAN_READY`, `VERDICT: APPROVED`, etc. for humans. Tools must not depend on them.

package/docs/protocol/config.md

@@ -0,0 +1,186 @@
+# Config
+
+## Layers (merge order)
+
+1. Package defaults
+2. `~/.config/apnea/config.json` — **only place profiles/`cmd` may appear**
+3. `.apnea/config.json` — role → profile bindings, caps, timeouts, slug defaults
+4. Per-run `workflow_start` args — slug, allow-dirty, temporary role rebinds
+
+Unknown keys and unimplemented values (`isolation: "worktree"`) **hard-error** at start.
+
+## Global profiles
+
+```jsonc
+// ~/.config/apnea/config.json
+{
+  "profiles": {
+    "pi-grok": {
+      "cmd_interactive": [
+        "pi",
+        "--provider",
+        "grok-cli",
+        "--model",
+        "grok-4.5",
+      ],
+      "cmd_oneshot": [
+        "pi",
+        "--print",
+        "--provider",
+        "grok-cli",
+        "--model",
+        "grok-4.5",
+      ],
+    },
+    "claude-fable": {
+      // oneshot needs Write (or equivalent) so the role can emit artifacts
+      "cmd_oneshot": [
+        "claude",
+        "-p",
+        "--model",
+        "claude-fable-5",
+        "--allowedTools",
+        "Read,Write,Edit,Glob,Grep",
+      ],
+      "cmd_interactive": ["claude", "--model", "claude-fable-5"],
+    },
+  },
+  "roles": {
+    "orchestrator": { "profile": "pi-grok" },
+    "planner": { "profile": "claude-fable" },
+    "reviewer": { "profile": "claude-fable" },
+    "coder": { "profile": "pi-grok" },
+  },
+  "review_round_cap": 3,
+  // "regular" (default) or "floating"; omit the key to keep the default
+  "pane_style": "regular",
+  "timeouts_ms": {
+    "planning": 1500000,
+    "plan_review": 900000,
+    "phase_packaging": 900000,
+    "coding": 2700000,
+    "code_review": 900000,
+    "verify": 900000,
+  },
+}
+```
+
+## Role timeout vs. `--timeout`
+
+`timeouts_ms` above sets each role's real deadline. `dispatch_role` (`apnea dispatch`) reads it
+and stamps the deadline into `state.json` at dispatch time, so it survives across process
+restarts and repeated `wait` calls.
+
+`apnea wait --timeout=<ms>` and `/apnea wait --timeout=<ms>` are a different knob: `--timeout`
+is an alias for `--budget`, and both bound how long **that one call** blocks before returning —
+not the role's deadline. When the call's budget runs out before the role's deadline, it exits
+`3` ("still waiting") and the caller must call `wait` again; this does not extend or shorten the
+role's timeout.
+
+The **CLI's** default budget is 90000ms. Agent shell tools commonly default to a 120000ms
+timeout, and a budget above that is killed before it can return the exit `3` the resume protocol
+depends on — the caller sees a killed command instead of an instruction to call again.
+
+The `workflow_wait` **Pi tool** has no default budget: it blocks until the role finishes. Pi
+streams progress and can interrupt the call, so there is no host shell timeout to fit inside,
+and chunking it would only add tool round trips. Everything below about budgets and the poll
+ceiling therefore describes the CLI, or a Pi call that passes `budget_ms` explicitly.
+
+The floor is `12000 + max(60000, 4 x poll_ms)` — 72000ms at the default 2000ms poll. A call
+shorter than that is refused.
+
+The floor exists because two rungs measure a duration by polling: the idle nudge needs 60000ms
+of unbroken idleness, and the dead-harness check needs four consecutive shell-only polls. Both
+start after a 12000ms grace. A duration is only meaningful over an interval something actually
+watched, and nothing watches the role between `wait` calls, so each of those rungs has to
+complete inside a single call.
+
+An earlier version tried to carry those counters across calls in `state.json`. That cannot be
+made correct. The counter has to assume something about the gap it did not observe: assume
+"still idle" and a role that was working gets nudged; assume "not idle" and the evidence is
+discarded so the rung never fires. Both failures were reproduced.
+
+Facts do survive a gap, and stay in `state.json`: the role deadline, whether the one-time
+extension was consumed, whether the final grace was taken, and whether a nudge was sent.
+
+Raising `--poll` therefore raises the floor. When you do not pass `--budget`, the budget is
+raised to the floor for you, so `apnea wait --poll=20000` works — the call simply runs longer
+than the 90000ms default.
+
+That auto-raise stops above `--poll=26999`, the largest poll whose budget stays strictly under
+the 120000ms an agent shell commonly allows. The bound is strict because a call that runs
+exactly 120000ms is killed at the instant it would have returned exit `3`. Above it there is no
+budget that both clears the floor and returns in time, so `wait` refuses rather than picking one
+that gets killed. Passing `--budget` explicitly still works at any poll: it is a deliberate
+statement that your shell allows a longer call. An explicit budget under the floor is still
+refused.
+
+`poll_ms` must be at least 250ms. Every poll spawns two herdr subprocesses, so a smaller
+interval is a busy-spin rather than a faster wait. `budget_ms` must be finite. The sleep between
+polls is clamped to the remaining budget, so a large `poll_ms` cannot make a call outlive it.
+
+The idle nudge and the final grace are independent rungs. A role nudged early for going idle
+still receives its 180000ms grace at the deadline; it just is not prompted twice.
+
+The 60000ms idle threshold is a trade, not a tuned value. It is short enough that the rung fits
+a 90000ms call, and short enough to sometimes prompt a role that is working — a coder blocked on
+a slow test run can read `idle` for a minute. The nudge is one-shot, so a false one is spent. A
+90000ms threshold would raise the floor to 102000ms and force the default budget to about
+105000ms, leaving roughly 15000ms of margin under a 120000ms shell. Raise one and you must raise
+the other.
+
+## Pane style
+
+`pane_style` controls how role dispatches appear in Herdr:
+
+- Values: `"regular"` | `"floating"`. Default is `"regular"` — **omitting the key changes nothing**.
+- Allowed in global config and overridable per project.
+- `"floating"` applies to **planner/reviewer oneshot dispatches only**. It requires herdr ≥ 0.7.4 **and** the linked `apnea` plugin (provisioned by `/apnea setup`). The popup is **session-modal**: it takes keyboard input until the worker exits, and dismissing it early kills the dispatch.
+- Floating oneshot scripts resolve `cmd_oneshot[0]` to an **absolute path** in the orchestrator environment and pass an augmented `PATH` into the popup. Bare names must be findable via the orchestrator's `PATH` (e.g. `~/.local/bin`); otherwise dispatch fails immediately instead of the popup exiting 127. Prefer absolute `cmd_oneshot` if your orchestrator process has a stripped PATH.
+- **Lifecycle (single popup):** herdr allows only one popup. Dispatch refuses while a prior floating oneshot is still live. The worker writes an exit-status file; `workflow_wait` fails closed when the popup dies without a complete artifact (instead of hanging until timeout). A second open while a popup is up surfaces `popup already open` immediately.
+- Interactive roles (orchestrator, coder) always use regular panes; the dispatch result reports `pane_style_effective: "regular (interactive role)"`.
+- Misconfiguration (old herdr, missing plugin, missing `cmd_oneshot`, unresolved oneshot binary) fails fast at dispatch with an actionable error.
+- Non-goal: per-role `pane_style` is future work. Setup never writes or flips this key — it only preserves a valid existing value on re-run.
+
+## Role modes (fixed)
+
+By default every worker role launches the **interactive** harness TUI so you can watch it in Herdr. With `pane_style: "floating"`, planner and reviewer instead run their profile's **`cmd_oneshot`** inside the popup (those profiles therefore need `cmd_oneshot` for floating — dispatch preflight errors otherwise). Interactive roles always stay on `cmd_interactive`.
+
+| Role         | Required profile capability                                         |
+| ------------ | ------------------------------------------------------------------- |
+| orchestrator | `cmd_interactive`                                                   |
+| planner      | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
+| reviewer     | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
+| coder        | `cmd_interactive`                                                   |
+
+Binding a role to a profile missing the required capability → **hard-error**.
+
+## Project config (no binaries)
+
+```jsonc
+// .apnea/config.json
+{
+  "roles": {
+    "coder": { "profile": "pi-grok" },
+  },
+  "review_round_cap": 3,
+}
+```
+
+Project entries that include `cmd`, `cmd_oneshot`, `cmd_interactive`, or `bin` → **hard-error**.
+
+## Trust model
+
+- Repo-controlled **text** (tasks, plans, verify commands, briefs if vendored) is an accepted prompt-injection surface — disclosed, not “solved.”
+- Repo-controlled **argv** is not allowed.
+- Planner-authored verify commands run at commit gate in the project cwd (same trust domain as the coder writing source). Output → `verify.log`.
+
+## Setup skill
+
+`apnea-setup` / `/apnea-init`:
+
+- Detect available binaries (`pi`, `claude`, `codex`, `herdr`, `jj`, `git`)
+- Write a safe global starter config
+- Optionally write project role bindings
+- Never write `cmd` into project config
+- Point at the manual gate before claiming readiness

package/docs/protocol/manual-gate.md

@@ -0,0 +1,38 @@
+# Manual gate (before any extension code)
+
+## Goal
+
+Prove the paper protocol works with mixed harnesses and file handoffs **without** Apnea tools. Human acts as orchestrator.
+
+## Setup
+
+- Herdr session in a throwaway toy repo (jj or git)
+- Global profiles already defined (hand-written or future `/apnea-init`)
+- Briefs from this package mounted or copied read-only for agents to read
+- Layout under `.apnea/` created by hand as needed
+
+## Toy feature
+
+Two phases, e.g. “CLI that greets by name + `--json` flag,” small enough to finish in one sitting.
+
+## Required paths (must all pass)
+
+| #   | Path                  | Pass criteria                                                                                                                     |
+| --- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Happy path            | Two phases committed/described; `pr-description.md` exists                                                                        |
+| 2   | Plan CHANGES_REQUIRED | At least one plan rework; new plan-review round artifact; **no** manual verdict transcription                                     |
+| 3   | Code CHANGES_REQUIRED | Live follow-up into existing coder pane; new `round-N` code-review; then APPROVED                                                 |
+| 4   | APPROVED + nits       | One review with `nits` field; commit still proceeds                                                                               |
+| 5   | Kill-and-resume       | Kill coder pane mid-phase; human reconciles per protocol (artifact present? ingest : re-dispatch same round); continue to success |
+| 6   | Mixed harness         | Planner/reviewer Claude oneshot; coder Pi interactive                                                                             |
+
+## Hard rules during the gate
+
+- Every verdict read from artifact front-matter only
+- No tool code, no “helper scripts” that parse markers as truth
+- Verify commands run by the human-orchestrator before each phase “commit” (simulating `workflow_commit_phase`)
+- Reviewer must not leave a dirty file-content tree; if they do, treat as escalate
+
+## Exit
+
+When the table passes, record a short note in `examples/toy/GATE-RESULTS.md` and only then implement extension tools.

package/docs/protocol/overview.md

@@ -0,0 +1,96 @@
+# Protocol overview
+
+## Roles
+
+| Role             | Mode                         | Default job                                |
+| ---------------- | ---------------------------- | ------------------------------------------ |
+| **orchestrator** | interactive (Pi; tools only) | Drive the loop; no product code            |
+| **planner**      | interactive TUI              | Plan, phase packages, final PR description |
+| **reviewer**     | interactive TUI              | Plan review + code review                  |
+| **coder**        | interactive TUI              | Implement current phase package only       |
+
+All worker roles open a **live harness TUI** in a Herdr pane (Claude / Pi / Codex / …). Dispatch never uses oneshot (`-p` / print) — that dumps shell output and is not watchable. Profiles must provide `cmd_interactive` for every role.
+
+## State machine (`state.json.step`)
+
+```text
+start
+  → planning
+  → plan_review
+  → phase_packaging
+  → coding
+  → code_review
+  → committing
+  → (phase_packaging | finishing)
+  → finishing          # planner writes pr-description
+  → done
+```
+
+Illegal tool calls refuse with the legal next call named in the error.
+
+## Tools
+
+| Tool                    | Purpose                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `workflow_start`        | Resolve config; clean-tree check (unless allow-dirty / resume); create git branch or prepare jj; label panes; write state |
+| `dispatch_role`         | Write task file; open live harness TUI in pane; wait idle; submit short pointer; rework-only round increment              |
+| `workflow_wait`         | Wait for artifact front-matter; treat agent-status as liveness only                                                       |
+| `workflow_commit_phase` | Require APPROVED + verify commands (log to `verify.log`) + VCS backend; advance phase                                     |
+| `workflow_status`       | **Read-only** snapshot                                                                                                    |
+
+Cap reset (`reset-rounds`) is not a Pi tool at all — it exists only as `apnea reset-rounds`
+(CLI) and `/apnea reset-rounds` (slash command), both human-only. See [ADR 0002](../adr/0002-orchestrator-authority.md).
+
+## Dispatch pointer (all harnesses)
+
+Short message only, e.g.:
+
+```text
+You are the reviewer.
+Read brief: <package>/briefs/reviewer.md
+Read task: .apnea/tasks/<id>.md
+Write artifact exactly at: .apnea/artifacts/phase-03/round-2/code-review.md
+Follow the brief. Do not invent paths.
+```
+
+## Completion
+
+Machine channel: **artifact front-matter only**.
+
+```yaml
+---
+status: done
+verdict: APPROVED # or CHANGES_REQUIRED; omit for non-review artifacts
+rework: code # optional on code-review CHANGES_REQUIRED; code or phase_package
+nits: | # optional; never blocks alone
+  Consider renaming foo later.
+---
+```
+
+Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane / hung oneshot without artifact → escalate).
+
+## Rework
+
+- **All roles:** live follow-up on the same pane when the harness is still idle; if pane missing or busy → new pane + cold TUI launch, then pointer.
+- Pointer always includes prior artifact paths for context.
+- Round increments **only** after CHANGES_REQUIRED on the same (phase, gate).
+- Crash / timeout / resume: **same round number**, clear-before-dispatch on that path.
+
+## Resume
+
+1. Re-resolve panes by role label (respawn if needed).
+2. If expected artifact has valid front-matter → ingest and advance.
+3. Else report state; **offer** re-dispatch — never auto-dispatch.
+4. Skip clean-tree check on resume.
+
+## Commit
+
+- Orchestrator only.
+- `workflow_commit_phase` runs phase package verify commands; non-zero → refuse.
+- jj: `jj describe` + `jj new` after APPROVED; **bookmark `apnea/<slug>` at terminus**, not start.
+- git: branch `apnea/<slug>` at start; one commit per phase.
+- No push / remote PR in v1. Terminus artifact: `pr-description.md` (planner).
+
+## Concurrency
+
+One run per repo. Existing `state.json` → resume or abandon only.

package/extension/adapters/commit.ts

@@ -0,0 +1,15 @@
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { makeAppLive } from "../services/app-live.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import { commitWorkflow, type CommitParams } from "../workflows/commit.ts"
+
+export async function workflowCommitPhase(
+  params: CommitParams,
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  return runToolResult(
+    commitWorkflow(params, process.cwd()),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/adapters/dispatch.ts

@@ -0,0 +1,15 @@
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { makeAppLive } from "../services/app-live.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import { dispatchWorkflow, type DispatchParams } from "../workflows/dispatch.ts"
+
+export async function workflowDispatch(
+  params: DispatchParams,
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  return runToolResult(
+    dispatchWorkflow(params, process.cwd()),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/adapters/setup.ts

@@ -0,0 +1,34 @@
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { makeAppLive } from "../services/app-live.ts"
+import { resolveExecutable } from "../services/herdr.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import {
+  setupWorkflow,
+  type SetupDeps,
+  type SetupParams,
+} from "../workflows/setup.ts"
+
+/**
+ * Walk PATH directly rather than spawning `which` once per binary — `which`
+ * itself is absent from minimal environments, which would report every
+ * harness as missing.
+ */
+function onPath(bin: string): boolean {
+  return resolveExecutable(bin) !== null
+}
+
+export async function apneaSetup(
+  params: SetupParams,
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  const prodDeps: SetupDeps = {
+    onPath,
+    materializeRoleAgentDir: () =>
+      hostAdapter.materializeRoleAgentDir?.() ?? null,
+  }
+  return runToolResult(
+    setupWorkflow(params, process.cwd(), prodDeps),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/adapters/start.ts

@@ -0,0 +1,16 @@
+import { makeAppLive } from "../services/app-live.ts"
+import type { ApneaHostAdapter } from "../host-adapter.ts"
+import { neutralHostAdapter } from "../host-adapter.ts"
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { startWorkflow, type StartParams } from "../workflows/start.ts"
+
+export async function workflowStart(
+  params: StartParams,
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  return runToolResult(
+    startWorkflow(params, process.cwd()),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/adapters/status.ts

@@ -0,0 +1,24 @@
+import { makeAppLive } from "../services/app-live.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { resetRoundsWorkflow } from "../workflows/reset.ts"
+import { statusWorkflow } from "../workflows/status.ts"
+
+export async function workflowStatus(
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  return runToolResult(statusWorkflow(process.cwd()), makeAppLive(hostAdapter))
+}
+
+export async function workflowResetRounds(
+  params: {
+    gate: string
+  },
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): Promise<ToolResult> {
+  return runToolResult(
+    resetRoundsWorkflow(params, process.cwd()),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/adapters/wait.ts

@@ -0,0 +1,20 @@
+import type { ToolResult } from "../result.ts"
+import { runToolResult } from "../run-tool.ts"
+import { makeAppLive } from "../services/app-live.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import {
+  waitWorkflow,
+  type WaitHooks,
+  type WaitParams,
+} from "../workflows/wait.ts"
+
+export async function workflowWait(
+  params: WaitParams,
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+  hooks: WaitHooks = {},
+): Promise<ToolResult> {
+  return runToolResult(
+    waitWorkflow(params, process.cwd(), hooks),
+    makeAppLive(hostAdapter),
+  )
+}

package/extension/api.ts

@@ -0,0 +1,16 @@
+export {
+  createOperations,
+  createExecutor,
+  executeOperation,
+  findByTool,
+  findByVerb,
+  OPERATIONS,
+  toolToVerb,
+  type Operation,
+  type ExecuteOperation,
+} from "./registry.ts"
+export { parseFlags, parseNumFlag } from "./cli/parse.ts"
+export { DISPATCH_KINDS, type DispatchKind } from "./domain/state-machine.ts"
+export { packageRoot } from "./domain/paths.ts"
+export { formatResult, toolContent, type ToolResult } from "./result.ts"
+export type { ApneaHostAdapter } from "./host-adapter.ts"