@naxodev/pi-apnea 0.2.0 → 0.2.1

package/extension/commands.ts

@@ -6,8 +6,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import {
   DISPATCH_KINDS,
   formatResult,
-  parseFlags,
   parseNumFlag,
+  parseOperationArgs,
   type DispatchKind,
   type ExecuteOperation,
   type Operation,
@@ -78,10 +78,14 @@ export function registerApneaCommands(
   operations: readonly Operation[] = PI_OPERATIONS,
   execute: ExecuteOperation = executePiOperation,
 ): void {
-  const run = (verb: string, params: Record<string, unknown>) => {
+  const run = (
+    signal: AbortSignal | undefined,
+    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)
+    return execute(operation.verb, params, { signal })
   }
   const kick = (kind: "start" | "resume", goal?: string) => {
     pi.sendUserMessage(orchestratorKickMessage(kind, goal))
@@ -158,9 +162,16 @@ export function registerApneaCommands(
 
       const tokens = raw.split(/\s+/).filter(Boolean)
       const sub = tokens[0]!
-      const { flags, values, rest } = parseFlags(tokens.slice(1))
-
       try {
+        const parsed = parseOperationArgs(sub, tokens.slice(1), {
+          surface: "slash",
+        })
+        if (!parsed.ok) {
+          ctx.ui.notify(parsed.message, "error")
+          return
+        }
+        const { flags, values, positional: rest } = parsed
+
         switch (sub) {
           case "help":
             ctx.ui.notify(helpText(operations), "info")
@@ -169,7 +180,7 @@ export function registerApneaCommands(
           case "setup":
             notify(
               ctx,
-              await run("setup", {
+              await run(ctx.signal, "setup", {
                 project: flags.has("project"),
                 force: flags.has("force"),
                 agents_md: flags.has("agents-md"),
@@ -188,7 +199,7 @@ export function registerApneaCommands(
               )
               return
             }
-            const r = await run("start", {
+            const r = await run(ctx.signal, "start", {
               goal,
               slug,
               allow_dirty: flags.has("allow-dirty"),
@@ -200,18 +211,24 @@ export function registerApneaCommands(
           }
 
           case "resume": {
-            const r = await run("start", { goal: "", action: "resume" })
+            const r = await run(ctx.signal, "start", {
+              goal: "",
+              action: "resume",
+            })
             notify(ctx, r)
             if (r.ok) kick("resume")
             return
           }
 
           case "abandon":
-            notify(ctx, await run("start", { goal: "", action: "abandon" }))
+            notify(
+              ctx,
+              await run(ctx.signal, "start", { goal: "", action: "abandon" }),
+            )
             return
 
           case "status":
-            notify(ctx, await run("status", {}))
+            notify(ctx, await run(ctx.signal, "status", {}))
             return
 
           case "wait": {
@@ -243,7 +260,7 @@ export function registerApneaCommands(
               )
               return
             }
-            const r = await run("wait", {
+            const r = await run(ctx.signal, "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
@@ -260,16 +277,17 @@ export function registerApneaCommands(
             const kind = rest[0] as DispatchKind | undefined
             if (!kind || !DISPATCH_KINDS.includes(kind)) {
               ctx.ui.notify(
-                `Usage: /apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework]`,
+                `Usage: /apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework] [--redeliver]`,
                 "error",
               )
               return
             }
             notify(
               ctx,
-              await run("dispatch", {
+              await run(ctx.signal, "dispatch", {
                 kind,
                 rework: flags.has("rework"),
+                redeliver: flags.has("redeliver"),
               }),
             )
             return
@@ -281,7 +299,7 @@ export function registerApneaCommands(
             const message = rest.join(" ").trim() || undefined
             notify(
               ctx,
-              await run("commit", {
+              await run(ctx.signal, "commit", {
                 message,
                 no_remaining_phases: flags.has("done"),
               }),
@@ -295,7 +313,7 @@ export function registerApneaCommands(
               ctx.ui.notify("Usage: /apnea reset-rounds <gate>", "error")
               return
             }
-            notify(ctx, await run("reset-rounds", { gate }))
+            notify(ctx, await run(ctx.signal, "reset-rounds", { gate }))
             return
           }
 
@@ -314,7 +332,8 @@ export function registerApneaCommands(
   // 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", {})),
+    handler: async (_args, ctx) =>
+      notify(ctx, await run(ctx.signal, "status", {})),
   })
 
   pi.registerCommand("apnea-start", {
@@ -325,7 +344,7 @@ export function registerApneaCommands(
         ctx.ui.notify("Usage: /apnea-start <goal>", "error")
         return
       }
-      const r = await run("start", { goal, action: "start" })
+      const r = await run(ctx.signal, "start", { goal, action: "start" })
       notify(ctx, r)
       if (r.ok) kick("start", goal)
     },

package/extension/index.ts

@@ -5,7 +5,11 @@
  * The standalone CLI binds the same registry to argv.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
-import { toolContent } from "@naxodev/apnea"
+import {
+  toolContent,
+  type ExecuteOperation,
+  type Operation,
+} from "@naxodev/apnea"
 import { registerApneaCommands } from "./commands.ts"
 import { executePiOperation, PI_OPERATIONS } from "./runtime.ts"
 
@@ -13,7 +17,15 @@ 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) {
+  registerApneaTools(pi, PI_OPERATIONS, executePiOperation)
+}
+
+export function registerApneaTools(
+  pi: ExtensionAPI,
+  operations: readonly Operation[],
+  executeOperation: ExecuteOperation,
+): void {
+  for (const op of operations) {
     if (op.tool === null) continue
 
     // wait is the one operation with streaming + abort; Pi's exclusive.
@@ -23,6 +35,7 @@ export default function (pi: ExtensionAPI) {
         label: "Apnea wait",
         description: [op.summary, op.guidance].filter(Boolean).join(" "),
         parameters: op.params,
+        executionMode: "sequential",
         async execute(
           _id: string,
           params: { poll_ms?: number; budget_ms?: number },
@@ -39,7 +52,7 @@ export default function (pi: ExtensionAPI) {
             // 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(
+            await executeOperation(
               op.verb,
               {
                 ...params,
@@ -70,8 +83,33 @@ export default function (pi: ExtensionAPI) {
       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))
+      executionMode: "sequential",
+      async execute(
+        _id: string,
+        params: Record<string, unknown>,
+        signal: AbortSignal | undefined,
+        onUpdate:
+          | ((partial: {
+              content: Array<{ type: "text"; text: string }>
+              details: unknown
+            }) => void)
+          | undefined,
+      ) {
+        return toolContent(
+          await executeOperation(op.verb, params, {
+            signal,
+            onUpdate: onUpdate
+              ? (partial) =>
+                  onUpdate({
+                    content: partial.content,
+                    details: {
+                      ok: true,
+                      message: partial.content[0]?.text ?? "",
+                    },
+                  })
+              : undefined,
+          }),
+        )
       },
     })
   }

package/extension/pi-role-agent.ts

@@ -4,20 +4,102 @@
  * 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
+ * user's auth/npm/skills but filters pi-vimmode packages and extensions,
+ * then wraps 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"
+import { randomUUID } from "node:crypto"
+import { fileURLToPath } from "node:url"
 
 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"
+  return piCommandIndex(cmd) !== null
+}
+
+function piCommandIndex(cmd: string[] | undefined | null): number | null {
+  if (!cmd?.length) return null
+  const first = path.basename(cmd[0]!)
+  if (first === "pi") return 0
+  if (first === "bunx") {
+    let index = 1
+    while (index < cmd.length) {
+      const token = cmd[index]!
+      if (
+        token === "--bun" ||
+        token === "--no-install" ||
+        token === "--verbose" ||
+        token === "--silent"
+      ) {
+        index += 1
+        continue
+      }
+      if (token === "-p" || token === "--package") {
+        if (cmd[index + 1] === undefined) return null
+        index += 2
+        continue
+      }
+      if (token.startsWith("--package=")) {
+        if (token.length === "--package=".length) return null
+        index += 1
+        continue
+      }
+      if (token === "--") {
+        index += 1
+        break
+      }
+      if (token.startsWith("-")) return null
+      break
+    }
+    return path.basename(cmd[index] ?? "") === "pi" ? index : null
+  }
+  if (first !== "env") return null
+
+  let index = 1
+  while (index < cmd.length) {
+    const token = cmd[index]!
+    if (
+      token === "-i" ||
+      token === "--ignore-environment" ||
+      token === "-v" ||
+      token === "--debug"
+    ) {
+      index += 1
+      continue
+    }
+    if (
+      token === "-u" ||
+      token === "--unset" ||
+      token === "-C" ||
+      token === "--chdir" ||
+      token === "-P" ||
+      token === "-S" ||
+      token === "--split-string"
+    ) {
+      if (cmd[index + 1] === undefined) return null
+      index += 2
+      continue
+    }
+    if (token.startsWith("--unset=")) {
+      if (token.length === "--unset=".length) return null
+      index += 1
+      continue
+    }
+    if (token === "--") {
+      index += 1
+      break
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) {
+      index += 1
+      continue
+    }
+    if (token.startsWith("-")) return null
+    break
+  }
+  return path.basename(cmd[index] ?? "") === "pi" ? index : null
 }
 
 export function packageSource(entry: unknown): string | null {
@@ -37,6 +119,11 @@ export function isPiVimModePackage(entry: unknown): boolean {
   return PI_VIMMODE_MARKERS.some((m) => lower.includes(m))
 }
 
+function hasVimModeMarker(value: string): boolean {
+  const lower = value.toLowerCase()
+  return PI_VIMMODE_MARKERS.some((marker) => lower.includes(marker))
+}
+
 /**
  * Drop pi-vimmode from a packages list. Leaves every other entry intact
  * (string form and object form with filters).
@@ -46,6 +133,159 @@ export function filterPackagesNoVim(packages: unknown): unknown[] {
   return packages.filter((p) => !isPiVimModePackage(p))
 }
 
+const PACKAGE_SOURCE_KEYS = new Set([
+  "source",
+  "autoload",
+  "extensions",
+  "skills",
+  "prompts",
+  "themes",
+])
+const PACKAGE_RESOURCE_KEYS = [
+  "extensions",
+  "skills",
+  "prompts",
+  "themes",
+] as const
+
+type ValidPackageSource =
+  | string
+  | {
+      source: string
+      autoload?: boolean
+      extensions?: string[]
+      skills?: string[]
+      prompts?: string[]
+      themes?: string[]
+    }
+
+function validatePackageSource(entry: unknown): ValidPackageSource {
+  if (typeof entry === "string") {
+    if (entry.trim() === "") throw new Error("package source must not be empty")
+    return entry
+  }
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new Error("package entry must be a string or object")
+  }
+
+  const value = entry as Record<string, unknown>
+  if (Object.keys(value).some((key) => !PACKAGE_SOURCE_KEYS.has(key))) {
+    throw new Error("package entry contains unknown keys")
+  }
+  if (typeof value.source !== "string" || value.source.trim() === "") {
+    throw new Error("package object source must be a non-empty string")
+  }
+  if (value.autoload !== undefined && typeof value.autoload !== "boolean") {
+    throw new Error("package object autoload must be a boolean")
+  }
+  for (const key of PACKAGE_RESOURCE_KEYS) {
+    const filter = value[key]
+    if (
+      filter !== undefined &&
+      (!Array.isArray(filter) ||
+        !filter.every((item) => typeof item === "string"))
+    ) {
+      throw new Error(`package object ${key} must be an array of strings`)
+    }
+  }
+  return entry as ValidPackageSource
+}
+
+function isLocalPackageSource(source: string): boolean {
+  const trimmed = source.trim()
+  return !["npm:", "git:", "github:", "http:", "https:", "ssh:"].some(
+    (prefix) => trimmed.startsWith(prefix),
+  )
+}
+
+function resolveLocalPath(
+  source: string,
+  sourceDir: string,
+  destDir: string,
+): { path: string; resolved: string; isVimMode: boolean } {
+  const sourceIsVimMode = hasVimModeMarker(source)
+  let expanded = source
+  if (source.startsWith("file://")) expanded = fileURLToPath(source)
+  else if (source === "~") expanded = os.homedir()
+  else if (source.startsWith("~/"))
+    expanded = path.join(os.homedir(), source.slice(2))
+
+  const wasRelative = !path.isAbsolute(expanded)
+  const resolved = wasRelative
+    ? path.resolve(sourceDir, expanded)
+    : path.resolve(expanded)
+  let canonical = resolved
+  try {
+    canonical = fs.realpathSync(resolved)
+  } catch {
+    // Missing local sources retain their resolved path and Pi reports them later.
+  }
+  const normalized = wasRelative
+    ? path.relative(destDir, canonical) || "."
+    : canonical
+  return {
+    path: normalized,
+    resolved,
+    isVimMode: sourceIsVimMode || hasVimModeMarker(canonical),
+  }
+}
+
+function normalizeLocalPath(
+  source: string,
+  sourceDir: string,
+  destDir: string,
+): string | null {
+  const normalized = resolveLocalPath(source, sourceDir, destDir)
+  return normalized.isVimMode ? null : normalized.path
+}
+
+function normalizePackageSources(
+  packages: ValidPackageSource[],
+  sourceDir: string,
+  destDir: string,
+): ValidPackageSource[] {
+  return packages.flatMap((entry) => {
+    const source = typeof entry === "string" ? entry : entry.source
+    if (!isLocalPackageSource(source)) {
+      return hasVimModeMarker(source) ? [] : [entry]
+    }
+    const normalized = normalizeLocalPath(source, sourceDir, destDir)
+    if (normalized === null) return []
+    return [
+      typeof entry === "string" ? normalized : { ...entry, source: normalized },
+    ]
+  })
+}
+
+function normalizeExtensionSources(
+  extensions: string[],
+  sourceDir: string,
+  destDir: string,
+): string[] {
+  const sourceExtensions = path.resolve(sourceDir, "extensions")
+  return extensions.flatMap((extension) => {
+    const first = extension[0]
+    const operator =
+      first === "!" || first === "+" || first === "-" ? first : ""
+    const target = operator ? extension.slice(1) : extension
+    const normalized = resolveLocalPath(target, sourceDir, destDir)
+    if (normalized.isVimMode && operator !== "!" && operator !== "-") return []
+    const extensionRelative = path.relative(
+      sourceExtensions,
+      normalized.resolved,
+    )
+    const isMirrored =
+      extensionRelative === "" ||
+      (!extensionRelative.startsWith(`..${path.sep}`) &&
+        extensionRelative !== ".." &&
+        !path.isAbsolute(extensionRelative))
+    const rebased = isMirrored
+      ? path.join("extensions", extensionRelative)
+      : normalized.path
+    return [`${operator}${rebased.split(path.sep).join("/")}`]
+  })
+}
+
 export function defaultSourceAgentDir(): string {
   return (
     process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent")
@@ -53,8 +293,7 @@ export function defaultSourceAgentDir(): string {
 }
 
 export function defaultRoleAgentDir(): string {
-  const home = process.env.HOME || process.env.USERPROFILE || os.homedir()
-  return path.join(home, ".config", "apnea", "pi-role-agent")
+  return path.join(os.homedir(), ".config", "apnea", "pi-role-agent")
 }
 
 function symlinkOrCopy(src: string, dest: string): void {
@@ -86,8 +325,9 @@ function symlinkOrCopy(src: string, dest: string): void {
 
 /**
  * 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
+ * - settings.json: user's packages/extensions minus pi-vimmode; piVimMode stripped
+ * - extensions: safe entries linked individually from the real agent dir
+ * - auth/npm/skills/themes/models: linked from the real agent dir
  *
  * Idempotent. Safe to call on every dispatch.
  */
@@ -97,36 +337,100 @@ export function materializePiRoleAgentDir(opts?: {
 }): string {
   const source = opts?.sourceAgentDir ?? defaultSourceAgentDir()
   const dest = opts?.destDir ?? defaultRoleAgentDir()
+
+  if (safeIsSymlink(dest)) {
+    throw new Error("destination Pi agent directory must not be a symlink")
+  }
+  if (safeIsSymlink(source)) {
+    const target = path.resolve(path.dirname(source), fs.readlinkSync(source))
+    const expected = path.resolve(dest)
+    if (
+      process.platform === "win32"
+        ? target.toLowerCase() === expected.toLowerCase()
+        : target === expected
+    ) {
+      throw new Error("source and destination Pi agent directories must differ")
+    }
+  }
+  if (path.resolve(source) === path.resolve(dest)) {
+    throw new Error("source and destination Pi agent directories must differ")
+  }
+  if (fs.existsSync(source) && fs.existsSync(dest)) {
+    if (fs.realpathSync(source) === fs.realpathSync(dest)) {
+      throw new Error("source and destination Pi agent directories must differ")
+    }
+  }
+
   fs.mkdirSync(dest, { recursive: true })
+  if (
+    fs.existsSync(source) &&
+    fs.realpathSync(source) === fs.realpathSync(dest)
+  ) {
+    throw new Error("source and destination Pi agent directories must differ")
+  }
+
+  const destSettingsPath = path.join(dest, "settings.json")
+  if (safeIsSymlink(destSettingsPath)) {
+    throw new Error("destination Pi settings must not be a symlink")
+  }
 
   const srcSettingsPath = path.join(source, "settings.json")
   let settings: Record<string, unknown> = {}
-  if (fs.existsSync(srcSettingsPath)) {
+  if (fs.existsSync(srcSettingsPath) || safeIsSymlink(srcSettingsPath)) {
     try {
       const raw = JSON.parse(fs.readFileSync(srcSettingsPath, "utf8"))
-      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-        settings = { ...(raw as Record<string, unknown>) }
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("settings root must be an object")
       }
-    } catch {
-      settings = {}
+      settings = { ...(raw as Record<string, unknown>) }
+      if ("packages" in settings && !Array.isArray(settings.packages)) {
+        throw new Error("packages must be an array")
+      }
+      if (Array.isArray(settings.packages)) {
+        settings.packages = settings.packages.map(validatePackageSource)
+      }
+      if (
+        "extensions" in settings &&
+        (!Array.isArray(settings.extensions) ||
+          !settings.extensions.every(
+            (extension) =>
+              typeof extension === "string" && extension.trim() !== "",
+          ))
+      ) {
+        throw new Error("extensions must be an array of strings")
+      }
+    } catch (error) {
+      throw new Error(
+        `invalid source Pi settings at ${srcSettingsPath}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      )
     }
   }
 
-  settings.packages = filterPackagesNoVim(settings.packages)
+  const packages = Array.isArray(settings.packages)
+    ? (settings.packages as ValidPackageSource[])
+    : []
+  const extensions = Array.isArray(settings.extensions)
+    ? (settings.extensions as string[])
+    : []
+  settings.packages = normalizePackageSources(packages, source, dest)
+  settings.extensions = normalizeExtensionSources(extensions, source, dest)
   delete settings.piVimMode
 
-  fs.writeFileSync(
-    path.join(dest, "settings.json"),
+  writeSettingsAtomically(
+    dest,
+    destSettingsPath,
     `${JSON.stringify(settings, null, 2)}\n`,
-    "utf8",
   )
 
+  const destExtensions = path.join(dest, "extensions")
+  materializeExtensionsNoVim(path.join(source, "extensions"), destExtensions)
+
   // Reuse identity + installed packages; keep sessions local to role dir.
   for (const name of [
     "auth.json",
     "npm",
     "skills",
-    "extensions",
     "themes",
     "models.json",
     "bin",
@@ -148,6 +452,71 @@ export function materializePiRoleAgentDir(opts?: {
   return dest
 }
 
+function materializeExtensionsNoVim(sourceDir: string, destDir: string): void {
+  fs.rmSync(destDir, { recursive: true, force: true })
+  if (!fs.existsSync(sourceDir)) return
+  if (extensionPathHasVimModeMarker(sourceDir)) return
+
+  fs.mkdirSync(destDir, { recursive: true })
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourceEntry = path.join(sourceDir, entry.name)
+    if (extensionPathHasVimModeMarker(sourceEntry)) continue
+    symlinkOrCopy(sourceEntry, path.join(destDir, entry.name))
+  }
+}
+
+function extensionPathHasVimModeMarker(entryPath: string): boolean {
+  if (hasVimModeMarker(entryPath)) return true
+  try {
+    return hasVimModeMarker(fs.realpathSync(entryPath))
+  } catch {
+    return true
+  }
+}
+
+type DirectorySyncIo = Pick<typeof fs, "openSync" | "fsyncSync" | "closeSync">
+
+export function syncDirectoryAfterRename(
+  destDir: string,
+  platform: NodeJS.Platform = process.platform,
+  io: DirectorySyncIo = fs,
+): void {
+  if (platform === "win32") return
+  const directory = io.openSync(destDir, fs.constants.O_RDONLY)
+  try {
+    io.fsyncSync(directory)
+  } finally {
+    io.closeSync(directory)
+  }
+}
+
+function writeSettingsAtomically(
+  destDir: string,
+  settingsPath: string,
+  contents: string,
+): void {
+  const temporaryPath = path.join(
+    destDir,
+    `.settings.json.${process.pid}.${randomUUID()}.tmp`,
+  )
+  let file: number | undefined
+  try {
+    // Bun 1.3.7 misinterprets Node's numeric O_CREAT flags on Windows.
+    // Exclusive creation also refuses an existing symlink at this random leaf.
+    file = fs.openSync(temporaryPath, "wx", 0o600)
+    fs.writeFileSync(file, contents, "utf8")
+    fs.fsyncSync(file)
+    fs.closeSync(file)
+    file = undefined
+    fs.renameSync(temporaryPath, settingsPath)
+
+    syncDirectoryAfterRename(destDir)
+  } finally {
+    if (file !== undefined) fs.closeSync(file)
+    fs.rmSync(temporaryPath, { force: true })
+  }
+}
+
 function safeIsSymlink(p: string): boolean {
   try {
     return fs.lstatSync(p).isSymbolicLink()
@@ -165,7 +534,16 @@ export function wrapInteractiveCmdNoVim(
   cmd: string[],
   opts?: { sourceAgentDir?: string; destDir?: string },
 ): string[] {
-  if (!isPiCmd(cmd)) return cmd
+  const piIndex = piCommandIndex(cmd)
+  if (piIndex === null) return cmd
   const agentDir = materializePiRoleAgentDir(opts)
+  if (path.basename(cmd[0]!) === "env") {
+    return [
+      "env",
+      ...cmd.slice(1, piIndex),
+      `PI_CODING_AGENT_DIR=${agentDir}`,
+      ...cmd.slice(piIndex),
+    ]
+  }
   return ["env", `PI_CODING_AGENT_DIR=${agentDir}`, ...cmd]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naxodev/pi-apnea",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pi adapter for the Apnea multi-role workflow",
   "license": "MIT",
   "author": "Nacho Vazquez",
@@ -66,7 +66,7 @@
     "@earendil-works/pi-coding-agent": ">=0.83.0 <0.85.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.84.2",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.2",
     "prettier": "^3.9.0",

package/skills/apnea-orchestrator/SKILL.md

@@ -44,11 +44,11 @@ Never: `apnea reset-rounds` / `/apnea reset-rounds` (human only - it is not a mo
 start
   → dispatch plan → wait
   → dispatch plan_review → wait
-      CHANGES_REQUIRED → dispatch plan (rework=true) → wait → plan_review …
+      CHANGES_REQUIRED → dispatch plan → wait → plan_review …
       APPROVED → dispatch phase_package → wait
   → dispatch code → wait
   → dispatch code_review → wait
-      CHANGES_REQUIRED → dispatch code (rework=true) → wait → code_review …
+      CHANGES_REQUIRED → dispatch code → wait → code_review …
       APPROVED → workflow_commit_phase
   → more phases? → phase_package …
   → else → dispatch pr_description → wait → done
@@ -56,6 +56,8 @@ start
 
 Follow `@naxodev/apnea/briefs/orchestrator.md` and `@naxodev/apnea/docs/protocol/overview.md`.
 
+Do not pass `rework` to authorize a new round. `workflow_wait` records the required target in state, and the matching dispatch consumes it. The 0.2.x flag grants authority only for ambiguous version-1 plan or code migration.
+
 ## When Pi tools are absent
 
 Run the `apnea` CLI instead — same loop, same refusals (see the table above). Any shell that
@@ -80,6 +82,6 @@ Do **not** stop at the first timeout. Investigate and fix:
 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).
+5. Pane dead → `dispatch_role` same kind with `redeliver=true` (not rework). A live or ambiguous pane must refuse redelivery.
 
 Escalate only after two failed recovery attempts, or on round cap / dirty reviewer tree / illegal step / VCS confusion.