@spexcode/spec-cli 0.6.5

package/dist/opencode-headless.js

@@ -0,0 +1,208 @@
+import { execFile } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { headlessTurnFailureShell } from './harness.js';
+import { shQuote } from './sh.js';
+const pexec = promisify(execFile);
+const WAKE_EARLY_EXIT_MS = 5_000;
+const OUTCOME_POLL_MS = 25;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function accountLoginShell() {
+    try {
+        return userInfo().shell || '';
+    }
+    catch {
+        return '';
+    }
+}
+// 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, outcomePath) {
+    const outcomeSetup = outcomePath ? [
+        `__spex_outcome_path=${shQuote(outcomePath)}`,
+        `__spex_outcome_tmp=${shQuote(`${outcomePath}.tmp`)}`,
+        '__spex_outcome() { printf \'%s\\n\' "$1" > "$__spex_outcome_tmp" && mv -f "$__spex_outcome_tmp" "$__spex_outcome_path"; }',
+        '__spex_outcome "running:$$" || { printf "[spex opencode-headless] could not create turn outcome marker\\n" >&2; exit 125; }',
+    ] : [];
+    const failure = outcomePath ? [
+        '__spex_cas_rc=0',
+        'if [ "$__spex_rc" -ne 0 ]; then',
+        '  __spex_outcome "reporting:$$:$__spex_rc" || true',
+        `  ${headlessTurnFailureShell('opencode-headless', false)}`,
+        '  __spex_cas_rc=$?',
+        'fi',
+        '__spex_outcome "exit:$__spex_rc:cas:$__spex_cas_rc" || printf "[spex opencode-headless] could not finalize turn outcome marker\\n" >&2',
+    ] : [
+        `if [ "$__spex_rc" -ne 0 ]; then ${headlessTurnFailureShell('opencode-headless')}; fi`,
+    ];
+    const script = [
+        ...outcomeSetup,
+        command,
+        '__spex_rc=$?',
+        ...failure,
+        '[ "$__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) {
+    const accountShell = accountLoginShell();
+    return [
+        '__spex_login_shell="${SHELL:-}"',
+        `[ -n "$__spex_login_shell" ] || __spex_login_shell=${shQuote(accountShell)}`,
+        `__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',
+        // Resolve OpenCode in the same login + interactive environment the user relies on. The launcher-leading
+        // assignments are applied after shell startup, so its explicit per-session config still wins.
+        '__spex_run() { [ -n "$__spex_login_shell" ] || { printf "[spex opencode-headless] no login shell could be resolved - turn NOT started\\n" >&2; return 126; }; "$__spex_login_shell" -ilc \'exec env "$@"\' spexcode-opencode-headless "${__spex_env[@]}" "${__spex_cmd[0]}" run "${__spex_cmd[@]:1}" "$@"; }',
+    ];
+}
+export function opencodeHeadlessLaunchCommand(opencodeCmd = 'opencode') {
+    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, harnessSessionId, text, outcomePath) {
+    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'), outcomePath);
+}
+function readTurnOutcome(path) {
+    let value;
+    try {
+        value = readFileSync(path, 'utf8').trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let match = /^running:(\d+)$/.exec(value);
+    if (match)
+        return { state: 'running', pid: Number(match[1]) };
+    match = /^reporting:(\d+):(-?\d+)$/.exec(value);
+    if (match)
+        return { state: 'reporting', pid: Number(match[1]), code: Number(match[2]) };
+    match = /^exit:(-?\d+):cas:(\d+)$/.exec(value);
+    if (match)
+        return { state: 'exit', code: Number(match[1]), casCode: Number(match[2]) };
+    return { state: 'invalid' };
+}
+function turnExited(rec, outcome) {
+    if (outcome.code === 0)
+        return { ok: true };
+    const cas = outcome.casCode === 0 ? '' : `; error CAS reporter also exited with code ${outcome.casCode}`;
+    return {
+        ok: false,
+        error: `opencode-headless turn exited with code ${outcome.code} during startup for session ${rec.session}${cas} - immediate wake failed`,
+    };
+}
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export async function spawnOpenCodeHeadlessTurn(rec, text, opencodeCmd, socketPath) {
+    if (!rec.worktreePath)
+        return { ok: false, error: `opencode-headless session ${rec.session} has no worktree path - turn NOT started` };
+    let outcomeDir;
+    try {
+        outcomeDir = mkdtempSync(join(tmpdir(), 'spexcode-oh-turn-'));
+    }
+    catch (error) {
+        return { ok: false, error: `opencode-headless could not prepare turn confirmation for session ${rec.session}: ${error.message}` };
+    }
+    const outcomePath = join(outcomeDir, 'exit-code');
+    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, outcomePath));
+    try {
+        await pexec('tmux', args, { timeout: 5_000 });
+        const deadline = Date.now() + WAKE_EARLY_EXIT_MS;
+        for (;;) {
+            const outcome = readTurnOutcome(outcomePath);
+            if (outcome?.state === 'exit')
+                return turnExited(rec, outcome);
+            if (outcome?.state === 'invalid') {
+                return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - immediate wake not confirmed` };
+            }
+            if (Date.now() >= deadline)
+                break;
+            await sleep(Math.min(OUTCOME_POLL_MS, deadline - Date.now()));
+        }
+        const first = readTurnOutcome(outcomePath);
+        if (first?.state === 'exit')
+            return turnExited(rec, first);
+        if (!first)
+            return { ok: false, error: `opencode-headless turn for session ${rec.session} never confirmed startup - immediate wake failed` };
+        if (first.state === 'invalid')
+            return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - immediate wake not confirmed` };
+        if (first.state === 'reporting') {
+            return { ok: false, error: `opencode-headless turn exited with code ${first.code} but its error CAS reporter did not finish for session ${rec.session} - immediate wake failed` };
+        }
+        if (!pidAlive(first.pid)) {
+            return { ok: false, error: `opencode-headless turn wrapper died before reporting an outcome for session ${rec.session} - immediate wake failed` };
+        }
+        await sleep(OUTCOME_POLL_MS);
+        const settled = readTurnOutcome(outcomePath);
+        if (settled?.state === 'exit')
+            return turnExited(rec, settled);
+        if (settled?.state !== 'running' || settled.pid !== first.pid || !pidAlive(settled.pid)) {
+            return { ok: false, error: `opencode-headless turn did not remain live through startup for session ${rec.session} - immediate wake failed` };
+        }
+        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}` };
+    }
+    finally {
+        rmSync(outcomeDir, { recursive: true, force: true });
+    }
+}

package/dist/opencode.d.ts

@@ -0,0 +1,3 @@
+export declare const OPENCODE_EVENTS: readonly ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"];
+export declare const OPENCODE_TOOL_NAMES: Record<string, string>;
+export declare function opencodePluginSource(dispatch: string, spex: string): string;

package/dist/opencode.js

@@ -0,0 +1,142 @@
+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'];
+// 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 = {
+    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, spex) {
+    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 shared rendezvous server receives best-effort reply pokes. An unadopted plugin simply leaves the
+  // timeline line for its next turn boundary; the SDK injection remains host-owned.
+  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)
+        // Start the Stop dispatch now, but RETURN this idle callback before a blocked verdict injects its
+        // follow-up turn. Awaiting client.session.prompt here re-enters opencode before it has published the
+        // just-finished assistant text: the continuation can declare success while the requested final answer
+        // disappears. This is opencode host scheduling, not shared dispatchStop semantics (pi correctly awaits
+        // its agent_end continuation). dispatchStop catches inject failures; this final catch keeps substrate
+        // failures loud without throwing them into opencode after the event callback has returned.
+        void rt.dispatchStop((reason) => injectPrompt(reason), "blocked by a spexcode hook")
+          .catch((e) => console.error("spexcode: Stop dispatch failed: " + String(e)))
+      }
+    },
+    "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/dist/pi-harness.d.ts

@@ -0,0 +1,3 @@
+export declare function piExtensionSource(dispatch: string, spex: string): string;
+export declare function writePiTrust(proj: string): string;
+export declare function removePiTrust(proj: string): void;

package/dist/pi-harness.js

@@ -0,0 +1,129 @@
+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, spex) {
+    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) => { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} };
+function readTrust(file) {
+    if (!existsSync(file))
+        return {};
+    const raw = readFileSync(file, 'utf8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON — refusing to rewrite pi's trust store: ${String(e)}`);
+    }
+}
+export function writePiTrust(proj) {
+    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) {
+    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');
+}

package/dist/pi-headless.d.ts

@@ -0,0 +1,25 @@
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js';
+/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
+export declare const piHeadlessSock: (id: string) => string;
+export declare function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string;
+export declare const deliverViaPiHeadless: (rec: HarnessDeliveryRecord, text: string) => Promise<DispatchResult>;
+export declare function piHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
+export declare class PiHeadlessController {
+    private readonly id;
+    private readonly piCmd;
+    private readonly cwd;
+    private server;
+    private child;
+    private controlQueue;
+    private closing;
+    private readonly socketPath;
+    constructor(id: string, _runtimeDir: string, piCmd: string, cwd?: string);
+    start(initialPrompt?: string): Promise<void>;
+    close(): Promise<void>;
+    private terminateTurn;
+    private waitForExit;
+    private accept;
+    private handle;
+    private spawnTurn;
+}
+export declare function runPiHeadlessController(id: string, runtimeDir: string, piCmd: string, tail: string[]): Promise<void>;