@naxodev/pi-apnea 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nacho Vazquez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @naxodev/pi-apnea
+
+Pi adapter for the [Apnea workflow engine](../apnea/README.md). It registers Apnea tools, slash commands, skills, and prompts while `@naxodev/apnea` provides the shared workflow and standalone CLI.
+
+## Requirements
+
+- Node.js 22.19 or later
+- Pi 0.83.x or 0.84.x
+- Bun 1.3.7 or later for the transitive `apnea` executable
+- Herdr and at least one supported agent CLI, as documented by [`@naxodev/apnea`](../apnea/README.md#requirements)
+
+## Install
+
+```sh
+pi install npm:@naxodev/pi-apnea
+```
+
+The normal `@naxodev/apnea` dependency installs transitively, including the `apnea` executable. Pi loads this package's `extension`, `skills`, and `prompts` resources.
+
+Pi role panes use a dedicated `PI_CODING_AGENT_DIR` without `pi-vimmode`. The user's orchestrator session remains unchanged.
+
+## Quickstart
+
+Run these commands inside Pi:
+
+```text
+/apnea setup
+/apnea start describe the implementation goal
+/apnea status
+```
+
+`setup` creates global profiles in `~/.config/apnea/config.json` and links the Herdr plugin when Herdr is available. `start` begins one workflow against the current working copy. `status` reports the current step and next legal operation.
+
+The shorter `/apnea-start` and `/apnea-status` aliases are also available. See the [Apnea CLI and operation reference](../apnea/README.md#cli-reference) for the shared command surface and exit behavior.
+
+## Verify
+
+Run `/apnea status` before starting a workflow. A clean installation reports no active run and identifies `workflow_start` as a legal next operation. If Pi does not register the commands, run `/reload` and inspect Pi's package-loading output.
+
+Apnea executes repository-controlled text through configured agent CLIs and can execute planner-authored verification commands. Read the [trust model](../apnea/SECURITY.md) before using it with an untrusted repository.
+
+## Versioning
+
+Compatible core patch releases flow through the `^0.1.0` dependency range. Incompatible host interface changes require coordinated minor releases of both packages.
+
+## Contributing
+
+Use the workspace [contribution guide](../../CONTRIBUTING.md) for setup, checks, and release policy. Use [GitHub Discussions](https://github.com/naxodev/ai/discussions) for usage questions and the workspace [security policy](../../SECURITY.md) for private vulnerability reports.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/extension/commands.ts

@@ -0,0 +1,333 @@
+/**
+ * User-facing slash commands with `/` autocomplete.
+ * These call the same functions as the LLM tools — no workflow_* typing required.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import {
+  DISPATCH_KINDS,
+  formatResult,
+  parseFlags,
+  parseNumFlag,
+  type DispatchKind,
+  type ExecuteOperation,
+  type Operation,
+  type ToolResult,
+} from "@naxodev/apnea"
+import { executePiOperation, PI_OPERATIONS } from "./runtime.ts"
+
+export const SUBS = [
+  ...PI_OPERATIONS.map((o) => o.verb),
+  "resume",
+  "abandon",
+  "help",
+] as const satisfies readonly string[]
+
+function notify(
+  ctx: {
+    ui: { notify: (m: string, l?: "info" | "error" | "warning") => void }
+  },
+  r: ToolResult,
+) {
+  const text = formatResult(r)
+  ctx.ui.notify(text, r.ok ? "info" : "error")
+}
+
+function orchestratorKickMessage(
+  kind: "start" | "resume",
+  goal?: string,
+): string {
+  if (kind === "start") {
+    return [
+      "You are the Apnea orchestrator for this run. Schedule only — no product code.",
+      goal ? `Goal: ${goal}` : null,
+      "State is step=planning with no pending dispatch.",
+      'Immediately call dispatch_role with kind="plan", then workflow_wait.',
+      "Then continue the loop: plan_review → phase_package → code → code_review → workflow_commit_phase → … → pr_description.",
+      "Use workflow_status if unsure. Never call workflow_reset_rounds. Escalate timeouts/caps/dirty-reviewer to the human.",
+    ]
+      .filter(Boolean)
+      .join("\n")
+  }
+  return [
+    "You are the Apnea orchestrator resuming this run. Schedule only — no product code.",
+    "Call workflow_status (and workflow_start action=resume if needed).",
+    "If a pending artifact exists, workflow_wait. Else dispatch the legal kind for the current step.",
+    "Never auto-invent steps; never workflow_reset_rounds; never product code.",
+  ].join("\n")
+}
+
+function helpText(operations: readonly Operation[]): string {
+  // verb + usage on one line (what to type), summary indented below (what
+  // it does) — usage is what regressed when helpText() first went generated:
+  // it rendered only the LLM-facing summary and dropped the flag syntax.
+  const lines = operations.map((o) => {
+    const invocation = o.usage ? `${o.verb} ${o.usage}` : o.verb
+    return `  /apnea ${invocation}\n      ${o.summary}`
+  })
+  return [
+    "Apnea commands (tools remain for the model; you use /apnea):",
+    ...lines,
+    "  /apnea resume | abandon        # actions on an existing run",
+    `      dispatch kinds: ${DISPATCH_KINDS.join(" | ")}`,
+    "  /apnea help",
+  ].join("\n")
+}
+
+export function registerApneaCommands(
+  pi: ExtensionAPI,
+  operations: readonly Operation[] = PI_OPERATIONS,
+  execute: ExecuteOperation = executePiOperation,
+): void {
+  const run = (verb: string, params: Record<string, unknown>) => {
+    const operation = operations.find((candidate) => candidate.verb === verb)
+    if (!operation) throw new Error(`Missing Apnea operation: ${verb}`)
+    return execute(operation.verb, params)
+  }
+  const kick = (kind: "start" | "resume", goal?: string) => {
+    pi.sendUserMessage(orchestratorKickMessage(kind, goal))
+  }
+
+  pi.registerCommand("apnea", {
+    description: "Apnea workflow: start, status, dispatch, wait, commit, …",
+    getArgumentCompletions: (prefix: string) => {
+      const parts = prefix.trimStart().split(/\s+/)
+      // completing first token (subcommand)
+      if (parts.length <= 1) {
+        const p = parts[0] ?? ""
+        const hits = SUBS.filter((s) => s.startsWith(p)).map((s) => ({
+          value: s,
+          label: s,
+        }))
+        return hits.length ? hits : null
+      }
+      const sub = parts[0]
+      if (sub === "dispatch") {
+        const p = parts[1] ?? ""
+        // Complete the kind token only — Pi replaces the last token.
+        const hits = DISPATCH_KINDS.filter((k) => k.startsWith(p)).map((k) => ({
+          value: k,
+          label: k,
+        }))
+        return hits.length ? hits : null
+      }
+      if (sub === "setup") {
+        const p = parts[1] ?? ""
+        const flags = ["--project", "--force", "--agents-md"]
+        const hits = flags
+          .filter((f) => f.startsWith(p) || p === "")
+          .map((f) => ({ value: f, label: f }))
+        return hits.length ? hits : null
+      }
+      if (sub === "start" && parts.length === 2 && parts[1]?.startsWith("--")) {
+        const flags = ["--allow-dirty", "--slug="]
+        const p = parts[1] ?? ""
+        const hits = flags
+          .filter((f) => f.startsWith(p))
+          .map((f) => ({ value: f, label: f }))
+        return hits.length ? hits : null
+      }
+      if (sub === "commit") {
+        const p = parts[1] ?? ""
+        if (p.startsWith("-") || p === "") {
+          const hits = ["--done"]
+            .filter((f) => f.startsWith(p) || p === "")
+            .map((f) => ({ value: f, label: f }))
+          return hits.length ? hits : null
+        }
+      }
+      if (sub === "reset-rounds") {
+        const gates = [
+          "plan_review",
+          "phase-01/code_review",
+          "phase-02/code_review",
+        ]
+        const p = parts[1] ?? ""
+        const hits = gates
+          .filter((g) => g.startsWith(p))
+          .map((g) => ({ value: g, label: g }))
+        return hits.length ? hits : null
+      }
+      return null
+    },
+    handler: async (args, ctx) => {
+      const raw = args.trim()
+      if (!raw || raw === "help") {
+        ctx.ui.notify(helpText(operations), "info")
+        return
+      }
+
+      const tokens = raw.split(/\s+/).filter(Boolean)
+      const sub = tokens[0]!
+      const { flags, values, rest } = parseFlags(tokens.slice(1))
+
+      try {
+        switch (sub) {
+          case "help":
+            ctx.ui.notify(helpText(operations), "info")
+            return
+
+          case "setup":
+            notify(
+              ctx,
+              await run("setup", {
+                project: flags.has("project"),
+                force: flags.has("force"),
+                agents_md: flags.has("agents-md"),
+              }),
+            )
+            return
+
+          case "start": {
+            // goal is everything not a flag; support --slug=x
+            const slug = values.get("slug")
+            const goal = rest.join(" ").trim()
+            if (!goal) {
+              ctx.ui.notify(
+                "Usage: /apnea start <goal> [--allow-dirty] [--slug=name]",
+                "error",
+              )
+              return
+            }
+            const r = await run("start", {
+              goal,
+              slug,
+              allow_dirty: flags.has("allow-dirty"),
+              action: "start",
+            })
+            notify(ctx, r)
+            if (r.ok) kick("start", goal)
+            return
+          }
+
+          case "resume": {
+            const r = await run("start", { goal: "", action: "resume" })
+            notify(ctx, r)
+            if (r.ok) kick("resume")
+            return
+          }
+
+          case "abandon":
+            notify(ctx, await run("start", { goal: "", action: "abandon" }))
+            return
+
+          case "status":
+            notify(ctx, await run("status", {}))
+            return
+
+          case "wait": {
+            // `--timeout` and `--budget` are the same knob: how long THIS
+            // call blocks. The role's deadline comes from config, stamped
+            // at dispatch. Same flags as `apnea wait`; only the default
+            // differs, because this surface has no host shell to time out.
+            const poll = parseNumFlag(values, "poll")
+            if (!poll.ok) {
+              ctx.ui.notify(
+                `Usage: /apnea wait [--poll=<ms>] (got --poll=${poll.raw})`,
+                "error",
+              )
+              return
+            }
+            const budget = parseNumFlag(values, "budget")
+            if (!budget.ok) {
+              ctx.ui.notify(
+                `Usage: /apnea wait [--budget=<ms>] (got --budget=${budget.raw})`,
+                "error",
+              )
+              return
+            }
+            const timeout = parseNumFlag(values, "timeout")
+            if (!timeout.ok) {
+              ctx.ui.notify(
+                `Usage: /apnea wait [--timeout=<ms>] (got --timeout=${timeout.raw})`,
+                "error",
+              )
+              return
+            }
+            const r = await run("wait", {
+              poll_ms: poll.value,
+              // Unbounded by default, like the Pi tool in `index.ts`:
+              // `/apnea` runs inside Pi, which has no shell timeout, so
+              // the CLI's chunking default would end the wait with a
+              // green "still waiting" toast and nothing left polling.
+              budget_ms:
+                budget.value ?? timeout.value ?? Number.MAX_SAFE_INTEGER,
+            })
+            notify(ctx, r)
+            return
+          }
+
+          case "dispatch": {
+            const kind = rest[0] as DispatchKind | undefined
+            if (!kind || !DISPATCH_KINDS.includes(kind)) {
+              ctx.ui.notify(
+                `Usage: /apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework]`,
+                "error",
+              )
+              return
+            }
+            notify(
+              ctx,
+              await run("dispatch", {
+                kind,
+                rework: flags.has("rework"),
+              }),
+            )
+            return
+          }
+
+          case "commit": {
+            // `parseFlags` already strips `--` tokens into `flags`/`values`;
+            // `rest` never contains them, so no filter is needed here.
+            const message = rest.join(" ").trim() || undefined
+            notify(
+              ctx,
+              await run("commit", {
+                message,
+                no_remaining_phases: flags.has("done"),
+              }),
+            )
+            return
+          }
+
+          case "reset-rounds": {
+            const gate = rest[0]
+            if (!gate) {
+              ctx.ui.notify("Usage: /apnea reset-rounds <gate>", "error")
+              return
+            }
+            notify(ctx, await run("reset-rounds", { gate }))
+            return
+          }
+
+          default:
+            ctx.ui.notify(
+              `Unknown subcommand: ${sub}\n${helpText(operations)}`,
+              "error",
+            )
+        }
+      } catch (e) {
+        ctx.ui.notify(e instanceof Error ? e.message : String(e), "error")
+      }
+    },
+  })
+
+  // Short aliases that also show in `/` autocomplete
+  pi.registerCommand("apnea-status", {
+    description: "Apnea: read-only run status (alias of /apnea status)",
+    handler: async (_args, ctx) => notify(ctx, await run("status", {})),
+  })
+
+  pi.registerCommand("apnea-start", {
+    description: "Apnea: start a run — /apnea-start <goal>",
+    handler: async (args, ctx) => {
+      const goal = args.trim()
+      if (!goal) {
+        ctx.ui.notify("Usage: /apnea-start <goal>", "error")
+        return
+      }
+      const r = await run("start", { goal, action: "start" })
+      notify(ctx, r)
+      if (r.ok) kick("start", goal)
+    },
+  })
+}

package/extension/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @naxodev/pi-apnea — Pi adapter for the Apnea workflow.
+ *
+ * Definitions come from @naxodev/apnea; this file only binds them to Pi.
+ * The standalone CLI binds the same registry to argv.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { toolContent } from "@naxodev/apnea"
+import { registerApneaCommands } from "./commands.ts"
+import { executePiOperation, PI_OPERATIONS } from "./runtime.ts"
+
+export default function (pi: ExtensionAPI) {
+  // `/apnea …` for humans (autocomplete); tools remain for the model
+  registerApneaCommands(pi, PI_OPERATIONS, executePiOperation)
+
+  for (const op of PI_OPERATIONS) {
+    if (op.tool === null) continue
+
+    // wait is the one operation with streaming + abort; Pi's exclusive.
+    if (op.tool === "workflow_wait") {
+      pi.registerTool({
+        name: op.tool,
+        label: "Apnea wait",
+        description: [op.summary, op.guidance].filter(Boolean).join(" "),
+        parameters: op.params,
+        async execute(
+          _id: string,
+          params: { poll_ms?: number; budget_ms?: number },
+          signal: AbortSignal | undefined,
+          onUpdate:
+            | ((partial: {
+                content: Array<{ type: "text"; text: string }>
+                details: unknown
+              }) => void)
+            | undefined,
+        ) {
+          return toolContent(
+            // Pi blocks in one chunk by design: it streams progress and
+            // can be interrupted, so it has no host shell timeout to fit
+            // inside. The registry handler no longer injects this — only
+            // the CLI reaches that, and it must stay bounded.
+            await executePiOperation(
+              op.verb,
+              {
+                ...params,
+                budget_ms: params.budget_ms ?? Number.MAX_SAFE_INTEGER,
+              },
+              {
+                signal,
+                onUpdate: onUpdate
+                  ? (partial) =>
+                      onUpdate({
+                        content: partial.content,
+                        details: {
+                          ok: true,
+                          message: partial.content[0]?.text ?? "",
+                        },
+                      })
+                  : undefined,
+              },
+            ),
+          )
+        },
+      })
+      continue
+    }
+
+    pi.registerTool({
+      name: op.tool,
+      label: `Apnea ${op.verb}`,
+      description: [op.summary, op.guidance].filter(Boolean).join(" "),
+      parameters: op.params,
+      async execute(_id: string, params: Record<string, unknown>) {
+        return toolContent(await executePiOperation(op.verb, params))
+      },
+    })
+  }
+}

package/extension/pi-role-agent.ts

@@ -0,0 +1,171 @@
+/**
+ * Role-pane pi launches must not load pi-vimmode. Modal vim intercepts
+ * herdr `pane run` pastes and leaves the pointer sitting in INSERT — the
+ * single biggest cause of idle-without-artifact stalls for the coder.
+ *
+ * Strategy: materialize a dedicated PI_CODING_AGENT_DIR that reuses the
+ * user's auth/npm/skills but filters pi-vimmode out of packages, then wrap
+ * interactive `pi` launches with that env. Reused panes also get a
+ * best-effort `/vimmode off` slash command.
+ */
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+const PI_VIMMODE_MARKERS = ["pi-vimmode", "pekochan069/pi-vimmode"]
+
+export function isPiCmd(cmd: string[] | undefined | null): boolean {
+  if (!cmd?.length) return false
+  const bin = path.basename(cmd[0]!)
+  return bin === "pi"
+}
+
+export function packageSource(entry: unknown): string | null {
+  if (typeof entry === "string") return entry
+  if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+    const src = (entry as Record<string, unknown>).source
+    return typeof src === "string" ? src : null
+  }
+  return null
+}
+
+/** True when a packages[] entry is (or wraps) pi-vimmode. */
+export function isPiVimModePackage(entry: unknown): boolean {
+  const src = packageSource(entry)
+  if (!src) return false
+  const lower = src.toLowerCase()
+  return PI_VIMMODE_MARKERS.some((m) => lower.includes(m))
+}
+
+/**
+ * Drop pi-vimmode from a packages list. Leaves every other entry intact
+ * (string form and object form with filters).
+ */
+export function filterPackagesNoVim(packages: unknown): unknown[] {
+  if (!Array.isArray(packages)) return []
+  return packages.filter((p) => !isPiVimModePackage(p))
+}
+
+export function defaultSourceAgentDir(): string {
+  return (
+    process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent")
+  )
+}
+
+export function defaultRoleAgentDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir()
+  return path.join(home, ".config", "apnea", "pi-role-agent")
+}
+
+function symlinkOrCopy(src: string, dest: string): void {
+  if (!fs.existsSync(src)) return
+  if (path.resolve(src) === path.resolve(dest)) return
+  try {
+    if (fs.existsSync(dest) || fs.lstatSync(dest).isSymbolicLink()) {
+      fs.rmSync(dest, { recursive: true, force: true })
+    }
+  } catch {
+    try {
+      fs.rmSync(dest, { recursive: true, force: true })
+    } catch {
+      /* ignore */
+    }
+  }
+  try {
+    fs.symlinkSync(src, dest)
+  } catch {
+    // Windows or no-symlink FS: copy
+    const st = fs.statSync(src)
+    if (st.isDirectory()) {
+      fs.cpSync(src, dest, { recursive: true, force: true })
+    } else {
+      fs.copyFileSync(src, dest)
+    }
+  }
+}
+
+/**
+ * Build (or refresh) a PI_CODING_AGENT_DIR for Apnea role panes.
+ * - settings.json: user's packages minus pi-vimmode; piVimMode key stripped
+ * - auth/npm/skills/extensions/themes/models: linked from the real agent dir
+ *
+ * Idempotent. Safe to call on every dispatch.
+ */
+export function materializePiRoleAgentDir(opts?: {
+  sourceAgentDir?: string
+  destDir?: string
+}): string {
+  const source = opts?.sourceAgentDir ?? defaultSourceAgentDir()
+  const dest = opts?.destDir ?? defaultRoleAgentDir()
+  fs.mkdirSync(dest, { recursive: true })
+
+  const srcSettingsPath = path.join(source, "settings.json")
+  let settings: Record<string, unknown> = {}
+  if (fs.existsSync(srcSettingsPath)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(srcSettingsPath, "utf8"))
+      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        settings = { ...(raw as Record<string, unknown>) }
+      }
+    } catch {
+      settings = {}
+    }
+  }
+
+  settings.packages = filterPackagesNoVim(settings.packages)
+  delete settings.piVimMode
+
+  fs.writeFileSync(
+    path.join(dest, "settings.json"),
+    `${JSON.stringify(settings, null, 2)}\n`,
+    "utf8",
+  )
+
+  // Reuse identity + installed packages; keep sessions local to role dir.
+  for (const name of [
+    "auth.json",
+    "npm",
+    "skills",
+    "extensions",
+    "themes",
+    "models.json",
+    "bin",
+    "tools",
+  ]) {
+    symlinkOrCopy(path.join(source, name), path.join(dest, name))
+  }
+
+  // Optional: pi-vimmode.config.js must not apply either
+  const vimCfg = path.join(dest, "pi-vimmode.config.js")
+  if (fs.existsSync(vimCfg) || safeIsSymlink(vimCfg)) {
+    try {
+      fs.rmSync(vimCfg, { force: true })
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return dest
+}
+
+function safeIsSymlink(p: string): boolean {
+  try {
+    return fs.lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Prefix a pi interactive command with env PI_CODING_AGENT_DIR=... so the
+ * role pane never loads pi-vimmode. Non-pi cmds pass through unchanged.
+ * `opts` is for tests; production callers omit it.
+ */
+export function wrapInteractiveCmdNoVim(
+  cmd: string[],
+  opts?: { sourceAgentDir?: string; destDir?: string },
+): string[] {
+  if (!isPiCmd(cmd)) return cmd
+  const agentDir = materializePiRoleAgentDir(opts)
+  return ["env", `PI_CODING_AGENT_DIR=${agentDir}`, ...cmd]
+}

package/extension/runtime.ts

@@ -0,0 +1,20 @@
+import {
+  createExecutor,
+  createOperations,
+  type ApneaHostAdapter,
+} from "@naxodev/apnea"
+import {
+  isPiCmd,
+  materializePiRoleAgentDir,
+  wrapInteractiveCmdNoVim,
+} from "./pi-role-agent.ts"
+
+export const piHostAdapter: ApneaHostAdapter = {
+  materializeRoleAgentDir: materializePiRoleAgentDir,
+  prepareInteractiveCommand: wrapInteractiveCmdNoVim,
+  beforeInteractivePrompt: (command) =>
+    isPiCmd(command) ? "/vimmode off" : null,
+}
+
+export const PI_OPERATIONS = createOperations(piHostAdapter)
+export const executePiOperation = createExecutor(piHostAdapter)

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@naxodev/pi-apnea",
+  "version": "0.1.0",
+  "description": "Pi adapter for the Apnea multi-role workflow",
+  "license": "MIT",
+  "author": "Nacho Vazquez",
+  "funding": "https://github.com/sponsors/NachoVazquez",
+  "homepage": "https://github.com/naxodev/ai/tree/main/packages/pi-apnea#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naxodev/ai.git",
+    "directory": "packages/pi-apnea"
+  },
+  "bugs": {
+    "url": "https://github.com/naxodev/ai/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "apnea",
+    "herdr",
+    "workflow"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "extensions": [
+      "./extension"
+    ]
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "extension",
+    "prompts",
+    "skills",
+    "!extension/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.7",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "bun run typecheck && bun run test && bun run format:check && bun run pack:check && bun run smoke:package",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test extension scripts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pack:check": "bun scripts/verify-pack.ts",
+    "prepublish:core": "bun scripts/check-core-published.ts",
+    "smoke:package": "bun scripts/package-smoke.ts"
+  },
+  "dependencies": {
+    "@naxodev/apnea": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <0.85.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.2",
+    "prettier": "^3.9.0",
+    "typescript": "^7.0.2"
+  }
+}

package/prompts/apnea-init.md

@@ -0,0 +1,20 @@
+---
+description: Initialize Apnea config (prefer /apnea setup)
+---
+
+Prefer the slash command (no model needed):
+
+```
+/apnea setup
+/apnea setup --project
+```
+
+If tools/commands are unavailable, run the apnea-setup skill steps:
+
+1. Detect `pi`, `claude`, `codex`, `herdr`, `jj`, `git` on PATH.
+2. Create or update `~/.config/apnea/config.json` with **profiles** only (no project cmds).
+3. Optional: `.apnea/config.json` with role→profile names only.
+4. Point at `@naxodev/apnea/docs/protocol/config.md`.
+5. Note `pane_style` (`regular` default / `floating` opt-in, needs herdr ≥ 0.7.4) — setup never writes it.
+
+Do not invent binaries. Do not write `cmd` into project config.

package/skills/apnea-orchestrator/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: apnea-orchestrator
+description: Drive an Apnea run as hybrid orchestrator (schedule only). Use when starting or resuming a multi-role plan→review→code loop in Herdr.
+---
+
+# apnea-orchestrator
+
+## Goal
+
+Drive one **Run** to `pr-description.md` without writing product code.
+
+## Critical: start is not the loop
+
+`workflow_start` / `/apnea start` only writes `.apnea/state.json` with `step=planning`.  
+**It does not launch any role.** Stopping after start is a failed orchestration.
+
+Immediately after a successful start:
+
+1. `dispatch_role` with `kind: "plan"`
+2. `workflow_wait`
+3. Continue the loop until `done`
+
+## When tools exist
+
+Use only these; the CLI column is the same operation for a harness with no Apnea Pi plugin. See `@naxodev/apnea/docs/adr/0009-cli-driver-split.md`.
+
+| Tool                    | CLI                     |
+| ----------------------- | ----------------------- |
+| `workflow_start`        | `apnea start <goal>`    |
+| `dispatch_role`         | `apnea dispatch <kind>` |
+| `workflow_wait`         | `apnea wait`            |
+| `workflow_commit_phase` | `apnea commit`          |
+| `workflow_status`       | `apnea status`          |
+
+`apnea wait` returns exit `3` when its own budget runs out but the role still has time. That is not a failure. Call `apnea wait` again, as many times as it takes. The default budget is 90s, so the call returns before a typical 120s shell timeout kills it.
+
+Do not pass `--budget` below 72s. A call must be long enough to contain the 60s idle nudge and the four polls that detect a dead harness; a shorter call is refused, with the required floor in the message. Raising `--poll` raises that floor, and if you omit `--budget` it is raised to match, so the call runs longer rather than failing. Keep `--poll` between 250ms and 26999ms, or state `--budget` yourself — above that the floor outgrows a typical shell timeout. Whether the role was already nudged, already took its one-time extension, and its deadline all persist across calls — only these two duration checks need one call to complete.
+
+Never: `apnea reset-rounds` / `/apnea reset-rounds` (human only - it is not a model-facing tool; see `@naxodev/apnea/docs/adr/0002-orchestrator-authority.md`), never edit `.apnea/state.json` by hand, never implement product code.
+
+### Loop (do not skip steps)
+
+```text
+start
+  → dispatch plan → wait
+  → dispatch plan_review → wait
+      CHANGES_REQUIRED → dispatch plan (rework=true) → wait → plan_review …
+      APPROVED → dispatch phase_package → wait
+  → dispatch code → wait
+  → dispatch code_review → wait
+      CHANGES_REQUIRED → dispatch code (rework=true) → wait → code_review …
+      APPROVED → workflow_commit_phase
+  → more phases? → phase_package …
+  → else → dispatch pr_description → wait → done
+```
+
+Follow `@naxodev/apnea/briefs/orchestrator.md` and `@naxodev/apnea/docs/protocol/overview.md`.
+
+## When Pi tools are absent
+
+Run the `apnea` CLI instead — same loop, same refusals (see the table above). Any shell that
+can run `apnea` can hold the orchestrator seat.
+
+## Paper mode (no shell at all)
+
+If you cannot run shell commands either, you may still help the **human** orchestrate:
+
+- Propose exact task file contents and pointer messages
+- Name exact artifact paths for the current step
+- Parse front-matter when asked
+- Remind verify-before-commit
+
+Do not pretend tools exist.
+
+## Active recovery before escalate
+
+Do **not** stop at the first timeout. Investigate and fix:
+
+1. `herdr pane get` / `pane read` the pending role pane.
+2. Prompt stuck in input → `send-keys Enter` or re-`pane run` the pointer.
+3. Idle without artifact → nudge with exact artifact path.
+4. Still working / API retry → `workflow_wait` again.
+5. Pane dead → `dispatch_role` same kind (not rework).
+
+Escalate only after two failed recovery attempts, or on round cap / dirty reviewer tree / illegal step / VCS confusion.

package/skills/apnea-setup/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: apnea-setup
+description: Create global Apnea profiles and optional project role bindings. Prefer /apnea setup when the extension is loaded. Use this skill when installing Apnea without commands, switching providers, or fixing config trust errors.
+---
+
+# apnea-setup
+
+## Prefer
+
+If the Apnea extension is loaded:
+
+```
+/apnea setup
+/apnea setup --project   # also write .apnea/config.json bindings
+/apnea setup --force     # replace global profiles instead of merge
+```
+
+That path is deterministic (no LLM). Use this skill only as a fallback.
+
+## Goal
+
+Leave the user with a valid **global** profile config and optional **project** role bindings. Never put binaries in project config.
+
+## Steps (fallback)
+
+1. Read `@naxodev/apnea/docs/protocol/config.md` if available.
+2. Check PATH for: `pi`, `claude`, `codex`, `herdr`, `jj`, `git`.
+3. Ensure `~/.config/apnea/` exists.
+4. Write or merge `~/.config/apnea/config.json`:
+   - Define profiles only for binaries that exist.
+   - Include both `cmd_oneshot` and `cmd_interactive` where the harness supports them.
+   - Bind default roles: orchestrator+coder → pi profile; planner+reviewer → claude or codex if present, else pi.
+   - Preserve an existing `pane_style` (`regular`|`floating`) if present; **never write/flip `pane_style`** — it is user opt-in only.
+5. When herdr is on PATH, provision the herdr `apnea` plugin: copy `herdr-plugin/` from the installed `@naxodev/apnea` package to `~/.config/apnea/herdr-plugin/` (refresh on every run) and, if herdr ≥ 0.7.4 and the plugin is not already linked, run `herdr plugin link ~/.config/apnea/herdr-plugin`. On herdr < 0.7.4, skip link and note the upgrade requirement.
+6. Optionally write `.apnea/config.json` with **only** `{ "roles": { "...": { "profile": "..." } } }`.
+7. Validate against trust rules: no project `cmd_*`, no unknown isolation modes.
+8. Next: `/apnea start <goal>` inside Herdr.
+
+## Refuse
+
+- Writing `cmd`, `cmd_oneshot`, `cmd_interactive`, or `bin` under the project.