@naxodev/apnea 0.1.0

package/extension/domain/recovery.ts

@@ -0,0 +1,25 @@
+import type { RunState } from "./types.ts"
+
+/**
+ * Clear the recovery ladder's per-dispatch state.
+ *
+ * These fields are facts about ONE in-flight dispatch: whether it was nudged,
+ * whether it consumed its one-time extension, whether it took the final grace.
+ * A new dispatch must start from none of them, and an ingested artifact must
+ * leave none behind.
+ *
+ * A shared helper because the block was previously copy-pasted at four sites
+ * (`start`, both `dispatch` save paths, and `wait`'s advance). Adding a rung
+ * meant editing four places, and missing one leaves a stale flag that makes
+ * the new rung fire immediately against a freshly dispatched role — the exact
+ * failure class that made this file's history what it is.
+ *
+ * `pending_started_at` and `pending_deadline_ms` are deliberately NOT reset
+ * here: dispatch sets them to real values in the same breath, and clearing
+ * them first would let a caller observe a pending role with no deadline.
+ */
+export function resetRecoveryLadder(state: RunState): void {
+  state.pending_nudged_at = null
+  state.pending_final_grace = false
+  state.pending_extended = false
+}

package/extension/domain/rounds.ts

@@ -0,0 +1,16 @@
+import type { RunState } from "./types.ts"
+
+export function roundKey(phaseIndex: number, gate: string): string {
+  if (gate === "plan_review") return "plan_review"
+  if (gate === "finishing") return "finishing"
+  const n = String(phaseIndex).padStart(2, "0")
+  return `phase-${n}/${gate}`
+}
+
+export function getRound(state: RunState, key: string): number {
+  return state.rounds[key] ?? 1
+}
+
+export function setRound(state: RunState, key: string, n: number): void {
+  state.rounds[key] = n
+}

package/extension/domain/setup.ts

@@ -0,0 +1,158 @@
+import { DEFAULT_TIMEOUTS } from "./types.ts"
+
+export type Detected = {
+  pi: boolean
+  claude: boolean
+  codex: boolean
+  herdr: boolean
+  jj: boolean
+  git: boolean
+}
+
+/** Existing keys win over incoming (never overwrite a user's edited profile). */
+export function deepMergeProfiles(
+  existing: Record<string, unknown>,
+  incoming: Record<string, unknown>,
+): Record<string, unknown> {
+  const out = { ...existing }
+  for (const [k, v] of Object.entries(incoming)) {
+    if (!(k in out)) out[k] = v
+  }
+  return out
+}
+
+/**
+ * Carry a valid user pane_style preference forward. Setup never writes the
+ * key when absent, and never invents values — only preserves exact "regular"
+ * or "floating". Invalid prev values are dropped.
+ */
+export function preservePaneStyle(
+  prev: Record<string, unknown>,
+): "regular" | "floating" | undefined {
+  const v = prev.pane_style
+  if (v === "regular" || v === "floating") return v
+  return undefined
+}
+
+export function buildProfiles(has: Detected): Record<string, unknown> {
+  const profiles: Record<string, unknown> = {}
+
+  if (has.pi) {
+    // Interactive launches inject PI_CODING_AGENT_DIR without pi-vimmode
+    // through the Pi host adapter, so profiles stay portable.
+    profiles["pi-grok"] = {
+      cmd_interactive: ["pi", "--provider", "grok-cli", "--model", "grok-4.5"],
+      cmd_oneshot: [
+        "pi",
+        "-p",
+        "--provider",
+        "grok-cli",
+        "--model",
+        "grok-4.5",
+      ],
+    }
+    profiles["pi-default"] = {
+      cmd_interactive: ["pi"],
+      cmd_oneshot: ["pi", "-p"],
+    }
+  }
+
+  if (has.claude) {
+    // Interactive TUI only for Apnea dispatch (watchable in Herdr).
+    // cmd_oneshot kept optional for other tooling; Apnea does not use it.
+    profiles["claude-fable"] = {
+      cmd_interactive: ["claude", "--model", "claude-fable-5"],
+      cmd_oneshot: [
+        "claude",
+        "-p",
+        "--model",
+        "claude-fable-5",
+        "--allowedTools",
+        "Read,Write,Edit,Glob,Grep",
+      ],
+    }
+  }
+  if (has.codex) {
+    profiles["codex"] = {
+      cmd_interactive: ["codex"],
+      cmd_oneshot: ["codex", "exec"],
+    }
+  }
+
+  return profiles
+}
+
+export function pickRoles(has: Detected): Record<string, { profile: string }> {
+  const defaultProfile = has.pi
+    ? "pi-grok"
+    : has.claude
+      ? "claude-fable"
+      : "codex"
+  const reviewProfile = has.claude
+    ? "claude-fable"
+    : has.codex
+      ? "codex"
+      : "pi-default"
+
+  return {
+    orchestrator: { profile: defaultProfile },
+    planner: { profile: reviewProfile },
+    reviewer: { profile: reviewProfile },
+    coder: { profile: defaultProfile },
+  }
+}
+
+export function buildGlobalConfig(opts: {
+  has: Detected
+  prev: Record<string, unknown>
+  force: boolean
+}): Record<string, unknown> {
+  const { has, prev, force } = opts
+  const profiles = buildProfiles(has)
+  const roles = pickRoles(has)
+
+  let nextProfiles = profiles
+  if (!force && prev.profiles && typeof prev.profiles === "object") {
+    nextProfiles = deepMergeProfiles(
+      prev.profiles as Record<string, unknown>,
+      profiles,
+    )
+  }
+
+  const preservedPaneStyle = preservePaneStyle(prev)
+
+  const globalConfig: Record<string, unknown> = {
+    profiles: nextProfiles,
+    roles: force || !prev.roles ? roles : prev.roles,
+    review_round_cap:
+      typeof prev.review_round_cap === "number" ? prev.review_round_cap : 3,
+    timeouts_ms:
+      prev.timeouts_ms && typeof prev.timeouts_ms === "object"
+        ? prev.timeouts_ms
+        : // Seed from the runtime defaults so the written template and the
+          // values wait/commit actually use cannot drift apart.
+          { ...DEFAULT_TIMEOUTS },
+  }
+  // Preserve user opt-in only — never introduce pane_style when absent.
+  if (preservedPaneStyle !== undefined) {
+    globalConfig.pane_style = preservedPaneStyle
+  }
+
+  return globalConfig
+}
+
+export function detectionNotes(has: Detected): string[] {
+  const missing: string[] = []
+  if (!has.claude && !has.codex) {
+    missing.push(
+      "no claude/codex — planner/reviewer bound to pi-default (edit global profiles to change)",
+    )
+  }
+  if (!has.herdr) {
+    missing.push("herdr not on PATH — pane launch will fail until installed")
+  }
+  if (!has.jj && !has.git) {
+    missing.push("neither jj nor git on PATH — commits will refuse")
+  }
+  return missing
+}

package/extension/domain/slug.ts

@@ -0,0 +1,9 @@
+export function slugify(s: string): string {
+  return (
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "")
+      .slice(0, 48) || "run"
+  )
+}

package/extension/domain/state-machine.ts

@@ -0,0 +1,132 @@
+import { Result } from "effect"
+import { IllegalTool } from "../errors.ts"
+import type { ReworkTarget, Role, Step } from "./types.ts"
+
+/** Legal next steps after a successful transition from `step`. */
+export const LEGAL_TOOLS: Record<
+  Step,
+  Array<
+    | "workflow_start"
+    | "dispatch_role"
+    | "workflow_wait"
+    | "workflow_commit_phase"
+    | "workflow_status"
+  >
+> = {
+  planning: ["dispatch_role", "workflow_wait", "workflow_status"],
+  plan_review: ["dispatch_role", "workflow_wait", "workflow_status"],
+  phase_packaging: ["dispatch_role", "workflow_wait", "workflow_status"],
+  coding: ["dispatch_role", "workflow_wait", "workflow_status"],
+  code_review: ["dispatch_role", "workflow_wait", "workflow_status"],
+  committing: ["workflow_commit_phase", "workflow_status"],
+  finishing: ["dispatch_role", "workflow_wait", "workflow_status"],
+  done: ["workflow_status"],
+}
+
+export type ToolName = (typeof LEGAL_TOOLS)[Step][number]
+
+/**
+ * Actionable next calls for a step: `LEGAL_TOOLS` minus the read-only
+ * snapshot. An agent follows this list literally, so it must contain only
+ * calls that move the run forward. The human-only cap reset (`reset-rounds`)
+ * is never a Pi tool at all — see `registry.ts` — so it never appears here.
+ */
+export function nextAfter(step: Step): ToolName[] {
+  return LEGAL_TOOLS[step].filter((t) => t !== "workflow_status")
+}
+
+/**
+ * Single source of truth for dispatch kinds — the Pi tool param schema
+ * (`extension/index.ts`), the `state.json` codec (`schema/state.ts`) and the
+ * `/apnea dispatch` completion list all derive from this tuple.
+ */
+export const DISPATCH_KINDS = [
+  "plan",
+  "plan_review",
+  "phase_package",
+  "code",
+  "code_review",
+  "pr_description",
+] as const
+
+export type DispatchKind = (typeof DISPATCH_KINDS)[number]
+
+export function expectedRole(kind: DispatchKind): Role {
+  switch (kind) {
+    case "plan":
+    case "phase_package":
+    case "pr_description":
+      return "planner"
+    case "plan_review":
+    case "code_review":
+      return "reviewer"
+    case "code":
+      return "coder"
+  }
+}
+
+export function allowedKinds(step: Step): DispatchKind[] {
+  switch (step) {
+    case "planning":
+      return ["plan"]
+    case "plan_review":
+      return ["plan_review", "plan"] // plan = rework after CHANGES_REQUIRED
+    case "phase_packaging":
+      return ["phase_package"]
+    case "coding":
+      return ["code"]
+    case "code_review":
+      return ["code_review", "code"]
+    case "finishing":
+      return ["pr_description"]
+    default:
+      return []
+  }
+}
+
+export function stepAfterArtifact(
+  kind: DispatchKind,
+  verdict: string | undefined,
+  rework?: ReworkTarget,
+): Step | { error: string } {
+  switch (kind) {
+    case "plan":
+      return "plan_review"
+    case "plan_review":
+      if (verdict === "APPROVED") return "phase_packaging"
+      if (verdict === "CHANGES_REQUIRED") return "planning"
+      return { error: "plan_review artifact missing verdict" }
+    case "phase_package":
+      return "coding"
+    case "code":
+      return "code_review"
+    case "code_review":
+      if (verdict === "APPROVED") return "committing"
+      if (verdict === "CHANGES_REQUIRED")
+        return rework === "phase_package" ? "phase_packaging" : "coding"
+      return { error: "code_review artifact missing verdict" }
+    case "pr_description":
+      return "done"
+  }
+}
+
+/**
+ * Policy check: is `tool` legal at `step`?
+ * Returns Result.fail(IllegalTool) instead of throwing (no Object.assign cast).
+ */
+export function toolAllowed(
+  step: Step,
+  tool: ToolName,
+): Result.Result<void, IllegalTool> {
+  const legal = LEGAL_TOOLS[step]
+  if (!legal.includes(tool as (typeof legal)[number])) {
+    return Result.fail(
+      new IllegalTool({
+        step,
+        tool,
+        legal: [...legal],
+      }),
+    )
+  }
+  return Result.succeed(undefined)
+}

package/extension/domain/timeouts.ts

@@ -0,0 +1,24 @@
+import type { DispatchKind } from "./state-machine.ts"
+
+/**
+ * Dispatch kind → the `timeouts_ms` key documented in docs/protocol/config.md.
+ * Non-nullable on purpose: a kind mapped to `null` silently ignores whatever
+ * the user configured, and reports the default back as if it were their value.
+ */
+const STEP_KEY: Record<DispatchKind, string> = {
+  plan: "planning",
+  plan_review: "plan_review",
+  phase_package: "phase_packaging",
+  code: "coding",
+  code_review: "code_review",
+  pr_description: "finishing",
+}
+
+export const DEFAULT_TIMEOUT_MS = 900_000
+
+export function timeoutMsForKind(
+  kind: DispatchKind,
+  timeouts: Record<string, number>,
+): number {
+  return timeouts[STEP_KEY[kind]] ?? timeouts.default ?? DEFAULT_TIMEOUT_MS
+}

package/extension/domain/types.ts

@@ -0,0 +1,145 @@
+export type Step =
+  | "planning"
+  | "plan_review"
+  | "phase_packaging"
+  | "coding"
+  | "code_review"
+  | "committing"
+  | "finishing"
+  | "done"
+
+export type Role = "orchestrator" | "planner" | "reviewer" | "coder"
+
+export type RoleMode = "oneshot" | "interactive"
+
+export type PaneStyle = "regular" | "floating"
+
+export type Verdict = "APPROVED" | "CHANGES_REQUIRED"
+
+export type ReworkTarget = "code" | "phase_package"
+
+export type VcsBackend = "jj" | "git"
+
+export interface Profile {
+  cmd_oneshot?: string[]
+  cmd_interactive?: string[]
+}
+
+export interface RoleBinding {
+  profile: string
+}
+
+export interface ApneaConfig {
+  profiles: Record<string, Profile>
+  roles: Record<string, RoleBinding>
+  review_round_cap: number
+  timeouts_ms: Record<string, number>
+  pane_style: PaneStyle
+}
+
+export interface RunState {
+  version: 1
+  slug: string
+  step: Step
+  phase_index: number
+  phase_count_hint: number | null
+  /** Keys: plan_review | phase-NN/code_review | phase-NN/coding | finishing */
+  rounds: Record<string, number>
+  vcs: VcsBackend
+  allow_dirty: boolean
+  goal: string
+  last_error: string | null
+  /** Relative artifact path expected for the in-flight dispatch, if any */
+  pending_artifact: string | null
+  /** Role for pending dispatch */
+  pending_role: Role | null
+  /** Herdr pane id for the in-flight dispatch */
+  pending_pane_id: string | null
+  /** Label of that pane (apnea:role:unique) */
+  pending_pane_label: string | null
+  /**
+   * Relative path to the floating oneshot exit-status file (written when the
+   * popup worker process ends). Null for regular panes. Herdr popups have no
+   * pane id — this is how wait detects death without hanging until timeout.
+   */
+  pending_floating_exit: string | null
+  /**
+   * Epoch ms when the in-flight dispatch was launched. Null when idle.
+   * Persisted so a chunked `workflow_wait` measures elapsed time from the
+   * dispatch, not from the start of the current process.
+   */
+  pending_started_at: number | null
+  /**
+   * Epoch ms after which the in-flight dispatch is considered timed out.
+   * Extensions granted by the recovery ladder move this forward and are
+   * saved, so the budget cannot be silently reset by re-invoking wait.
+   */
+  pending_deadline_ms: number | null
+  /**
+   * Epoch ms of the last idle-nudge sent to the role pane. Persisted so a
+   * fresh process does not re-nudge a role it already nudged.
+   */
+  pending_nudged_at: number | null
+  /**
+   * True once the final-nudge rung has granted its 180s grace. Persisted for
+   * the same reason as `pending_extended`: as a per-call local the grace was
+   * re-granted by every new `wait`, so a role behind a pane that cannot be
+   * prompted extended its own deadline forever and never timed out.
+   */
+  pending_final_grace: boolean
+  /** True once the one-time deadline extension has been consumed. */
+  pending_extended: boolean
+  /**
+   * Last known live pane per role, keyed by role name.
+   * Reuse requires its pane_id and effective profile fingerprint.
+   * Labels are never scanned because they are ambiguous.
+   */
+  role_panes: Partial<
+    Record<
+      Role,
+      { pane_id: string; label: string; profile_fingerprint: string | null }
+    >
+  >
+  /** Absolute path to package root (briefs) */
+  package_root: string
+  /** Tree snapshot fingerprint before reviewer dispatch */
+  reviewer_tree_fingerprint: string | null
+  /** Last known phase package path for verify/commit */
+  current_phase_package: string | null
+  /** Last code-review path for commit gate */
+  current_code_review: string | null
+  /** The next phase-package dispatch must consume planner-owned rework. */
+  phase_package_rework: boolean
+}
+
+export interface FrontMatter {
+  status?: string
+  verdict?: string
+  nits?: string
+  rework?: string
+  raw: string
+  body: string
+}
+
+/**
+ * All worker roles use interactive TUIs so you can watch them live in Herdr.
+ * Oneshot (`claude -p`, `pi -p`) is intentionally not used for dispatch:
+ * it dumps shell output and is not observable as a harness session.
+ */
+export const ROLE_MODE: Record<Role, RoleMode> = {
+  orchestrator: "interactive",
+  planner: "interactive",
+  reviewer: "interactive",
+  coder: "interactive",
+}
+
+export const DEFAULT_TIMEOUTS: Record<string, number> = {
+  planning: 1_500_000,
+  plan_review: 900_000,
+  phase_packaging: 900_000,
+  coding: 2_700_000,
+  code_review: 900_000,
+  verify: 900_000,
+  finishing: 900_000,
+  default: 900_000,
+}

package/extension/domain/verify-commands.ts

@@ -0,0 +1,128 @@
+/** Does this line end in an ODD run of backslashes — a shell continuation? */
+function endsInContinuation(line: string): boolean {
+  const run = /(\\+)$/.exec(line)
+  return run !== null && run[1]!.length % 2 === 1
+}
+
+/**
+ * Split fence lines into logical shell commands: continuations joined,
+ * comments dropped — in ONE pass, because the two interact and both split
+ * orderings shipped bugs.
+ *
+ * Join-then-strip (version 1): a comment ending in `\` swallowed the command
+ * below it, then the merged line was dropped as a comment — `bun test
+ * extension` silently never ran and the phase committed green.
+ *
+ * Strip-then-join (version 2): removing a comment line that sat BETWEEN a
+ * continued line and the next command spliced the two commands together —
+ * `test -f README.md \` + `# note` + `bun test extension` became one command.
+ *
+ * bash resolves this by interleaving, and each command later runs through
+ * `bash -lc`, so bash's rules are the spec:
+ *
+ * - Joining appends the next line with NOTHING between; the final backslash of
+ *   an odd run is dropped, the rest stay (they are escaped literals). A
+ *   backslash that is not the line's last character continues nothing —
+ *   `echo hi \ ` escapes the space and ends the command.
+ * - A `#` at the start of a logical command is a comment; its own trailing
+ *   backslash is inside the comment and continues nothing.
+ * - A comment line reached MID-continuation ends the logical command, when the
+ *   `#` would start a word in the joined text (whitespace before it). Without
+ *   whitespace on either side of the join, `over\` + `#note` is the single
+ *   word `over#note`, not a comment — so it is appended, not terminated on.
+ */
+function logicalCommands(lines: string[]): string[] {
+  const out: string[] = []
+  let acc = ""
+  let pending = false
+  for (const line of lines) {
+    const isCommentish = line.trim().startsWith("#")
+    if (!pending && isCommentish) continue
+    if (pending && isCommentish && (/\s$/.test(acc) || /^\s/.test(line))) {
+      out.push(acc)
+      acc = ""
+      pending = false
+      continue
+    }
+    const continues = endsInContinuation(line)
+    const text = continues ? line.slice(0, -1) : line
+    acc = pending ? acc + text : text
+    pending = continues
+    if (!pending) {
+      out.push(acc)
+      acc = ""
+    }
+  }
+  // A dangling continuation on the last line: keep what we have rather than
+  // dropping the command on the floor.
+  if (pending) out.push(acc)
+  return out
+}
+
+function toCommands(lines: string[]): string[] {
+  const cmds: string[] = []
+  for (const joined of logicalCommands(lines)) {
+    const t = joined.trim()
+    if (t) cmds.push(t)
+  }
+  return cmds
+}
+
+function commandsFromFenceBody(body: string): string[] {
+  return toCommands(body.split(/\r?\n/))
+}
+
+/**
+ * Extract shell commands from a phase package.
+ * Prefer the fence under a "Verify commands" heading — packages often embed
+ * earlier ```bash sketches that must not be executed at the commit gate.
+ */
+export function extractVerifyCommands(phasePackageText: string): string[] {
+  // Heading-scoped fence first (## / ### / **Verify commands**)
+  const section = phasePackageText.match(
+    /(?:^|\n)(?:#{1,6}\s*|\*\*)Verify commands(?:\*\*)?\s*\r?\n([\s\S]*?)(?=\n#{1,6}\s|\n\*\*[A-Z]|$)/i,
+  )
+  if (section) {
+    const fence = section[1]!.match(/```(?:sh|bash|shell)\r?\n([\s\S]*?)```/i)
+    if (fence) {
+      const cmds = commandsFromFenceBody(fence[1]!)
+      if (cmds.length) return cmds
+    }
+  }
+
+  // Fallback: last sh/bash fence in the doc (verify blocks are usually last)
+  const all = [
+    ...phasePackageText.matchAll(/```(?:sh|bash|shell)\r?\n([\s\S]*?)```/gi),
+  ]
+  for (let i = all.length - 1; i >= 0; i--) {
+    const cmds = commandsFromFenceBody(all[i]![1]!)
+    if (cmds.length) return cmds
+  }
+
+  // Last resort: $ / test / bun lines scattered through prose.
+  //
+  // Continuations join FORWARD FROM A MATCHED COMMAND LINE only, never
+  // document-wide. This text is markdown, not shell, and a trailing backslash
+  // on a prose line is a markdown hard break: joining globally glued prose
+  // onto the command below it, the merged line no longer matched the command
+  // pattern, and the check was silently dropped — the gate ran a subset of
+  // the verify commands and committed the phase green. Comments need no
+  // handling here: a line starting with `#` cannot match the pattern.
+  const cmds: string[] = []
+  const rawLines = phasePackageText.split(/\r?\n/)
+  for (let i = 0; i < rawLines.length; i++) {
+    const m = rawLines[i]!.match(
+      /^\s*(?:\$\s+)?((?:test |node |npm |bun |bunx |chmod |head ).+)$/,
+    )
+    if (!m) continue
+    let cmd = m[1]!
+    while (endsInContinuation(cmd) && i + 1 < rawLines.length) {
+      cmd = cmd.slice(0, -1) + rawLines[++i]!
+    }
+    // Dangling continuation on the final line: drop the backslash rather
+    // than handing the shell a command that continues into nothing.
+    if (endsInContinuation(cmd)) cmd = cmd.slice(0, -1)
+    cmds.push(cmd.trim())
+  }
+  return cmds
+}