spexcode 0.4.1 → 0.5.0

package/spec-cli/src/message-stream.ts

@@ -0,0 +1,147 @@
+import { closeSync, fstatSync, openSync, readSync, watch, type FSWatcher } from 'node:fs'
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+
+import { readAliasedRawRecord, sessionArtifactPath, sessionStoreDir } from './layout.js'
+
+export type NativeMessageEvent = Record<string, unknown>
+export type MessageEnvelope = { cursor: number; event: NativeMessageEvent }
+export type MessageBatch = { messages: MessageEnvelope[]; cursor: number }
+
+function fileBytes(path: string, cursor: number): Buffer {
+  let fd: number
+  try { fd = openSync(path, 'r') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && cursor === 0) return Buffer.alloc(0)
+    throw error
+  }
+  try {
+    const size = fstatSync(fd).size
+    if (cursor > size) throw new Error(`messages.ndjson cursor ${cursor} is past file size ${size}`)
+    const bytes = Buffer.alloc(size - cursor)
+    let read = 0
+    while (read < bytes.length) {
+      const count = readSync(fd, bytes, read, bytes.length - read, cursor + read)
+      if (count === 0) break
+      read += count
+    }
+    return read === bytes.length ? bytes : bytes.subarray(0, read)
+  } finally { closeSync(fd) }
+}
+
+// Parse only newline-terminated records. The cursor is a byte offset, not a character count, so an SSE
+// reconnect resumes correctly even when a native event contains non-ASCII text.
+export function readMessageBatchFile(path: string, requestedCursor = 0): MessageBatch {
+  const cursor = Number.isSafeInteger(requestedCursor) && requestedCursor >= 0 ? requestedCursor : 0
+  const bytes = fileBytes(path, cursor)
+
+  const messages: MessageEnvelope[] = []
+  let lineStart = 0
+  while (lineStart < bytes.length) {
+    const newline = bytes.indexOf(0x0a, lineStart)
+    if (newline < 0) break
+    const nextCursor = cursor + newline + 1
+    const text = bytes.subarray(lineStart, newline).toString('utf8')
+    let event: unknown
+    try { event = JSON.parse(text) }
+    catch (error) {
+      throw new Error(`invalid messages.ndjson event at byte ${cursor + lineStart}: ${(error as Error).message}`)
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event)) {
+      throw new Error(`invalid messages.ndjson event at byte ${cursor + lineStart}: expected a JSON object`)
+    }
+    messages.push({ cursor: nextCursor, event: event as NativeMessageEvent })
+    lineStart = newline + 1
+  }
+  return { messages, cursor: cursor + lineStart }
+}
+
+// null means the id is unknown or is not a governed session. A known session with no adapter output yet is
+// an ordinary empty stream: the adapter may create messages.ndjson after the browser has connected.
+export function readSessionMessages(id: string, cursor = 0): MessageBatch | null {
+  const record = readAliasedRawRecord(id)
+  if (!record?.governed) return null
+  return readMessageBatchFile(sessionArtifactPath(record.session_id, 'messages.ndjson'), cursor)
+}
+
+type StreamSignal = 'append' | 'ping' | 'abort' | 'watch-error'
+
+function signalQueue() {
+  const queued: StreamSignal[] = []
+  let waiter: ((signal: StreamSignal) => void) | null = null
+  const push = (signal: StreamSignal) => {
+    if (signal === 'append' && queued.includes('append')) return
+    if (waiter) {
+      const resolve = waiter
+      waiter = null
+      resolve(signal)
+    } else queued.push(signal)
+  }
+  const next = (): Promise<StreamSignal> => {
+    const ready = queued.shift()
+    return ready ? Promise.resolve(ready) : new Promise((resolve) => { waiter = resolve })
+  }
+  return { push, next }
+}
+
+function cursorParam(value: string | undefined): number | null {
+  if (!value || !/^\d+$/.test(value)) return null
+  const cursor = Number(value)
+  return Number.isSafeInteger(cursor) ? cursor : null
+}
+
+// GET /api/sessions/:id/messages/stream — the append-follow half of [[message-stream]]. REST establishes a
+// complete snapshot + cursor; this stream starts there. Standard SSE ids let EventSource reconnect through
+// Last-Event-ID even though its original URL still carries the older cursor.
+export function sessionMessageStream(c: Context): Response {
+  const record = readAliasedRawRecord(c.req.param('id') as string)
+  if (!record?.governed) return c.json({ error: 'no such session' }, 404)
+
+  const lastEventCursor = cursorParam(c.req.header('Last-Event-ID'))
+  const queryCursor = cursorParam(c.req.query('cursor'))
+  const startCursor = lastEventCursor ?? queryCursor ?? 0
+  const id = record.session_id
+
+  return streamSSE(c, async (stream) => {
+    const signals = signalQueue()
+    let aborted = false
+    let watcher: FSWatcher | null = null
+    const ping = setInterval(() => signals.push('ping'), 10_000)
+    ping.unref()
+    stream.onAbort(() => { aborted = true; signals.push('abort') })
+
+    try {
+      watcher = watch(sessionStoreDir(id), { persistent: false }, (_event, filename) => {
+        if (filename == null || String(filename) === 'messages.ndjson') signals.push('append')
+      })
+      watcher.on('error', () => signals.push('watch-error'))
+
+      let cursor = startCursor
+      await stream.writeSSE({ event: 'ready', data: JSON.stringify({ cursor }) })
+      const flush = async () => {
+        const batch = readSessionMessages(id, cursor)
+        if (!batch) throw new Error('session closed')
+        cursor = batch.cursor
+        for (const message of batch.messages) {
+          await stream.writeSSE({ event: 'message', id: String(message.cursor), data: JSON.stringify(message) })
+        }
+      }
+      await flush()
+
+      while (!aborted) {
+        const signal = await signals.next()
+        if (signal === 'abort') break
+        if (signal === 'watch-error') throw new Error('messages.ndjson watcher failed')
+        if (signal === 'ping') await stream.writeSSE({ event: 'ping', data: 'x' })
+        else await flush()
+      }
+    } catch (error) {
+      if (!aborted) {
+        await stream.writeSSE({ event: 'stream-error', data: JSON.stringify({ error: (error as Error).message }) }).catch(() => {})
+      }
+    } finally {
+      clearInterval(ping)
+      watcher?.close()
+    }
+  })
+}

package/spec-cli/src/opencode-headless.ts

@@ -0,0 +1,95 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+
+const pexec = promisify(execFile)
+
+const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+// A headless turn owns the pane only while `opencode run` is alive. Returning to a shell keeps the tmux
+// window as the session's durable home without adding a resident controller or an stdin bridge.
+function turnHome(command: string): string {
+  const script = [
+    command,
+    '__spex_rc=$?',
+    '[ "$__spex_rc" -eq 0 ] || printf "[spex opencode-headless] turn exited rc=%s\\n" "$__spex_rc" >&2',
+    'exec "${SHELL:-/bin/sh}"',
+  ].join('\n')
+  return `bash -lc ${shQuote(script)} spexcode-opencode-headless`
+}
+
+// Launcher profiles carry a base executable plus its configured flags (`opencode --auto`). OpenCode parses
+// `run` as a subcommand, so it must sit between those two halves (`opencode run --auto`), not at the tail.
+function runPrelude(opencodeCmd: string): string[] {
+  return [
+    `__spex_cmd=(${opencodeCmd})`,
+    '__spex_env=()',
+    'while [ "${#__spex_cmd[@]}" -gt 0 ] && [[ "${__spex_cmd[0]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do',
+    '  __spex_env+=("${__spex_cmd[0]}")',
+    '  __spex_cmd=("${__spex_cmd[@]:1}")',
+    'done',
+    '__spex_run() { env "${__spex_env[@]}" "${__spex_cmd[0]}" run "${__spex_cmd[@]:1}" "$@"; }',
+  ]
+}
+
+export function opencodeHeadlessLaunchCommand(opencodeCmd = 'opencode'): string {
+  const script = [
+    ...runPrelude(opencodeCmd),
+    'if [ "${1:-}" = "--resume" ]; then',
+    '  export SPEXCODE_OPENCODE_RESUME_ID="$2"',
+    '  unset SPEXCODE_OPENCODE_CONTINUE',
+    '  __spex_run --session "$2"',
+    'elif [ "${1:-}" = "--continue" ]; then',
+    '  unset SPEXCODE_OPENCODE_RESUME_ID',
+    '  export SPEXCODE_OPENCODE_CONTINUE=1',
+    '  __spex_run --continue',
+    'elif [ -n "${1:-}" ]; then',
+    '  unset SPEXCODE_OPENCODE_RESUME_ID SPEXCODE_OPENCODE_CONTINUE',
+    '  __spex_run "$1"',
+    'else',
+    '  __spex_run',
+    'fi',
+  ].join('\n')
+  return turnHome(script)
+}
+
+export function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string): string {
+  const resume = harnessSessionId ? [
+    `export SPEXCODE_OPENCODE_RESUME_ID=${shQuote(harnessSessionId)}`,
+    'unset SPEXCODE_OPENCODE_CONTINUE',
+    `__spex_run --session ${shQuote(harnessSessionId)} ${shQuote(text)}`,
+  ] : [
+    'unset SPEXCODE_OPENCODE_RESUME_ID',
+    'export SPEXCODE_OPENCODE_CONTINUE=1',
+    `__spex_run --continue ${shQuote(text)}`,
+  ]
+  return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'))
+}
+
+export async function spawnOpenCodeHeadlessTurn(
+  rec: HarnessDeliveryRecord,
+  text: string,
+  opencodeCmd: string,
+  socketPath: string,
+): Promise<DispatchResult> {
+  if (!rec.worktreePath) return { ok: false, error: `opencode-headless session ${rec.session} has no worktree path - turn NOT started` }
+  const tmuxSock = process.env.SPEXCODE_TMUX || 'spexcode'
+  const args = [
+    '-L', tmuxSock, 'respawn-pane', '-k', '-t', rec.session, '-c', rec.worktreePath,
+    '-e', `SPEXCODE_SESSION_ID=${rec.session}`,
+    '-e', 'CLAUDE_BG_BACKEND=daemon',
+    '-e', `CLAUDE_BG_RENDEZVOUS_SOCK=${socketPath}`,
+  ]
+  for (const name of ['SPEXCODE_HOME', 'CODEX_HOME']) {
+    const value = process.env[name]
+    if (value) args.push('-e', `${name}=${value}`)
+  }
+  args.push(opencodeHeadlessWakeCommand(opencodeCmd, rec.harnessSessionId, text))
+  try {
+    await pexec('tmux', args, { timeout: 5_000 })
+    return { ok: true }
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return { ok: false, error: `opencode-headless could not start a turn for session ${rec.session}: ${detail}` }
+  }
+}

package/spec-cli/src/opencode.ts

@@ -0,0 +1,145 @@
+import { shimRuntimeSource } from './shim-runtime.js'
+
+// @@@ opencode plugin generator - the opencode adapter's "shim" is not a settings JSON but a generated
+// opencode PLUGIN (.opencode/plugins/spexcode.ts, auto-loaded by opencode from the project tree) that runs
+// inside the agent process. It is a THIN HOST over the shared shim runtime ([[shim-runtime]], embedded
+// verbatim): this generator declares opencode's event-bus mapping (session.created → SessionStart,
+// chat.message → UserPromptSubmit, tool.execute.before/after → Pre/PostToolUse, session.idle → Stop) and its
+// host bindings; the payload synthesis, the block verdict (exit 2 + stdout decision:block JSON), and the
+// rendezvous server come from the runtime. opencode's host-specific verdict consumers ([[opencode-harness]]):
+// a PreToolUse block THROWS (opencode aborts the tool call); a Stop block re-injects the gate's reason as a
+// follow-up prompt via the SDK client, closing the stop-gate loop. What re-enters is always the parsed
+// REASON, never the escaped wire JSON. The rendezvous inject is client.session.prompt into the ROOT session,
+// gated by canInject (a plugin with no adopted session reply-rejects instead of confirming an undeliverable
+// prompt). What genuinely stays opencode-only below: session tracking (root vs subagent children, the
+// agent_id stamp), the minted-id capture, and the two resume seeds.
+// This module is a PURE content producer (no imports from harness.ts — the adapter object lives there, in the
+// one HARNESSES seam) so there is no import cycle.
+
+// the lifecycle events the generated plugin can emit (drives the shim + hooks-manifest binding). opencode's
+// bus has no failed-stop and no idle/attention notification event, so StopFailure/Notification are genuinely
+// absent — the same five codex binds.
+export const OPENCODE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
+
+// opencode tool name → Claude tool name, so [[inject-spec-first]] / [[inject-spec-of-file]] and every other
+// claude-family handler read the payload with zero opencode knowledge. Unknown tools pass through untouched
+// (opencode's names are lowercase). Exported for tests.
+export const OPENCODE_TOOL_NAMES: Record<string, string> = {
+  bash: 'Bash', edit: 'Edit', write: 'Write', read: 'Read', grep: 'Grep', glob: 'Glob', list: 'LS',
+  patch: 'Edit', todowrite: 'TodoWrite', todoread: 'TodoRead', webfetch: 'WebFetch', task: 'Task',
+}
+
+// the generated plugin source. `dispatch` and `spex` are absolute paths baked at materialize time (same as
+// every shim); the 'dispatch.sh' substring doubles as the identity stamp cleanHarness gates removal on. The
+// file is plain TS with no @opencode-ai/plugin type import, so it loads regardless of the host project's
+// node_modules; opencode calls every exported function with its plugin context.
+export function opencodePluginSource(dispatch: string, spex: string): string {
+  return `// spexcode: GENERATED by spex materialize — do not edit (regenerated per clone; see [[opencode-harness]])
+// Bridges opencode's event bus into SpexCode's dispatch.sh (claude-shaped payloads) and serves the
+// per-session rendezvous socket for prompt delivery + liveness.
+import { spawn } from "node:child_process"
+${shimRuntimeSource('opencode', dispatch, spex)}
+
+const TOOL_NAMES = ${JSON.stringify(OPENCODE_TOOL_NAMES)}
+
+export const SpexcodePlugin = async (ctx) => {
+  const client = ctx && ctx.client
+  const cwd = (ctx && (ctx.directory || (ctx.app && ctx.app.path && ctx.app.path.cwd))) || process.cwd()
+  const recordId = (process.env.SPEXCODE_SESSION_ID || "").trim()
+  const rt = spexShimRuntime({ sessionId: () => recordId, cwd: () => cwd })
+
+  // session tracking: the ROOT opencode session is this worker's conversation; child sessions (subagents)
+  // are stamped agent_id so a parent's declared state stays out of its subagents' reach (the same
+  // discriminator claude's Task subagents carry). A RESUMED session re-fires no bus event until poked, so
+  // event-driven adoption alone leaves a resumed worker unreachable (the daemon reply-rejects every
+  // delivery): a --session resume seeds rootSession from the launch env (the resume marker's id), and a
+  // --continue resume falls back to asking the SDK for the newest root session.
+  let rootSession = (process.env.SPEXCODE_OPENCODE_RESUME_ID || "").trim()
+  const children = new Set()
+  const stamp = (sid) => (sid && children.has(sid) ? { agent_id: sid } : {})
+  // opencode MINTS its own session id — report it once so the backend stores it as harness_session_id
+  // (the id session resume passes to \`opencode --session <id>\`). Fire-and-forget; a failure only costs resume-by-id.
+  let captured = !!rootSession   // a seeded (resumed) id is already on the record — don't re-report it
+  const capture = (sid) => {
+    if (captured || !sid || !recordId) return
+    captured = true
+    try { spawn(SPEX, ["internal", "opencode-capture", sid], { cwd, env: process.env, stdio: "ignore" }) } catch { /* resume falls back to --continue */ }
+  }
+  const adopt = (sid) => { if (!rootSession && sid) { rootSession = sid; capture(sid) } }
+  const injectPrompt = async (text) => {
+    if (!client || !rootSession) throw new Error("no session to prompt")
+    await client.session.prompt({ path: { id: rootSession }, body: { parts: [{ type: "text", text }] } })
+  }
+
+  // --continue resume: no owned id was ever captured, and a reattached session fires no bus event until
+  // poked — ask the SDK for the newest root session (what --continue itself reattached) so deliveries can
+  // inject. Gated on the launch marker so a FRESH launch can never adopt a stale session; best-effort with
+  // bounded retries (the server may still be loading at plugin init), shape-defensive, and adopt() ignores
+  // the late result if a real event won the race.
+  if (!rootSession && process.env.SPEXCODE_OPENCODE_CONTINUE && client && client.session && typeof client.session.list === "function") {
+    (async () => {
+      for (let i = 0; i < 10 && !rootSession; i++) {
+        try {
+          const res = await client.session.list()
+          const arr = (res && (res.data || res)) || []
+          const roots = (Array.isArray(arr) ? arr : []).filter((s) => s && s.id && !s.parentID)
+          const at = (s) => (s.time && (s.time.updated || s.time.created)) || 0
+          roots.sort((a, b) => at(b) - at(a))
+          if (roots.length) { adopt(roots[0].id); return }
+        } catch { /* not up yet — retry */ }
+        await new Promise((r) => setTimeout(r, 1000))
+      }
+    })()
+  }
+
+  // the rendezvous daemon, from the shared runtime: {type:"reply"} injects into the root session (a plugin
+  // that adopted no session yet reply-rejects synchronously, BEFORE repaint-done, so the sender fails loud
+  // instead of confirming a prompt that can never inject); {type:"repaint"} answers repaint-done in the same
+  // synchronous parse pass — confirmation means PARSED, not processed. The injection itself (a whole model
+  // turn: the SDK prompt call resolves only when the TURN ends) runs BEHIND the confirm.
+  rt.serveRendezvous(injectPrompt, { canInject: () => !!(client && rootSession) })
+
+  const toolPayload = (input, output) => {
+    const sid = (input && input.sessionID) || ""
+    return {
+      ...stamp(sid),   // agent_id must precede tool_input — hp_is_subagent checks keys only before tool_input
+      tool_name: TOOL_NAMES[(input && input.tool) || ""] || ((input && input.tool) || ""),
+      tool_input: rt.toolInput(output && output.args, "filePath"),
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      const t = event && event.type
+      const p = (event && event.properties) || {}
+      if (t === "session.created") {
+        const info = p.info || {}
+        if (info.parentID) children.add(info.id)
+        else if (!rootSession) { adopt(info.id); await rt.dispatchEvent("SessionStart", { source: "startup" }) }
+      } else if (t === "session.idle") {
+        const sid = p.sessionID || ""
+        if (sid && rootSession && sid !== rootSession) return   // a subagent going idle is not this worker's Stop
+        adopt(sid)
+        // the stop-gate loop closes in-process via the runtime's dispatchStop: stop_hook_active rides the
+        // payload (the gate's loop-termination bit) and the gate's parsed reason re-enters as a follow-up
+        // prompt; an inject the host can no longer take is reported loud.
+        await rt.dispatchStop((reason) => injectPrompt(reason), "blocked by a spexcode hook")
+      }
+    },
+    "chat.message": async (input, output) => {
+      const sid = (output && output.message && output.message.sessionID) || (input && input.sessionID) || ""
+      if (!(sid && children.has(sid))) adopt(sid)
+      const text = ((output && output.parts) || []).filter((x) => x && x.type === "text").map((x) => x.text).join("\\n")
+      await rt.dispatchEvent("UserPromptSubmit", { ...stamp(sid), prompt: text })
+    },
+    "tool.execute.before": async (input, output) => {
+      const r = await rt.dispatchEvent("PreToolUse", toolPayload(input, output))
+      if (rt.blocked(r)) throw new Error(rt.blockReason(r, "blocked by a spexcode hook"))   // aborts the tool call — the PreToolUse block contract
+    },
+    "tool.execute.after": async (input, output) => {
+      await rt.dispatchEvent("PostToolUse", toolPayload(input, output))
+    },
+  }
+}
+`
+}

package/spec-cli/src/pi-harness.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { shimRuntimeSource } from './shim-runtime.js'
+
+// @@@ pi-harness helpers - the pi-ONLY machinery behind harness.ts's piHarness adapter: the generated
+// extension source (pi's shim is a TypeScript extension, not a hooks JSON — pi has no external hook binding;
+// its lifecycle surface IS the extension API) and the trust writer (pi's project-trust store,
+// ~/.pi/agent/trust.json). Kept out of harness.ts so the adapter table stays scannable; imports NOTHING from
+// harness.ts at runtime (no cycle — harness.ts imports us).
+
+// ---------------------------------------------------------------------------------------------------------
+// the pi shim = a generated extension at .pi/extensions/spexcode.ts (pi runs .ts extensions natively). It is
+// a THIN HOST over the shared shim runtime ([[shim-runtime]], embedded verbatim): this generator declares
+// only pi's event-name mapping and its ExtensionAPI bindings —
+//   session_start → SessionStart · input → UserPromptSubmit · tool_call → PreToolUse (blockable) ·
+//   tool_result → PostToolUse · agent_end + agent_settled → Stop (dual binding, one shared bit)
+// — while the payload synthesis, the block-verdict parse (exit 2 + stdout decision:block JSON), and the
+// rendezvous server all come from the runtime. pi's two host-specific verdict consumers: a tool_call block
+// returns pi's typed { block: true, reason }; a Stop block has no blocking return, so Stop rides the
+// runtime's dispatchStop on a DUAL binding — agent_end (awaited in the run loop: a queued teach drains as
+// the same prompt's continuation, never an orphan) plus agent_settled (fires once per prompt after every
+// drain: the terminal backstop whose flagged dispatch guarantees the gate's escape runs before settlement
+// completes) — with stop_hook_active synthesized across both and the gate's reason SENT BACK IN as a user
+// message; a no-longer-injectable host is reported loud — never silently dropped (a dropped rejection is
+// a session stuck `active` forever).
+// The rendezvous inject is pi.sendUserMessage({deliverAs: steer}), always able → no canInject gate.
+export function piExtensionSource(dispatch: string, spex: string): string {
+  return `// generated by spexcode materialize — DO NOT EDIT (regenerated per clone; identity: dispatch.sh)
+// SpexCode's pi shim: forwards pi lifecycle events to dispatch.sh as Claude-shaped hook payloads, and serves
+// this session's rendezvous socket for prompt delivery + liveness.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+${shimRuntimeSource('pi', dispatch, spex)}
+
+// pi tool names → the Claude tool vocabulary harness.sh parses (unknown names pass through untouched).
+const TOOL: Record<string, string> = { read: "Read", edit: "Edit", write: "Write", bash: "Bash" }
+
+export default function spexcode(pi: ExtensionAPI) {
+  let sessionId = process.env.SPEXCODE_SESSION_ID || ""
+  const rt = spexShimRuntime({ sessionId: () => sessionId })
+  const toolFields = (toolName: string, input: unknown) =>
+    ({ tool_name: TOOL[toolName] ?? toolName, tool_input: rt.toolInput(input, "path") })
+
+  // bound as soon as the extension loads so liveness reads online early; only a governed launch carries the
+  // socket env (sessions.ts rvEnv) — a self-launched bare \`pi\` skips this.
+  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }))
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionId = ctx.sessionManager.getSessionId() || sessionId
+    process.env.PI_SESSION_ID = sessionId   // tool subprocesses inherit it → spex CLI knows its session
+    await rt.dispatchEvent("SessionStart")
+  })
+  pi.on("input", async (event) => { await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
+  pi.on("tool_call", async (event) => {
+    const r = await rt.dispatchEvent("PreToolUse", toolFields(event.toolName, event.input))
+    if (rt.blocked(r)) return { block: true, reason: rt.blockReason(r, "blocked by a SpexCode hook") }
+  })
+  pi.on("tool_result", async (event) => { await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
+  // Stop rides the runtime's dispatchStop on TWO bindings that never duplicate: agent_end performs the
+  // NORMAL dispatch (pi awaits its listeners inside the run loop and drains a queued teach as the SAME
+  // awaited prompt's continuation — never the orphaned settle-time prompt whose late inject threw
+  // "extension ctx is stale"), while agent_settled — which fires exactly once per prompt, after every
+  // drain — consumes AT MOST ONE PENDING BLOCKED stop (measured gap: in real dispatched runs the drained
+  // continuation's own agent_end does not reliably re-reach the extension, so without the backstop the
+  // flagged escape never runs). A naturally allowed agent_end leaves no
+  // pending state and settle dispatches NOTHING (exactly one gate entry per stop); only a blocked
+  // agent_end arms it, and the flagged settle dispatch always ends allowed (the gate's continuation paths
+  // terminate), clearing the pending bit through a subprocess write with no duplicate inject. An
+  // uninjectable host stays caught-loud.
+  const stop = () => rt.dispatchStop(
+    async (reason: string) => pi.sendUserMessage(reason, { deliverAs: "steer" }),
+    "a SpexCode Stop hook blocked this stop without giving a reason",
+  )
+  pi.on("agent_end", async () => { await stop() })
+  pi.on("agent_settled", async () => { if (rt.stopPending()) await stop() })
+  pi.on("session_shutdown", async () => { rv?.close() })
+}
+`
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// pi trust — make a dispatched/self-launched pi load our project-local extension with zero prompts. pi gates
+// EVERY project-local resource (.pi/extensions, .pi/skills, .pi/prompts, .pi/settings.json) behind project
+// trust: saved decisions live in ~/.pi/agent/trust.json as a flat { "<canonical dir>": true|false } map, and
+// the CLOSEST saved decision on the cwd's parent chain wins (pi trust-manager findNearestTrustEntry). So ONE
+// entry keyed by the MAIN CHECKOUT covers every .worktrees/<id> worktree beneath it. The launch additionally
+// carries `--approve` (one-run trust) as defence for a worktree living OUTSIDE the checkout. Writes are
+// idempotent and surgical: other projects' decisions are untouched; a corrupt trust.json FAILS LOUD rather
+// than being clobbered; remove only deletes a `true` we could have written, never a user's saved "false".
+
+// pi has no config-dir env of its own (hardcoded ~/.pi/agent) — SPEXCODE_PI_AGENT_DIR is OUR test seam only.
+const piAgentDir = () => process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent')
+// pi canonicalizes trust keys (realpath); mirror it so our key matches its lookup.
+const canonical = (p: string) => { try { return realpathSync(p) } catch { return p } }
+
+function readTrust(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {}
+  const raw = readFileSync(file, 'utf8')
+  try { return JSON.parse(raw) as Record<string, unknown> } catch (e) {
+    throw new Error(`${file} is not valid JSON — refusing to rewrite pi's trust store: ${String(e)}`)
+  }
+}
+
+export function writePiTrust(proj: string): string {
+  const dir = piAgentDir()
+  const file = join(dir, 'trust.json')
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] === true) return file   // already trusted — no churn
+  data[key] = true
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+  return file
+}
+
+export function removePiTrust(proj: string): void {
+  const file = join(piAgentDir(), 'trust.json')
+  if (!existsSync(file)) return
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] !== true) return   // absent, or a user's own "do not trust" — never touch it
+  delete data[key]
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+}