spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/{spec-cli/src/opencode.ts → node_modules/@spexcode/spec-cli/dist/opencode.js}

@@ -1,5 +1,4 @@
-import { shimRuntimeSource } from './shim-runtime.js'
-
+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
@@ -15,26 +14,23 @@ import { shimRuntimeSource } from './shim-runtime.js'
 // 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
-
+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: 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',
-}
-
+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: string, spex: string): string {
-  return `// spexcode: GENERATED by spex materialize — do not edit (regenerated per clone; see [[opencode-harness]])
+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"
@@ -142,5 +138,5 @@ export const SpexcodePlugin = async (ctx) => {
     },
   }
 }
-`
+`;
 }

package/node_modules/@spexcode/spec-cli/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/{spec-cli/src/pi-harness.ts → node_modules/@spexcode/spec-cli/dist/pi-harness.js}

@@ -1,14 +1,12 @@
-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'
-
+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
@@ -25,8 +23,8 @@ import { shimRuntimeSource } from './shim-runtime.js'
 // 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)
+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"
@@ -75,9 +73,8 @@ export default function spexcode(pi: ExtensionAPI) {
   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
@@ -87,38 +84,46 @@ export default function spexcode(pi: ExtensionAPI) {
 // 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')
+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)}`)
-  }
+const canonical = (p) => { try {
+    return realpathSync(p);
 }
-
-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
+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 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')
+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/node_modules/@spexcode/spec-cli/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>;

package/node_modules/@spexcode/spec-cli/dist/pi-headless.js

@@ -0,0 +1,196 @@
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { controlRequest, withTimeout } from './headless-controller.js';
+import { shQuote } from './sh.js';
+const PKG = fileURLToPath(new URL('..', import.meta.url));
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+const CONTROL_TIMEOUT_MS = 30_000;
+const START_TIMEOUT_MS = 30_000;
+const TERM_EXIT_GRACE_MS = 500;
+const KILL_EXIT_GRACE_MS = 2_000;
+/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
+export const piHeadlessSock = (id) => join(tmpdir(), `spexcode-ph-${id}.sock`);
+export function piHeadlessLaunchCommand(id, runtimeDir, piCmd) {
+    return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ');
+}
+export const deliverViaPiHeadless = (rec, text) => controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text, mid: rec.mid }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the request',
+});
+// The resident controller and a running pi turn own two per-session listeners. The generic lifecycle
+// teardown has already proved and removed the exact controller leaf before this runs; cold filing is valid
+// only once neither listener can still accept work for this session.
+export async function piHeadlessColdRuntime(rec) {
+    const { listenerAt, rvSock } = await import('./harness.js');
+    const paths = [piHeadlessSock(rec.session), rvSock(rec.session)];
+    const probes = await Promise.all(paths.map((path) => listenerAt(path)));
+    const pending = paths.filter((_, index) => probes[index] !== 'dead');
+    return pending.length
+        ? { ok: false, error: `pi-headless runtime is still ${probes.some((probe) => probe === 'live') ? 'live' : 'unproven'} (${pending.join(', ')})` }
+        : { ok: true };
+}
+export class PiHeadlessController {
+    id;
+    piCmd;
+    cwd;
+    server = null;
+    child = null;
+    controlQueue = Promise.resolve();
+    closing = false;
+    socketPath;
+    constructor(id, _runtimeDir, piCmd, cwd = process.cwd()) {
+        this.id = id;
+        this.piCmd = piCmd;
+        this.cwd = cwd;
+        this.socketPath = piHeadlessSock(id);
+    }
+    async start(initialPrompt) {
+        try {
+            rmSync(this.socketPath, { force: true });
+        }
+        catch { /* stale control socket is replaced at startup */ }
+        this.server = createServer((socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            const onError = (error) => { this.server?.off('listening', onListening); reject(error); };
+            const onListening = () => { this.server?.off('error', onError); resolve(); };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(this.socketPath);
+        });
+        if (initialPrompt)
+            void this.spawnTurn(initialPrompt, false).catch((error) => {
+                console.error(`[spex pi-headless] initial turn failed: ${error.message}`);
+            });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const child = this.child;
+        try {
+            if (child)
+                await this.terminateTurn(child);
+        }
+        finally {
+            await new Promise((resolve) => {
+                if (!this.server)
+                    return resolve();
+                this.server.close(() => resolve());
+            });
+            // same proof-before-removal rule as every other teardown (harness.ts unlinkSocks): a socket path is keyed
+            // by session id alone, so only a listener PROVEN dead is ours to unlink.
+            const { rvSock, unlinkSocks } = await import('./harness.js');
+            await unlinkSocks(this.socketPath, rvSock(this.id));
+        }
+    }
+    async terminateTurn(turn) {
+        if (turn.process.exitCode !== null)
+            return;
+        try {
+            turn.process.kill('SIGTERM');
+        }
+        catch { /* the child can leave between the exit check and signal */ }
+        if (await this.waitForExit(turn, TERM_EXIT_GRACE_MS))
+            return;
+        try {
+            turn.process.kill('SIGKILL');
+        }
+        catch { /* already gone */ }
+        await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `pi-headless turn did not exit for session ${this.id}`);
+    }
+    async waitForExit(turn, timeoutMs) {
+        try {
+            await withTimeout(turn.exited, timeoutMs, 'turn exit grace elapsed');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    accept(socket) {
+        socket.setEncoding('utf8');
+        let buffer = '';
+        let handled = false;
+        socket.on('data', (chunk) => {
+            if (handled)
+                return;
+            buffer += chunk;
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            handled = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, nl));
+            }
+            catch (error) {
+                socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${error.message}` })}\n`);
+                return;
+            }
+            this.controlQueue = this.controlQueue.then(async () => {
+                const result = await this.handle(request).catch((error) => ({ ok: false, error: error.message }));
+                socket.end(`${JSON.stringify(result)}\n`);
+            });
+        });
+    }
+    async handle(request) {
+        if (request.type !== 'deliver')
+            return { ok: false, error: 'unknown pi-headless control request' };
+        if (!request.text)
+            return { ok: false, error: 'empty prompt - nothing to deliver' };
+        // A live extension listener is an in-flight pi turn. Only a proven absent listener may cold-wake a saved
+        // session; an inconclusive probe must not start a duplicate turn.
+        const { deliverViaSocketOrWake } = await import('./harness.js');
+        return deliverViaSocketOrWake(this.id, request.text, request.mid, async () => {
+            if (this.child)
+                await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`);
+            await this.spawnTurn(request.text, true);
+            return { ok: true };
+        }, `could not determine whether pi turn ${this.id} is live — prompt NOT delivered`);
+    }
+    async spawnTurn(text, resume) {
+        if (this.closing)
+            throw new Error('pi-headless controller is closing');
+        const mode = resume ? ['--session', this.id] : ['--session-id', this.id];
+        // Keep pi's default text mode. `--mode json` is intentionally omitted: it can hang in this runtime.
+        const args = ['-p', ...mode, text];
+        const command = `exec ${this.piCmd} ${args.map(shQuote).join(' ')}`;
+        const childProcess = spawn('/bin/sh', ['-lc', command], { cwd: this.cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        const turn = { process: childProcess, exited };
+        this.child = turn;
+        childProcess.stdout?.pipe(process.stdout);
+        childProcess.stderr?.pipe(process.stderr);
+        childProcess.once('error', (error) => console.error(`[spex pi-headless] child spawn failed: ${error.message}`));
+        childProcess.once('close', (code) => {
+            if (this.child === turn)
+                this.child = null;
+            resolveExit(code);
+            if (code !== 0 && !this.closing)
+                void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'pi-headless', code, this.cwd));
+        });
+        await withTimeout(new Promise((resolve, reject) => {
+            childProcess.once('spawn', () => resolve());
+            childProcess.once('error', reject);
+        }), START_TIMEOUT_MS, `pi-headless child did not start for session ${this.id}`);
+    }
+}
+export async function runPiHeadlessController(id, runtimeDir, piCmd, tail) {
+    // runtimeDir is retained in the command shape for parity with claude-headless and future per-session output.
+    mkdirSync(join(runtimeDir, 'sessions', id), { recursive: true });
+    const controller = new PiHeadlessController(id, runtimeDir, piCmd);
+    const resume = tail[0] === '--session';
+    const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ');
+    await controller.start(prompt);
+    await new Promise((resolve) => {
+        const stop = () => void controller.close().finally(resolve);
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        process.once('SIGHUP', stop);
+    });
+}

package/node_modules/@spexcode/spec-cli/dist/plugin-harness.d.ts

@@ -0,0 +1,21 @@
+export type PluginBundle = {
+    contract: string;
+    skills: {
+        name: string;
+        content: string;
+    }[];
+    agents: {
+        name: string;
+        content: string;
+    }[];
+    commands: {
+        name: string;
+        content: string;
+    }[];
+    spex: string;
+    version: string;
+};
+export declare function pluginBundleDir(proj: string, folder: string): string;
+export declare function emitPlugin(proj: string, folder: string, r: PluginBundle): void;
+export declare function cleanPlugin(proj: string, folder: string): void;
+export declare function pluginVersion(): string;