@naxodev/apnea 0.2.0 → 0.2.2

package/extension/services/herdr.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process"
 import * as fs from "node:fs"
 import * as path from "node:path"
 import { Clock, Context, Effect, Layer, Option, Result } from "effect"
@@ -6,14 +5,28 @@ import { shellJoin } from "../domain/herdr.ts"
 import { HerdrError } from "../errors.ts"
 import type { ApneaHostAdapter } from "../host-adapter.ts"
 import { neutralHostAdapter } from "../host-adapter.ts"
+import {
+  Process,
+  ProcessCancelledError,
+  ProcessExitError,
+  ProcessTimeoutError,
+  type ProcessError,
+  type ProcessService,
+} from "./process.ts"
 
 export type PaneInfo = {
   ok: boolean
+  /** True only when Herdr explicitly reports that this pane does not exist. */
+  missing?: boolean
   agent_status?: string
   label?: string
   agent?: string
 }
 export type RolePaneRef = { pane_id: string; label: string }
+/** Persist pane ownership before any task prompt can reach the pane. */
+export type BeforeInteractiveDelivery = (
+  pane: RolePaneRef,
+) => Effect.Effect<void, HerdrError>
 export type HerdrAvailability = "available" | "unavailable"
 export type InteractiveLaunch = {
   pane_id: string
@@ -28,7 +41,7 @@ export interface HerdrService {
   readonly enabled: Effect.Effect<boolean>
   /** Dispatch preflight that distinguishes a stale pane from CLI failures. */
   readonly availability: Effect.Effect<HerdrAvailability, HerdrError>
-  readonly paneGet: (paneId: string) => Effect.Effect<PaneInfo>
+  readonly paneGet: (paneId: string) => Effect.Effect<PaneInfo, HerdrError>
   readonly paneRun: (
     paneId: string,
     command: string,
@@ -42,6 +55,8 @@ export interface HerdrService {
     interactiveCmd: string[],
     prompt: string,
     prefer: RolePaneRef | null,
+    beforeDelivery?: BeforeInteractiveDelivery,
+    onAcquisitionFailure?: () => Effect.Effect<void>,
   ) => Effect.Effect<InteractiveLaunch, HerdrError>
 }
 
@@ -61,22 +76,67 @@ export const paneReadRecentArgs = (paneId: string): string[] => [
   "text",
 ]
 
-function herdrCli(args: string[]): { ok: boolean; json: unknown; raw: string } {
-  const r = spawnSync("herdr", args, {
-    encoding: "utf8",
-    maxBuffer: 10 * 1024 * 1024,
+const HERDR_QUERY_TIMEOUT_MS = 10_000
+const HERDR_MUTATION_TIMEOUT_MS = 30_000
+const HERDR_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024
+
+type HerdrCliResult = { ok: boolean; json: unknown; raw: string }
+
+function processRaw(error: ProcessError): string {
+  return "stdout" in error ? `${error.stdout}${error.stderr}` : error.message
+}
+
+export function herdrCli(
+  processService: ProcessService,
+  args: string[],
+  options: { mutation?: boolean; timeoutMs?: number } = {},
+): Effect.Effect<HerdrCliResult, HerdrError> {
+  const command = shellJoin(["herdr", ...args])
+  return Effect.gen(function* () {
+    const result = yield* Effect.result(
+      processService.run({
+        command: "herdr",
+        args,
+        timeoutMs: options.timeoutMs ?? HERDR_QUERY_TIMEOUT_MS,
+        outputLimitBytes: HERDR_OUTPUT_LIMIT_BYTES,
+      }),
+    )
+    if (Result.isFailure(result)) {
+      const error = result.failure
+      const raw = processRaw(error)
+      if (error instanceof ProcessExitError) {
+        return { ok: false, json: null, raw }
+      }
+      const deliveryUnknown =
+        options.mutation &&
+        (error instanceof ProcessTimeoutError ||
+          error instanceof ProcessCancelledError)
+      return yield* new HerdrError({
+        message: `${command} failed: ${error.message}${raw ? `: ${raw.trim()}` : ""}`,
+        command,
+        details: {
+          ...(deliveryUnknown ? { delivery: "unknown" } : {}),
+          process_error: error._tag,
+        },
+      })
+    }
+    const raw = `${result.success.stdout}${result.success.stderr}`
+    const line = result.success.stdout.trim().split(/\n/).filter(Boolean).pop()
+    if (!line) {
+      return yield* new HerdrError({
+        message: `${command} returned no JSON output`,
+        command,
+      })
+    }
+    try {
+      return { ok: true, json: JSON.parse(line), raw }
+    } catch {
+      return yield* new HerdrError({
+        message: `${command} returned malformed JSON: ${raw.trim() || "empty output"}`,
+        command,
+      })
+    }
   })
-  const raw = `${r.stdout ?? ""}${r.stderr ?? ""}`
-  if (r.status !== 0) {
-    return { ok: false, json: null, raw }
-  }
-  // herdr often prints one JSON object
-  const line = (r.stdout ?? "").trim().split(/\n/).filter(Boolean).pop() ?? ""
-  try {
-    return { ok: true, json: JSON.parse(line), raw }
-  } catch {
-    return { ok: true, json: null, raw }
-  }
 }
 
 function resultOf(json: unknown): Record<string, unknown> | null {
@@ -137,98 +197,157 @@ export function probeHerdrAvailability(
   })
 }
 
-function herdrAvailabilitySync(): HerdrAvailability {
-  return probeHerdrAvailability(
-    {
-      HERDR_ENV: process.env.HERDR_ENV,
-      HERDR_PANE_ID: process.env.HERDR_PANE_ID,
-    },
-    (paneId) => herdrCli(["pane", "get", paneId]),
-  )
-}
-
-function paneGetSync(paneId: string): PaneInfo {
-  const r = herdrCli(["pane", "get", paneId])
-  if (!r.ok) return { ok: false }
-  const res = resultOf(r.json)
-  const pane = (res?.pane as Record<string, unknown>) ?? {}
-  return {
-    ok: true,
-    agent_status: pane.agent_status ? String(pane.agent_status) : undefined,
-    label: pane.label ? String(pane.label) : undefined,
-    agent: pane.agent ? String(pane.agent) : undefined,
+function herdrAvailability(
+  processService: ProcessService,
+): Effect.Effect<HerdrAvailability, HerdrError> {
+  if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_PANE_ID) {
+    return Effect.succeed("unavailable")
   }
+  const current = process.env.HERDR_PANE_ID
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(processService, ["pane", "get", current])
+    if (r.ok) return "available"
+    if (/pane_not_found|pane not found/i.test(r.raw)) return "unavailable"
+    return yield* new HerdrError({
+      message: `failed to verify current Herdr pane ${current}: ${r.raw.trim() || "unknown herdr error"}`,
+      command: "herdr pane get",
+    })
+  })
 }
 
-function paneAliveSync(paneId: string): boolean {
-  return paneGetSync(paneId).ok
+export function paneGet(
+  processService: ProcessService,
+  paneId: string,
+): Effect.Effect<PaneInfo, HerdrError> {
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(processService, ["pane", "get", paneId])
+    if (!r.ok) {
+      return {
+        ok: false,
+        missing: /pane_not_found|pane not found/i.test(r.raw),
+      }
+    }
+    const res = resultOf(r.json)
+    if (!res?.pane || typeof res.pane !== "object") {
+      return yield* new HerdrError({
+        message: `herdr pane get returned no pane for ${paneId}`,
+        command: "herdr pane get",
+      })
+    }
+    const pane = res.pane as Record<string, unknown>
+    return {
+      ok: true,
+      agent_status: pane.agent_status ? String(pane.agent_status) : undefined,
+      label: pane.label ? String(pane.label) : undefined,
+      agent: pane.agent ? String(pane.agent) : undefined,
+    }
+  })
 }
 
-function paneReadRecentSync(paneId: string): string {
+function paneReadRecent(
+  processService: ProcessService,
+  paneId: string,
+): Effect.Effect<string, HerdrError> {
   const args = paneReadRecentArgs(paneId)
-  const r = spawnSync("herdr", args, {
-    encoding: "utf8",
-    maxBuffer: 10 * 1024 * 1024,
+  return Effect.gen(function* () {
+    const r = yield* Effect.result(
+      processService.run({
+        command: "herdr",
+        args,
+        timeoutMs: HERDR_QUERY_TIMEOUT_MS,
+        outputLimitBytes: HERDR_OUTPUT_LIMIT_BYTES,
+      }),
+    )
+    if (Result.isFailure(r)) {
+      const output = processRaw(r.failure)
+        .trim()
+        .split(/\r?\n/)
+        .slice(-80)
+        .join("\n")
+      throw new HerdrError({
+        message: `herdr pane read failed for ${paneId}${output ? `: ${output}` : ""}`,
+        command: shellJoin(["herdr", ...args]),
+        ...(output ? { details: { output } } : {}),
+      })
+    }
+    return r.success.stdout
   })
-  if (r.status !== 0 || r.error) {
-    const output = `${r.stdout ?? ""}${r.stderr ?? ""}${r.error?.message ?? ""}`
-      .trim()
-      .split(/\r?\n/)
-      .slice(-80)
-      .join("\n")
-    throw new HerdrError({
-      message: `herdr pane read failed for ${paneId}${output ? `: ${output}` : ""}`,
-      command: shellJoin(["herdr", ...args]),
-      ...(output ? { details: { output } } : {}),
-    })
-  }
-  return r.stdout ?? ""
 }
 
 /** Prefer right on wide panes, down on tall/narrow ones. */
-function splitDirectionSync(): "right" | "down" {
+function splitDirection(
+  processService: ProcessService,
+): Effect.Effect<"right" | "down", HerdrError> {
   const current = process.env.HERDR_PANE_ID
-  if (!current) return "right"
-  const r = herdrCli(["pane", "layout", "--pane", current])
-  const res = resultOf(r.json)
-  const layout = res?.layout as Record<string, unknown> | undefined
-  const panes = (layout?.panes as Array<Record<string, unknown>>) ?? []
-  const me = panes.find((p) => String(p.pane_id) === current)
-  const rect = me?.rect as { width?: number; height?: number } | undefined
-  if (rect?.width != null && rect?.height != null) {
-    return rect.width >= rect.height ? "right" : "down"
-  }
-  return "right"
+  if (!current) return Effect.succeed("right")
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(processService, [
+      "pane",
+      "layout",
+      "--pane",
+      current,
+    ])
+    const res = resultOf(r.json)
+    const layout = res?.layout as Record<string, unknown> | undefined
+    if (!Array.isArray(layout?.panes)) {
+      return yield* new HerdrError({
+        message: "herdr pane layout returned no panes",
+        command: "herdr pane layout",
+      })
+    }
+    const panes = layout.panes as Array<Record<string, unknown>>
+    const me = panes.find((p) => String(p.pane_id) === current)
+    const rect = me?.rect as { width?: number; height?: number } | undefined
+    if (rect?.width != null && rect?.height != null) {
+      return rect.width >= rect.height ? "right" : "down"
+    }
+    return "right"
+  })
 }
 
-function splitPaneSync(): string {
-  const direction = splitDirectionSync()
-  const r = herdrCli([
-    "pane",
-    "split",
-    "--current",
-    "--direction",
-    direction,
-    "--no-focus",
-  ])
-  if (!r.ok)
-    throw new HerdrError({ message: `herdr pane split failed: ${r.raw}` })
-  const res = resultOf(r.json)
-  const pane = res?.pane as Record<string, unknown> | undefined
-  const id = pane?.pane_id ? String(pane.pane_id) : null
-  if (!id) {
-    throw new HerdrError({
-      message: `herdr pane split: no pane_id in ${r.raw}`,
-    })
-  }
-  return id
+function splitPane(
+  processService: ProcessService,
+): Effect.Effect<string, HerdrError> {
+  return Effect.gen(function* () {
+    const direction = yield* splitDirection(processService)
+    const r = yield* herdrCli(
+      processService,
+      ["pane", "split", "--current", "--direction", direction, "--no-focus"],
+      { mutation: true },
+    )
+    if (!r.ok)
+      return yield* new HerdrError({
+        message: `herdr pane split failed: ${r.raw}`,
+      })
+    const res = resultOf(r.json)
+    const pane = res?.pane as Record<string, unknown> | undefined
+    const id = pane?.pane_id ? String(pane.pane_id) : null
+    if (!id) {
+      return yield* new HerdrError({
+        message: `herdr pane split: no pane_id in ${r.raw}`,
+      })
+    }
+    return id
+  })
 }
 
-function renamePaneSync(paneId: string, label: string): void {
-  const r = herdrCli(["pane", "rename", paneId, label])
-  if (!r.ok) {
-    throw new HerdrError({ message: `herdr pane rename failed: ${r.raw}` })
-  }
+function renamePane(
+  processService: ProcessService,
+  paneId: string,
+  label: string,
+): Effect.Effect<void, HerdrError> {
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(
+      processService,
+      ["pane", "rename", paneId, label],
+      { mutation: true },
+    )
+    if (!r.ok) {
+      return yield* new HerdrError({
+        message: `herdr pane rename failed: ${r.raw}`,
+      })
+    }
+  })
 }
 
 /**
@@ -236,85 +355,97 @@ function renamePaneSync(paneId: string, label: string): void {
  * When a live agent TUI is focused, this submits a prompt (not a shell command).
  * When the pane is a bare shell, this runs a shell line.
  */
-function paneRunSync(paneId: string, command: string): void {
-  const r = herdrCli(["pane", "run", paneId, command])
-  if (!r.ok) {
-    throw new HerdrError({
-      message: `herdr pane run failed: ${r.raw}`,
-      command: "herdr pane run",
-    })
-  }
+function paneRun(
+  processService: ProcessService,
+  paneId: string,
+  command: string,
+): Effect.Effect<void, HerdrError> {
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(
+      processService,
+      ["pane", "run", paneId, command],
+      { mutation: true },
+    )
+    if (!r.ok) {
+      return yield* new HerdrError({
+        message: `herdr pane run failed: ${r.raw}`,
+        command: "herdr pane run",
+      })
+    }
+  })
 }
 
 /** Send raw key names (e.g. Escape, Enter) into a pane. */
-function paneSendKeysSync(paneId: string, keys: string[]): void {
-  if (keys.length === 0) return
-  const r = herdrCli(["pane", "send-keys", paneId, ...keys])
-  if (!r.ok) {
-    throw new HerdrError({ message: `herdr pane send-keys failed: ${r.raw}` })
-  }
+function paneSendKeys(
+  processService: ProcessService,
+  paneId: string,
+  keys: string[],
+): Effect.Effect<void, HerdrError> {
+  if (keys.length === 0) return Effect.void
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(
+      processService,
+      ["pane", "send-keys", paneId, ...keys],
+      { mutation: true },
+    )
+    if (!r.ok) {
+      return yield* new HerdrError({
+        message: `herdr pane send-keys failed: ${r.raw}`,
+      })
+    }
+  })
 }
 
-function paneForegroundNamesSync(paneId: string): string[] {
-  try {
-    const r = spawnSync("herdr", ["pane", "process-info", "--pane", paneId], {
-      encoding: "utf8",
-      maxBuffer: 2 * 1024 * 1024,
-    })
-    if (r.status !== 0) return []
-    const line = (r.stdout ?? "").trim().split(/\n/).filter(Boolean).pop() ?? ""
-    const json = JSON.parse(line) as {
-      result?: {
-        process_info?: {
-          foreground_processes?: Array<{
-            name?: string
-            argv0?: string
-            cmdline?: string
-          }>
-        }
-      }
+function paneForegroundNames(
+  processService: ProcessService,
+  paneId: string,
+): Effect.Effect<string[]> {
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(processService, [
+      "pane",
+      "process-info",
+      "--pane",
+      paneId,
+    ])
+    const res = resultOf(r.json)
+    const processInfo = res?.process_info as Record<string, unknown> | undefined
+    if (!Array.isArray(processInfo?.foreground_processes)) {
+      return yield* new HerdrError({
+        message: "herdr pane process-info returned no foreground_processes",
+        command: "herdr pane process-info",
+      })
     }
-    const procs = json.result?.process_info?.foreground_processes ?? []
+    const procs = processInfo.foreground_processes as Array<{
+      name?: string
+      argv0?: string
+      cmdline?: string
+    }>
     return procs.map((p) => p.cmdline || p.argv0 || p.name || "?")
-  } catch {
-    return []
-  }
+  }).pipe(Effect.catch(() => Effect.succeed([])))
 }
 
-function toHerdrError(e: unknown): HerdrError {
-  return e instanceof HerdrError
-    ? e
-    : new HerdrError({ message: e instanceof Error ? e.message : String(e) })
+function toHerdrError(error: unknown): HerdrError {
+  return error instanceof HerdrError
+    ? error
+    : new HerdrError({
+        message: error instanceof Error ? error.message : String(error),
+      })
 }
 
-/**
- * Effect wrappers for the throwing `*Sync` helpers. A `throw` inside
- * `Effect.gen` is a defect, and defects pass straight through `Effect.ignore` /
- * `Effect.option` — so every sync herdr call must go through `Effect.try` for
- * best-effort recovery blocks to actually be best-effort.
- */
-function paneRun(
+function paneClose(
+  processService: ProcessService,
   paneId: string,
-  command: string,
 ): Effect.Effect<void, HerdrError> {
-  return Effect.try({
-    try: () => paneRunSync(paneId, command),
-    catch: toHerdrError,
-  })
-}
-
-function paneClose(paneId: string): Effect.Effect<void, HerdrError> {
-  return Effect.try({
-    try: () => {
-      const r = herdrCli(["pane", "close", paneId])
-      if (!r.ok) {
-        throw new HerdrError({
-          message: `herdr pane close failed: ${r.raw}`,
-          command: "herdr pane close",
-        })
-      }
-    },
-    catch: toHerdrError,
+  return Effect.gen(function* () {
+    const r = yield* herdrCli(processService, ["pane", "close", paneId], {
+      mutation: true,
+    })
+    if (!r.ok) {
+      return yield* new HerdrError({
+        message: `herdr pane close failed: ${r.raw}`,
+        command: "herdr pane close",
+      })
+    }
   })
 }
 
@@ -333,7 +464,7 @@ function withLaunchDetails(
 export function cleanupFailedInteractiveLaunch(
   error: HerdrError,
   paneId: string,
-  close: (paneId: string) => Effect.Effect<void, HerdrError> = paneClose,
+  close: (paneId: string) => Effect.Effect<void, HerdrError>,
 ): Effect.Effect<never, HerdrError> {
   return Effect.gen(function* () {
     const cleanup = yield* Effect.result(close(paneId))
@@ -349,16 +480,6 @@ export function cleanupFailedInteractiveLaunch(
   })
 }
 
-function sendKeys(
-  paneId: string,
-  keys: string[],
-): Effect.Effect<void, HerdrError> {
-  return Effect.try({
-    try: () => paneSendKeysSync(paneId, keys),
-    catch: toHerdrError,
-  })
-}
-
 /** Unique label for a role slot (stable for the run when we reuse the pane). */
 function roleLabel(role: string, millis: number): string {
   const id = `${millis.toString(36)}-${Math.random().toString(36).slice(2, 6)}`
@@ -370,23 +491,28 @@ function roleLabel(role: string, millis: number): string {
  * Uses herdr wait when available; falls back to poll.
  */
 function waitAgentReady(
+  processService: ProcessService,
   paneId: string,
   timeoutMs = 90_000,
-): Effect.Effect<string | undefined> {
+): Effect.Effect<string | undefined, HerdrError> {
   return Effect.gen(function* () {
     // Prefer Herdr's blocking wait (does not freeze our caller if we use it
     // only for short readiness; dispatch is already a tool call).
-    const r = herdrCli([
-      "wait",
-      "agent-status",
-      paneId,
-      "--status",
-      "idle",
-      "--timeout",
-      String(timeoutMs),
-    ])
+    const r = yield* herdrCli(
+      processService,
+      [
+        "wait",
+        "agent-status",
+        paneId,
+        "--status",
+        "idle",
+        "--timeout",
+        String(timeoutMs),
+      ],
+      { timeoutMs: timeoutMs + 5_000 },
+    )
     if (r.ok) {
-      const s = paneGetSync(paneId).agent_status
+      const s = (yield* paneGet(processService, paneId)).agent_status
       if (s === "idle" || s === "done") return s
     }
     // fall back: poll (done also counts as ready). Clock, not Date.now(): the
@@ -395,32 +521,34 @@ function waitAgentReady(
     const deadline =
       (yield* Clock.currentTimeMillis) + Math.min(timeoutMs, 30_000)
     while ((yield* Clock.currentTimeMillis) < deadline) {
-      const s = paneGetSync(paneId).agent_status
+      const s = (yield* paneGet(processService, paneId)).agent_status
       if (s === "idle" || s === "done") return s
       yield* Effect.sleep(500)
     }
-    return paneGetSync(paneId).agent_status
+    return (yield* paneGet(processService, paneId)).agent_status
   })
 }
 
 /**
  * The three pane operations the recovery ladder drives.
  *
- * Injectable because the ladder cannot otherwise be tested: Bun's `spawnSync`
- * resolves binaries against the process's real PATH and ignores mutations to
- * `process.env.PATH`, so a fake `herdr` placed on a temp PATH is never invoked.
+ * Injectable so the recovery ladder can be tested without a Herdr process.
  */
 export type PromptProbes = {
-  readonly status: () => string | undefined
+  readonly status: () => Effect.Effect<string | undefined, HerdrError>
   readonly sendKeys: (keys: string[]) => Effect.Effect<void, HerdrError>
   readonly run: (text: string) => Effect.Effect<void, HerdrError>
 }
 
-function livePromptProbes(paneId: string): PromptProbes {
+function livePromptProbes(
+  processService: ProcessService,
+  paneId: string,
+): PromptProbes {
   return {
-    status: () => paneGetSync(paneId).agent_status,
-    sendKeys: (keys) => sendKeys(paneId, keys),
-    run: (text) => paneRun(paneId, text),
+    status: () =>
+      Effect.map(paneGet(processService, paneId), (info) => info.agent_status),
+    sendKeys: (keys) => paneSendKeys(processService, paneId, keys),
+    run: (text) => paneRun(processService, paneId, text),
   }
 }
 
@@ -437,27 +565,42 @@ export function ensurePromptSubmitted(
     settleMs?: number
     workingWaitMs?: number
     probes?: PromptProbes
+    processService?: ProcessService
   },
-): Effect.Effect<{
-  accepted: boolean
-  attempts: number
-  last_status?: string
-}> {
+): Effect.Effect<
+  {
+    accepted: boolean
+    attempts: number
+    last_status?: string
+  },
+  HerdrError
+> {
   return Effect.gen(function* () {
-    const probes = opts?.probes ?? livePromptProbes(paneId)
+    const probes =
+      opts?.probes ??
+      (opts?.processService
+        ? livePromptProbes(opts.processService, paneId)
+        : undefined)
+    if (!probes) {
+      return yield* new HerdrError({
+        message: "prompt probes or process service are required",
+      })
+    }
     const settleMs = opts?.settleMs ?? 2500
     const workingWaitMs = opts?.workingWaitMs ?? 12_000
     let attempts = 1
 
-    const waitForWorking = (ms: number): Effect.Effect<string | undefined> =>
+    const waitForWorking = (
+      ms: number,
+    ): Effect.Effect<string | undefined, HerdrError> =>
       Effect.gen(function* () {
         const deadline = (yield* Clock.currentTimeMillis) + ms
         while ((yield* Clock.currentTimeMillis) < deadline) {
-          const s = probes.status()
+          const s = yield* probes.status()
           if (s === "working" || s === "blocked") return s
           yield* Effect.sleep(400)
         }
-        return probes.status()
+        return yield* probes.status()
       })
 
     // Give the first paneRun a moment to flip status.
@@ -498,7 +641,7 @@ export function ensurePromptSubmitted(
       return {
         accepted: false,
         attempts,
-        last_status: probes.status(),
+        last_status: yield* probes.status(),
       }
     }
     yield* Effect.sleep(settleMs)
@@ -519,12 +662,15 @@ export function ensurePromptSubmitted(
  * Never claims an unrelated pane by scanning labels alone.
  */
 function acquireRolePane(
+  processService: ProcessService,
   role: string,
   hostAdapter: ApneaHostAdapter,
   opts?: {
     prefer?: RolePaneRef | null
     /** Launch interactive harness only when creating a new pane */
     interactiveCmd?: string[]
+    beforeDelivery?: BeforeInteractiveDelivery
+    onAcquisitionFailure?: () => Effect.Effect<void>
   },
 ): Effect.Effect<RolePaneRef & { reused: boolean }, HerdrError> {
   return Effect.gen(function* () {
@@ -534,7 +680,13 @@ function acquireRolePane(
       })
     }
 
-    if (opts?.prefer?.pane_id && paneAliveSync(opts.prefer.pane_id)) {
+    if (
+      opts?.prefer?.pane_id &&
+      (yield* paneGet(processService, opts.prefer.pane_id)).ok
+    ) {
+      if (opts.beforeDelivery) {
+        yield* Effect.uninterruptible(opts.beforeDelivery(opts.prefer))
+      }
       return {
         pane_id: opts.prefer.pane_id,
         label: opts.prefer.label,
@@ -544,25 +696,44 @@ function acquireRolePane(
 
     const millis = yield* Clock.currentTimeMillis
     const label = roleLabel(role, millis)
-    const split = yield* Effect.result(
-      Effect.try({
-        try: () => splitPaneSync(),
-        catch: toHerdrError,
+    // A split can create a pane before its response arrives. Finish the bounded
+    // acquisition and ownership save before observing cancellation.
+    const paneId = yield* Effect.uninterruptible(
+      Effect.gen(function* () {
+        const split = yield* Effect.result(splitPane(processService))
+        if (Result.isFailure(split)) {
+          // Restore proven non-delivery before a pending interruption can hide
+          // the split failure when this acquisition mask exits.
+          if (split.failure.details?.delivery !== "unknown") {
+            yield* opts?.onAcquisitionFailure?.() ?? Effect.void
+          }
+          return yield* withLaunchDetails(split.failure, {
+            delivery:
+              split.failure.details?.delivery === "unknown"
+                ? "unknown"
+                : "not_delivered",
+            newly_created: false,
+          })
+        }
+        const paneId = split.success
+        if (opts?.beforeDelivery) {
+          const persisted = yield* Effect.result(
+            opts.beforeDelivery({ pane_id: paneId, label }),
+          )
+          if (Result.isFailure(persisted)) {
+            return yield* cleanupFailedInteractiveLaunch(
+              persisted.failure,
+              paneId,
+              (id) => paneClose(processService, id),
+            )
+          }
+        }
+        return paneId
       }),
     )
-    if (Result.isFailure(split)) {
-      return yield* withLaunchDetails(split.failure, {
-        delivery: "not_delivered",
-        newly_created: false,
-      })
-    }
-    const paneId = split.success
     const prepared = yield* Effect.result(
       Effect.gen(function* () {
-        yield* Effect.try({
-          try: () => renamePaneSync(paneId, label),
-          catch: toHerdrError,
-        })
+        yield* renamePane(processService, paneId, label)
         if (!opts?.interactiveCmd?.length) return
         // Launch the interactive harness only (no task argv).
         // Pi roles get PI_CODING_AGENT_DIR without pi-vimmode so pane-run pastes
@@ -576,11 +747,23 @@ function acquireRolePane(
           catch: toHerdrError,
         })
         const cmd = shellJoin(["cd", process.cwd(), "&&", "exec", ...launchCmd])
-        yield* paneRun(paneId, cmd)
+        yield* paneRun(processService, paneId, cmd)
       }),
     )
     if (Result.isFailure(prepared)) {
-      return yield* cleanupFailedInteractiveLaunch(prepared.failure, paneId)
+      if (prepared.failure.details?.delivery === "unknown") {
+        return yield* withLaunchDetails(prepared.failure, {
+          delivery: "unknown",
+          pane_id: paneId,
+          pane_label: label,
+          newly_created: true,
+        })
+      }
+      return yield* cleanupFailedInteractiveLaunch(
+        prepared.failure,
+        paneId,
+        (id) => paneClose(processService, id),
+      )
     }
     return { pane_id: paneId, label, reused: false }
   })
@@ -594,17 +777,20 @@ function acquireRolePane(
  * `claude -p` / `pi -p` dumping shell output.
  */
 function runInteractivePromptImpl(
+  processService: ProcessService,
   hostAdapter: ApneaHostAdapter,
   role: string,
   interactiveCmd: string[],
   prompt: string,
   prefer: RolePaneRef | null,
+  beforeDelivery?: BeforeInteractiveDelivery,
+  onAcquisitionFailure?: () => Effect.Effect<void>,
 ): Effect.Effect<InteractiveLaunch, HerdrError> {
   return Effect.gen(function* () {
     let preferUse: RolePaneRef | null = null
     if (prefer?.pane_id) {
       // One `pane get`: liveness and agent_status come from the same call.
-      const info = paneGetSync(prefer.pane_id)
+      const info = yield* paneGet(processService, prefer.pane_id)
       // reuse only when a live agent can take a new prompt
       // working/blocked/unknown/shell-only → new pane
       if (
@@ -615,38 +801,64 @@ function runInteractivePromptImpl(
       }
     }
 
-    const acquired = yield* acquireRolePane(role, hostAdapter, {
+    const acquired = yield* acquireRolePane(processService, role, hostAdapter, {
       prefer: preferUse,
       interactiveCmd: preferUse ? undefined : interactiveCmd,
+      beforeDelivery,
+      onAcquisitionFailure,
     })
 
-    if (!acquired.reused) {
-      yield* waitAgentReady(acquired.pane_id, 90_000)
-      // still try even if not idle/done — some harnesses accept input
-      // before status settles.
-    } else {
-      const st = paneGetSync(acquired.pane_id).agent_status
-      if (st !== "idle" && st !== "done") {
-        yield* waitAgentReady(acquired.pane_id, 30_000)
-      }
-    }
+    const ready = yield* Effect.result(
+      Effect.gen(function* () {
+        if (!acquired.reused) {
+          yield* waitAgentReady(processService, acquired.pane_id, 90_000)
+          // Some harnesses accept input before status settles.
+        } else {
+          const st = (yield* paneGet(processService, acquired.pane_id))
+            .agent_status
+          if (st !== "idle" && st !== "done") {
+            yield* waitAgentReady(processService, acquired.pane_id, 30_000)
+          }
+        }
 
-    const beforePrompt = hostAdapter.beforeInteractivePrompt?.(interactiveCmd)
-    if (beforePrompt) {
-      // Host preparation is best-effort; command wrapping is the primary guard.
-      yield* Effect.gen(function* () {
-        yield* paneRun(acquired.pane_id, beforePrompt)
-        yield* waitAgentReady(acquired.pane_id, 5_000)
-        yield* Effect.sleep(300)
-      }).pipe(Effect.ignore)
+        const beforePrompt =
+          hostAdapter.beforeInteractivePrompt?.(interactiveCmd)
+        if (beforePrompt) {
+          // Host preparation is best-effort; command wrapping is the primary guard.
+          yield* Effect.gen(function* () {
+            yield* paneRun(processService, acquired.pane_id, beforePrompt)
+            yield* waitAgentReady(processService, acquired.pane_id, 5_000)
+            yield* Effect.sleep(300)
+          }).pipe(Effect.ignore)
+        }
+      }),
+    )
+    if (Result.isFailure(ready)) {
+      if (!acquired.reused) {
+        return yield* cleanupFailedInteractiveLaunch(
+          ready.failure,
+          acquired.pane_id,
+          (id) => paneClose(processService, id),
+        )
+      }
+      return yield* withLaunchDetails(ready.failure, {
+        delivery: "not_delivered",
+      })
     }
 
     // Submit pointer into the live TUI (Herdr: pane run = text + Enter),
     // then confirm the agent actually started — do not trust fire-and-forget.
-    const submitted = yield* Effect.result(paneRun(acquired.pane_id, prompt))
+    const submitted = yield* Effect.result(
+      Effect.gen(function* () {
+        yield* paneRun(processService, acquired.pane_id, prompt)
+        return yield* ensurePromptSubmitted(acquired.pane_id, prompt, {
+          processService,
+        })
+      }),
+    )
     if (Result.isFailure(submitted)) {
       return yield* withLaunchDetails(submitted.failure, {
-        // The Herdr CLI can lose its response after the pane accepted text.
+        // Submission or acceptance probing can fail after the pane accepted text.
         // Closing or retrying here could kill or duplicate a live worker.
         delivery: "unknown",
         pane_id: acquired.pane_id,
@@ -654,7 +866,7 @@ function runInteractivePromptImpl(
         reused: acquired.reused,
       })
     }
-    const submit = yield* ensurePromptSubmitted(acquired.pane_id, prompt)
+    const submit = submitted.success
     return {
       pane_id: acquired.pane_id,
       label: acquired.label,
@@ -673,32 +885,26 @@ function runInteractivePromptImpl(
 export const makeHerdrLive = (hostAdapter: ApneaHostAdapter) =>
   Layer.effect(
     Herdr,
-    Effect.sync(() =>
-      Herdr.of({
+    Effect.gen(function* () {
+      const processService = yield* Process
+      return Herdr.of({
         enabled: Effect.sync(herdrEnabledSync),
 
-        availability: Effect.try({
-          try: herdrAvailabilitySync,
-          catch: toHerdrError,
-        }),
+        availability: herdrAvailability(processService),
 
-        paneGet: (paneId) => Effect.sync(() => paneGetSync(paneId)),
+        paneGet: (paneId) => paneGet(processService, paneId),
 
-        paneRun,
+        paneRun: (paneId, command) => paneRun(processService, paneId, command),
 
-        paneReadRecent: (paneId) =>
-          Effect.try({
-            try: () => paneReadRecentSync(paneId),
-            catch: toHerdrError,
-          }),
+        paneReadRecent: (paneId) => paneReadRecent(processService, paneId),
 
         paneForegroundNames: (paneId) =>
-          Effect.sync(() => paneForegroundNamesSync(paneId)),
+          paneForegroundNames(processService, paneId),
 
         runInteractivePrompt: (...args) =>
-          runInteractivePromptImpl(hostAdapter, ...args),
-      }),
-    ),
+          runInteractivePromptImpl(processService, hostAdapter, ...args),
+      })
+    }),
   )
 
 export const HerdrLive = makeHerdrLive(neutralHostAdapter)