@naxodev/apnea 0.1.0 → 0.2.0

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

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

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

@@ -16,7 +16,7 @@ Both adapters bind the operation registry exported by `@naxodev/apnea`. The Pi a
 
 The core exposes only the operation registry, result formatting, command parsing, resource-root lookup, and the `ApneaHostAdapter` launch hooks. Pi supplies those hooks when it creates its registry.
 
-`@naxodev/pi-apnea` depends on `@naxodev/apnea` with `^0.1.0`. Compatible core patch releases flow through that range. An incompatible host interface change requires coordinated minor releases of both packages.
+The current incompatible `@naxodev/pi-apnea` line depends on `@naxodev/apnea` with `^0.2.0`. Compatible core patch releases flow through that range. For an incompatible line, the core manifest is pre-staged at the new minor so the workspace remains installable while Nx coordinates the adapter's minor release.
 
 ## Consequences
 

package/docs/protocol/config.md

@@ -52,8 +52,6 @@ Unknown keys and unimplemented values (`isolation: "worktree"`) **hard-error** a
     "coder": { "profile": "pi-grok" },
   },
   "review_round_cap": 3,
-  // "regular" (default) or "floating"; omit the key to keep the default
-  "pane_style": "regular",
   "timeouts_ms": {
     "planning": 1500000,
     "plan_review": 900000,
@@ -129,29 +127,16 @@ a slow test run can read `idle` for a minute. The nudge is one-shot, so a false
 105000ms, leaving roughly 15000ms of margin under a 120000ms shell. Raise one and you must raise
 the other.
 
-## Pane style
-
-`pane_style` controls how role dispatches appear in Herdr:
-
-- Values: `"regular"` | `"floating"`. Default is `"regular"` — **omitting the key changes nothing**.
-- Allowed in global config and overridable per project.
-- `"floating"` applies to **planner/reviewer oneshot dispatches only**. It requires herdr ≥ 0.7.4 **and** the linked `apnea` plugin (provisioned by `/apnea setup`). The popup is **session-modal**: it takes keyboard input until the worker exits, and dismissing it early kills the dispatch.
-- Floating oneshot scripts resolve `cmd_oneshot[0]` to an **absolute path** in the orchestrator environment and pass an augmented `PATH` into the popup. Bare names must be findable via the orchestrator's `PATH` (e.g. `~/.local/bin`); otherwise dispatch fails immediately instead of the popup exiting 127. Prefer absolute `cmd_oneshot` if your orchestrator process has a stripped PATH.
-- **Lifecycle (single popup):** herdr allows only one popup. Dispatch refuses while a prior floating oneshot is still live. The worker writes an exit-status file; `workflow_wait` fails closed when the popup dies without a complete artifact (instead of hanging until timeout). A second open while a popup is up surfaces `popup already open` immediately.
-- Interactive roles (orchestrator, coder) always use regular panes; the dispatch result reports `pane_style_effective: "regular (interactive role)"`.
-- Misconfiguration (old herdr, missing plugin, missing `cmd_oneshot`, unresolved oneshot binary) fails fast at dispatch with an actionable error.
-- Non-goal: per-role `pane_style` is future work. Setup never writes or flips this key — it only preserves a valid existing value on re-run.
-
 ## Role modes (fixed)
 
-By default every worker role launches the **interactive** harness TUI so you can watch it in Herdr. With `pane_style: "floating"`, planner and reviewer instead run their profile's **`cmd_oneshot`** inside the popup (those profiles therefore need `cmd_oneshot` for floating — dispatch preflight errors otherwise). Interactive roles always stay on `cmd_interactive`.
+Every worker role launches the **interactive** harness TUI in a reusable Herdr pane. Apnea dispatch always resolves `cmd_interactive`; a profile that only has `cmd_oneshot` cannot satisfy any role. `cmd_oneshot` remains part of the profile contract for manual and external workflows.
 
-| Role         | Required profile capability                                         |
-| ------------ | ------------------------------------------------------------------- |
-| orchestrator | `cmd_interactive`                                                   |
-| planner      | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
-| reviewer     | `cmd_interactive` (and `cmd_oneshot` when `pane_style: "floating"`) |
-| coder        | `cmd_interactive`                                                   |
+| Role         | Required profile capability |
+| ------------ | --------------------------- |
+| orchestrator | `cmd_interactive`           |
+| planner      | `cmd_interactive`           |
+| reviewer     | `cmd_interactive`           |
+| coder        | `cmd_interactive`           |
 
 Binding a role to a profile missing the required capability → **hard-error**.
 

package/docs/protocol/manual-gate.md

@@ -24,7 +24,7 @@ Two phases, e.g. “CLI that greets by name + `--json` flag,” small enough to
 | 3   | Code CHANGES_REQUIRED | Live follow-up into existing coder pane; new `round-N` code-review; then APPROVED                                                 |
 | 4   | APPROVED + nits       | One review with `nits` field; commit still proceeds                                                                               |
 | 5   | Kill-and-resume       | Kill coder pane mid-phase; human reconciles per protocol (artifact present? ingest : re-dispatch same round); continue to success |
-| 6   | Mixed harness         | Planner/reviewer Claude oneshot; coder Pi interactive                                                                             |
+| 6   | Mixed harness         | Planner/reviewer Claude interactive; coder Pi interactive                                                                         |
 
 ## Hard rules during the gate
 

package/docs/protocol/overview.md

@@ -67,7 +67,7 @@ nits: | # optional; never blocks alone
 ---
 ```
 
-Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane / hung oneshot without artifact → escalate).
+Pane markers are human decoration. Herdr `agent_status` is liveness (dead pane without artifact → escalate).
 
 ## Rework
 

package/extension/domain/herdr.ts

@@ -1,52 +1,3 @@
-import type { PaneStyle, Role } from "./types.ts"
-
-/** Parse `herdr X.Y.Z` (or noisy multi-line) into a numeric tuple. */
-export function parseHerdrVersion(
-  raw: string,
-): [number, number, number] | null {
-  const m = raw.match(/(\d+)\.(\d+)\.(\d+)/)
-  if (!m) return null
-  return [Number(m[1]), Number(m[2]), Number(m[3])]
-}
-
-export function versionGte(
-  a: [number, number, number],
-  b: [number, number, number],
-): boolean {
-  const [a0, a1, a2] = a
-  const [b0, b1, b2] = b
-  if (a0 !== b0) return a0 > b0
-  if (a1 !== b1) return a1 > b1
-  return a2 >= b2
-}
-
-/**
- * Floating popups need herdr ≥ 0.7.4. Fail closed on unparseable versions so an
- * unattended run never hangs on a CLI that rejects `--placement popup`.
- */
-export function supportsFloating(
-  version: [number, number, number] | null,
-): boolean {
-  return version != null && versionGte(version, [0, 7, 4])
-}
-
-/**
- * Configured style vs effective style. Floating is only for planner/reviewer
- * (oneshot-eligible artifact producers); interactive roles always stay regular.
- */
-export function effectivePaneStyle(
-  configured: PaneStyle,
-  role: Role,
-): { style: PaneStyle; effective: string } {
-  if (configured === "regular") {
-    return { style: "regular", effective: "regular" }
-  }
-  if (role === "planner" || role === "reviewer") {
-    return { style: "floating", effective: "floating" }
-  }
-  return { style: "regular", effective: "regular (interactive role)" }
-}
-
 export function shellJoin(parts: string[]): string {
   return parts
     .map((p) => {
@@ -70,40 +21,3 @@ export function looksLikeShellOnly(names: string[]): boolean {
     )
   })
 }
-
-/** Parse a floating task's exit-file contents; null if not a finished exit code. */
-export function parseFloatingExit(text: string): number | null {
-  const t = text.trim()
-  const n = Number.parseInt(t, 10)
-  return Number.isFinite(n) ? n : null
-}
-
-/**
- * Self-contained bash script body that cds to root, runs cmd + prompt as a
- * child (not exec — so EXIT trap still fires), and always records the exit
- * code for workflow_wait. Popups have no pane id; the exit file is the
- * liveness signal.
- */
-export function floatingTaskScriptBody(opts: {
-  root: string
-  resolvedCmd: string[]
-  prompt: string
-  exitFileAbs: string
-}): string {
-  return [
-    "#!/bin/bash",
-    "set -uo pipefail",
-    `EXIT_FILE=${shellJoin([opts.exitFileAbs])}`,
-    "write_exit() {",
-    "  local st=$?",
-    `  printf '%s\n' "$st" > "$EXIT_FILE" 2>/dev/null || true`,
-    "}",
-    "trap write_exit EXIT",
-    "trap 'exit 129' HUP",
-    "trap 'exit 130' INT",
-    "trap 'exit 143' TERM",
-    shellJoin(["cd", opts.root]),
-    shellJoin([...opts.resolvedCmd, "--", opts.prompt]),
-    "",
-  ].join("\n")
-}

package/extension/domain/paths.ts

@@ -107,8 +107,7 @@ export function findPackageRootFrom(startDir: string): string | null {
 }
 
 /**
- * Package root — the directory holding `briefs/`, `herdr-plugin/`, and our
- * own `package.json`.
+ * Package root — the directory holding `briefs/` and our own `package.json`.
  *
  * Found by walking up and reading each `package.json`, NOT by counting
  * directory levels. The level count differs for every way this code runs, and

package/extension/domain/setup.ts

@@ -21,19 +21,6 @@ export function deepMergeProfiles(
   return out
 }
 
-/**
- * Carry a valid user pane_style preference forward. Setup never writes the
- * key when absent, and never invents values — only preserves exact "regular"
- * or "floating". Invalid prev values are dropped.
- */
-export function preservePaneStyle(
-  prev: Record<string, unknown>,
-): "regular" | "floating" | undefined {
-  const v = prev.pane_style
-  if (v === "regular" || v === "floating") return v
-  return undefined
-}
-
 export function buildProfiles(has: Detected): Record<string, unknown> {
   const profiles: Record<string, unknown> = {}
 
@@ -119,8 +106,6 @@ export function buildGlobalConfig(opts: {
     )
   }
 
-  const preservedPaneStyle = preservePaneStyle(prev)
-
   const globalConfig: Record<string, unknown> = {
     profiles: nextProfiles,
     roles: force || !prev.roles ? roles : prev.roles,
@@ -133,11 +118,6 @@ export function buildGlobalConfig(opts: {
           // values wait/commit actually use cannot drift apart.
           { ...DEFAULT_TIMEOUTS },
   }
-  // Preserve user opt-in only — never introduce pane_style when absent.
-  if (preservedPaneStyle !== undefined) {
-    globalConfig.pane_style = preservedPaneStyle
-  }
-
   return globalConfig
 }
 

package/extension/domain/types.ts

@@ -12,8 +12,6 @@ export type Role = "orchestrator" | "planner" | "reviewer" | "coder"
 
 export type RoleMode = "oneshot" | "interactive"
 
-export type PaneStyle = "regular" | "floating"
-
 export type Verdict = "APPROVED" | "CHANGES_REQUIRED"
 
 export type ReworkTarget = "code" | "phase_package"
@@ -34,7 +32,6 @@ export interface ApneaConfig {
   roles: Record<string, RoleBinding>
   review_round_cap: number
   timeouts_ms: Record<string, number>
-  pane_style: PaneStyle
 }
 
 export interface RunState {
@@ -57,12 +54,6 @@ export interface RunState {
   pending_pane_id: string | null
   /** Label of that pane (apnea:role:unique) */
   pending_pane_label: string | null
-  /**
-   * Relative path to the floating oneshot exit-status file (written when the
-   * popup worker process ends). Null for regular panes. Herdr popups have no
-   * pane id — this is how wait detects death without hanging until timeout.
-   */
-  pending_floating_exit: string | null
   /**
    * Epoch ms when the in-flight dispatch was launched. Null when idle.
    * Persisted so a chunked `workflow_wait` measures elapsed time from the

package/extension/domain/verify-commands.ts

@@ -1,128 +1,220 @@
-/** Does this line end in an ODD run of backslashes — a shell continuation? */
-function endsInContinuation(line: string): boolean {
-  const run = /(\\+)$/.exec(line)
-  return run !== null && run[1]!.length % 2 === 1
+export type VerifyBlock = {
+  readonly interpreter: "bash" | "sh"
+  readonly source: string
 }
 
-/**
- * Split fence lines into logical shell commands: continuations joined,
- * comments dropped — in ONE pass, because the two interact and both split
- * orderings shipped bugs.
- *
- * Join-then-strip (version 1): a comment ending in `\` swallowed the command
- * below it, then the merged line was dropped as a comment — `bun test
- * extension` silently never ran and the phase committed green.
- *
- * Strip-then-join (version 2): removing a comment line that sat BETWEEN a
- * continued line and the next command spliced the two commands together —
- * `test -f README.md \` + `# note` + `bun test extension` became one command.
- *
- * bash resolves this by interleaving, and each command later runs through
- * `bash -lc`, so bash's rules are the spec:
- *
- * - Joining appends the next line with NOTHING between; the final backslash of
- *   an odd run is dropped, the rest stay (they are escaped literals). A
- *   backslash that is not the line's last character continues nothing —
- *   `echo hi \ ` escapes the space and ends the command.
- * - A `#` at the start of a logical command is a comment; its own trailing
- *   backslash is inside the comment and continues nothing.
- * - A comment line reached MID-continuation ends the logical command, when the
- *   `#` would start a word in the joined text (whitespace before it). Without
- *   whitespace on either side of the join, `over\` + `#note` is the single
- *   word `over#note`, not a comment — so it is appended, not terminated on.
- */
-function logicalCommands(lines: string[]): string[] {
-  const out: string[] = []
-  let acc = ""
-  let pending = false
-  for (const line of lines) {
-    const isCommentish = line.trim().startsWith("#")
-    if (!pending && isCommentish) continue
-    if (pending && isCommentish && (/\s$/.test(acc) || /^\s/.test(line))) {
-      out.push(acc)
-      acc = ""
-      pending = false
-      continue
-    }
-    const continues = endsInContinuation(line)
-    const text = continues ? line.slice(0, -1) : line
-    acc = pending ? acc + text : text
-    pending = continues
-    if (!pending) {
-      out.push(acc)
-      acc = ""
-    }
-  }
-  // A dangling continuation on the last line: keep what we have rather than
-  // dropping the command on the floor.
-  if (pending) out.push(acc)
-  return out
+type FenceRegion = {
+  readonly start: number
+  readonly bodyStart: number
+  readonly bodyEnd: number
+  readonly info: string
+  readonly indent: number
+}
+
+type Heading = {
+  readonly start: number
+  readonly end: number
+  readonly rank: number | null
+  readonly text: string
+}
+
+export function normalizeVerifySource(source: string): string {
+  return source.replace(/\r\n?/g, "\n")
 }
 
-function toCommands(lines: string[]): string[] {
-  const cmds: string[] = []
-  for (const joined of logicalCommands(lines)) {
-    const t = joined.trim()
-    if (t) cmds.push(t)
+function atxHeading(line: string): { rank: number; text: string } | null {
+  const match = /^ {0,3}(#{1,6})(?:[\t ]+(.*?)|[\t ]*)$/.exec(line)
+  if (!match) return null
+  return {
+    rank: match[1]!.length,
+    text: (match[2] ?? "").replace(/[\t ]+#+[\t ]*$/, "").trim(),
   }
-  return cmds
 }
 
-function commandsFromFenceBody(body: string): string[] {
-  return toCommands(body.split(/\r?\n/))
+function boldHeading(line: string): string | null {
+  return /^ {0,3}\*\*(.+?)\*\*[\t ]*$/.exec(line)?.[1]?.trim() ?? null
 }
 
-/**
- * Extract shell commands from a phase package.
- * Prefer the fence under a "Verify commands" heading — packages often embed
- * earlier ```bash sketches that must not be executed at the commit gate.
- */
-export function extractVerifyCommands(phasePackageText: string): string[] {
-  // Heading-scoped fence first (## / ### / **Verify commands**)
-  const section = phasePackageText.match(
-    /(?:^|\n)(?:#{1,6}\s*|\*\*)Verify commands(?:\*\*)?\s*\r?\n([\s\S]*?)(?=\n#{1,6}\s|\n\*\*[A-Z]|$)/i,
-  )
-  if (section) {
-    const fence = section[1]!.match(/```(?:sh|bash|shell)\r?\n([\s\S]*?)```/i)
-    if (fence) {
-      const cmds = commandsFromFenceBody(fence[1]!)
-      if (cmds.length) return cmds
+function scanMarkdown(text: string): {
+  fences: FenceRegion[]
+  headings: Heading[]
+  unclosedFence: boolean
+} {
+  const fences: FenceRegion[] = []
+  const headings: Heading[] = []
+  let open:
+    | {
+        marker: "`" | "~"
+        length: number
+        start: number
+        bodyStart: number
+        info: string
+        indent: number
+      }
+    | undefined
+
+  let offset = 0
+  while (offset < text.length) {
+    const newline = text.indexOf("\n", offset)
+    const lineEnd = newline === -1 ? text.length : newline
+    const next = newline === -1 ? text.length : newline + 1
+    const line = text.slice(offset, lineEnd)
+
+    if (open) {
+      const closing = /^ {0,3}(`{3,}|~{3,})[\t ]*$/.exec(line)?.[1]
+      if (closing?.[0] === open.marker && closing.length >= open.length) {
+        fences.push({
+          start: open.start,
+          bodyStart: open.bodyStart,
+          bodyEnd: offset,
+          info: open.info,
+          indent: open.indent,
+        })
+        open = undefined
+      }
+    } else {
+      const opening = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line)
+      const marker = opening?.[2]
+      const info = opening?.[3] ?? ""
+      if (marker && !(marker[0] === "`" && info.includes("`"))) {
+        open = {
+          marker: marker[0] as "`" | "~",
+          length: marker.length,
+          start: offset,
+          bodyStart: next,
+          info: info.trim(),
+          indent: opening[1]!.length,
+        }
+      } else {
+        const atx = atxHeading(line)
+        const bold = boldHeading(line)
+        if (atx) {
+          headings.push({
+            start: offset,
+            end: next,
+            rank: atx.rank,
+            text: atx.text,
+          })
+        } else if (bold !== null) {
+          headings.push({ start: offset, end: next, rank: null, text: bold })
+        }
+      }
     }
+
+    offset = next
   }
 
-  // Fallback: last sh/bash fence in the doc (verify blocks are usually last)
-  const all = [
-    ...phasePackageText.matchAll(/```(?:sh|bash|shell)\r?\n([\s\S]*?)```/gi),
-  ]
-  for (let i = all.length - 1; i >= 0; i--) {
-    const cmds = commandsFromFenceBody(all[i]![1]!)
-    if (cmds.length) return cmds
+  return { fences, headings, unclosedFence: open !== undefined }
+}
+
+function toVerifyBlock(text: string, fence: FenceRegion): VerifyBlock | null {
+  const language = fence.info.toLowerCase()
+  if (language !== "bash" && language !== "sh" && language !== "shell") {
+    return null
+  }
+
+  const body = text.slice(fence.bodyStart, fence.bodyEnd)
+  const source =
+    fence.indent === 0
+      ? body
+      : body.replace(new RegExp(`^ {0,${fence.indent}}`, "gm"), "")
+  const hasExecutableLine = source
+    .split("\n")
+    .some((line) => line.trim() !== "" && !line.trimStart().startsWith("#"))
+  if (!hasExecutableLine) return null
+
+  return {
+    interpreter: language === "sh" ? "sh" : "bash",
+    source,
   }
+}
 
-  // Last resort: $ / test / bun lines scattered through prose.
-  //
-  // Continuations join FORWARD FROM A MATCHED COMMAND LINE only, never
-  // document-wide. This text is markdown, not shell, and a trailing backslash
-  // on a prose line is a markdown hard break: joining globally glued prose
-  // onto the command below it, the merged line no longer matched the command
-  // pattern, and the check was silently dropped — the gate ran a subset of
-  // the verify commands and committed the phase green. Comments need no
-  // handling here: a line starting with `#` cannot match the pattern.
-  const cmds: string[] = []
-  const rawLines = phasePackageText.split(/\r?\n/)
+function isShellFence(fence: FenceRegion): boolean {
+  return /^(?:bash|sh|shell)$/i.test(fence.info)
+}
+
+/** Does this line end in an odd run of backslashes? */
+function endsInContinuation(line: string): boolean {
+  const run = /(\\+)$/.exec(line)
+  return run !== null && run[1]!.length % 2 === 1
+}
+
+function extractLegacyBlocks(text: string): VerifyBlock[] {
+  const blocks: VerifyBlock[] = []
+  const rawLines = text.split("\n")
   for (let i = 0; i < rawLines.length; i++) {
-    const m = rawLines[i]!.match(
+    const match = rawLines[i]!.match(
       /^\s*(?:\$\s+)?((?:test |node |npm |bun |bunx |chmod |head ).+)$/,
     )
-    if (!m) continue
-    let cmd = m[1]!
-    while (endsInContinuation(cmd) && i + 1 < rawLines.length) {
-      cmd = cmd.slice(0, -1) + rawLines[++i]!
+    if (!match) continue
+    let source = match[1]!
+    while (endsInContinuation(source) && i + 1 < rawLines.length) {
+      source = source.slice(0, -1) + rawLines[++i]!
     }
-    // Dangling continuation on the final line: drop the backslash rather
-    // than handing the shell a command that continues into nothing.
-    if (endsInContinuation(cmd)) cmd = cmd.slice(0, -1)
-    cmds.push(cmd.trim())
+    if (endsInContinuation(source)) source = source.slice(0, -1)
+    blocks.push({ interpreter: "bash", source: source.trim() })
   }
-  return cmds
+  return blocks
+}
+
+/**
+ * Extract interpreter-aware verification scripts from a phase package.
+ * A Verify commands section owns every shell fence below it. Without that
+ * section, only the last shell fence is verification, matching legacy package
+ * selection without splitting a script into unrelated command lines.
+ */
+export function extractVerifyBlocks(phasePackageText: string): VerifyBlock[] {
+  const text = normalizeVerifySource(phasePackageText)
+  const { fences, headings, unclosedFence } = scanMarkdown(text)
+  if (unclosedFence) return []
+  const verifyHeading = headings.find(
+    (heading) => heading.text.toLowerCase() === "verify commands",
+  )
+
+  if (verifyHeading) {
+    const nextHeading = headings.find(
+      (heading) =>
+        heading.start >= verifyHeading.end &&
+        (heading.rank === null ||
+          verifyHeading.rank === null ||
+          (heading.rank !== null && heading.rank <= verifyHeading.rank)),
+    )
+    const sectionEnd = nextHeading?.start ?? text.length
+    const sectionFences = fences.filter(
+      (fence) => fence.start >= verifyHeading.end && fence.start < sectionEnd,
+    )
+    const blocks = sectionFences
+      .filter(isShellFence)
+      .map((fence) => toVerifyBlock(text, fence))
+      .filter((block): block is VerifyBlock => block !== null)
+    return sectionFences.length > 0
+      ? blocks
+      : extractLegacyBlocks(text.slice(verifyHeading.end, sectionEnd))
+  }
+
+  const shellFences = fences.filter(isShellFence)
+  if (shellFences.length > 0) {
+    const block = toVerifyBlock(text, shellFences[shellFences.length - 1]!)
+    return block ? [block] : []
+  }
+
+  return fences.length === 0 ? extractLegacyBlocks(text) : []
+}
+
+/** Render a block for readable logs without leaking its temp path. */
+export function formatVerifyBlock(block: VerifyBlock): string {
+  const source = normalizeVerifySource(block.source)
+  const body = source.endsWith("\n") ? source.slice(0, -1) : source
+  const displayedSource = body
+    .split("\n")
+    .map((line) => `| ${line}`)
+    .join("\n")
+  return `${block.interpreter} -e [verification block]\n${displayedSource}`
+}
+
+/** Render a verification block as a runnable command without its temp path. */
+export function formatVerifyCommand(block: VerifyBlock): string {
+  const source = normalizeVerifySource(block.source)
+  const quotedSource = `'${source.replaceAll("'", `'"'"'`)}'`
+  return `${block.interpreter} -e -c ${quotedSource}`
 }

package/extension/errors.ts

@@ -52,7 +52,7 @@ export class VcsError extends Schema.TaggedErrorClass<VcsError>()("VcsError", {
   command: Schema.optional(Schema.String),
 }) {}
 
-/** Herdr CLI / pane / floating failure. */
+/** Herdr CLI or pane failure. */
 export class HerdrError extends Schema.TaggedErrorClass<HerdrError>()(
   "HerdrError",
   {