spexcode 0.6.1 → 0.6.5

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

@@ -1,205 +0,0 @@
-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, type DispatchResult, type HarnessDeliveryRecord } 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: number) => new Promise((resolve) => setTimeout(resolve, ms))
-
-function accountLoginShell(): string {
-  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: string, outcomePath?: string): string {
-  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: string): string[] {
-  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'): 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,
-  outcomePath?: 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'), outcomePath)
-}
-
-type TurnOutcome =
-  | { state: 'running'; pid: number }
-  | { state: 'reporting'; pid: number; code: number }
-  | { state: 'exit'; code: number; casCode: number }
-  | { state: 'invalid' }
-
-function readTurnOutcome(path: string): TurnOutcome | undefined {
-  let value: string
-  try { value = readFileSync(path, 'utf8').trim() } catch (error) {
-    if ((error as NodeJS.ErrnoException).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: HarnessDeliveryRecord, outcome: Extract<TurnOutcome, { state: 'exit' }>): DispatchResult {
-  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: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try { process.kill(pid, 0); return true } catch (error) {
-    return (error as NodeJS.ErrnoException).code === 'EPERM'
-  }
-}
-
-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` }
-  let outcomeDir: string
-  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 as 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/spec-cli/src/pi-headless.ts

@@ -1,153 +0,0 @@
-import { createServer, type Server, type Socket } from 'node:net'
-import { spawn, type ChildProcess } 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 type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
-import { controlRequest, withTimeout } from './headless-controller.js'
-import { shQuote } from './sh.js'
-
-type ControlRequest = { type: 'deliver'; text: string; mid?: string }
-type ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
-
-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
-
-/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
-export const piHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ph-${id}.sock`)
-
-export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string {
-  return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ')
-}
-
-export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
-  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',
-  })
-
-export class PiHeadlessController {
-  private server: Server | null = null
-  private child: ChildTurn | null = null
-  private controlQueue: Promise<void> = Promise.resolve()
-  private closing = false
-  private readonly socketPath: string
-
-  constructor(
-    private readonly id: string,
-    _runtimeDir: string,
-    private readonly piCmd: string,
-    private readonly cwd = process.cwd(),
-  ) {
-    this.socketPath = piHeadlessSock(id)
-  }
-
-  async start(initialPrompt?: string): Promise<void> {
-    try { rmSync(this.socketPath, { force: true }) } catch { /* stale control socket is replaced at startup */ }
-    this.server = createServer((socket) => this.accept(socket))
-    await new Promise<void>((resolve, reject) => {
-      const onError = (error: 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 as Error).message}`)
-    })
-  }
-
-  async close(): Promise<void> {
-    if (this.closing) return
-    this.closing = true
-    const child = this.child
-    if (child && child.process.exitCode === null) child.process.kill('SIGTERM')
-    await new Promise<void>((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))
-  }
-
-  private accept(socket: Socket): void {
-    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: ControlRequest
-      try { request = JSON.parse(buffer.slice(0, nl)) as ControlRequest } catch (error) {
-        socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${(error as Error).message}` })}\n`)
-        return
-      }
-      this.controlQueue = this.controlQueue.then(async () => {
-        const result = await this.handle(request).catch((error) => ({ ok: false, error: (error as Error).message }))
-        socket.end(`${JSON.stringify(result)}\n`)
-      })
-    })
-  }
-
-  private async handle(request: ControlRequest): Promise<DispatchResult> {
-    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`)
-  }
-
-  private async spawnTurn(text: string, resume: boolean): Promise<void> {
-    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!: (code: number | null) => void
-    const exited = new Promise<number | null>((resolve) => { resolveExit = resolve })
-    const turn: ChildTurn = { 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<void>((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: string, runtimeDir: string, piCmd: string, tail: string[]): Promise<void> {
-  // 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<void>((resolve) => {
-    const stop = () => void controller.close().finally(resolve)
-    process.once('SIGINT', stop)
-    process.once('SIGTERM', stop)
-    process.once('SIGHUP', stop)
-  })
-}

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

@@ -1,157 +0,0 @@
-import { mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { copyFileIfChanged, writeFileIfChanged } from './file-write.js'
-
-// @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
-// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
-// `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
-// write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
-// materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
-// (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
-// `.zcode-plugin > .claude-plugin > .codex-plugin` and z-code/Claude both read a `.claude-plugin` directly, so
-// the ONE `.claude-plugin` bundle reaches ZCode, Claude, and (future) Codex from a single emit.
-//
-// The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
-// files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
-// injection Claude/z-code normalize, the superpowers pattern), so a plugin host gets the contract with no
-// --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
-// ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
-// (harness.sh) parses payloads as the claude family (z-code/Claude share Claude's tool names + file_path).
-
-const PKG = fileURLToPath(new URL('..', import.meta.url))   // installed spec-cli root
-const HOOKS_SRC = join(PKG, 'hooks')                        // the canonical dispatch.sh + harness.sh source
-const PLUGIN_NAME = 'spexcode'
-// the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
-// (the same variable z-code's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
-// where the host scanned the bundle from.
-const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
-// the lifecycle events the bundle binds — the Claude/z-code superset; a host that fires fewer (Codex) simply
-// never invokes the extras, so binding all is harmless and one emit serves every host.
-const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
-
-// the gathered surface artifacts this materialize writes into the bundle. contract = the assembled guide+system
-// block (the SAME string the native path folds into CLAUDE.md, here delivered as additionalContext); skills/
-// agents/commands are the already-materialized file CONTENTS (reusing materialize's skillArtifact/agentArtifact),
-// keyed
-// by node name; spex is the baked tsx+cli invocation the dispatcher gate calls; version stamps plugin.json.
-export type PluginBundle = {
-  contract: string
-  skills: { name: string; content: string }[]
-  agents: { name: string; content: string }[]
-  commands: { name: string; content: string }[]
-  spex: string
-  version: string
-}
-
-// the bundle dir for a plugin folder: <proj>/<folder>/plugins/spexcode — `<folder>` is the host's plugins-scan
-// root ([[harness-select]] requires it explicit), `plugins/<name>` the conventional bundle location under it.
-export function pluginBundleDir(proj: string, folder: string): string {
-  return join(proj, folder, 'plugins', PLUGIN_NAME)
-}
-
-// the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
-// the component pointers Claude/z-code discover (hooks.json + the skills/commands/agents dirs).
-function pluginManifest(version: string): string {
-  return JSON.stringify({
-    name: PLUGIN_NAME,
-    version,
-    description: 'SpexCode — spec-driven dev-flow contract, hooks, skills, commands & agents as one self-contained plugin.',
-    hooks: './hooks/hooks.json',
-    commands: './commands',
-    agents: './agents',
-    skills: './skills',
-  }, null, 2)
-}
-
-// hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
-// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
-// ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
-function pluginHooksJson(spex: string): string {
-  const dispatch = (e: string) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`
-  const inject = `bash "${PLUGIN_ROOT}/hooks/inject-contract.sh"`
-  const hooks: Record<string, unknown> = {}
-  for (const e of PLUGIN_EVENTS) {
-    const cmds = e === 'SessionStart'
-      ? [{ type: 'command', command: inject }, { type: 'command', command: dispatch(e) }]
-      : [{ type: 'command', command: dispatch(e) }]
-    hooks[e] = [{ hooks: cmds }]
-  }
-  return JSON.stringify({ hooks }, null, 2)
-}
-
-// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at materialize time,
-// so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
-function contractContextJson(contract: string): string {
-  return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2)
-}
-
-// the SessionStart contract injector: print the pre-encoded additionalContext payload (the harness-neutral
-// stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
-const INJECT_SH = `#!/usr/bin/env bash
-# Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
-# superpowers pattern; Claude/z-code normalize hookSpecificOutput.additionalContext) that replaces a plugin
-# host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
-here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-[ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
-exit 0
-`
-
-// emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
-export function emitPlugin(proj: string, folder: string, r: PluginBundle): void {
-  const bundle = pluginBundleDir(proj, folder)
-  const meta = join(bundle, '.claude-plugin')
-  const hooksDir = join(bundle, 'hooks')
-  mkdirSync(meta, { recursive: true })
-  mkdirSync(hooksDir, { recursive: true })
-  writeFileIfChanged(join(meta, 'plugin.json'), pluginManifest(r.version))
-  // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
-  // injector + its pre-encoded payload, and the event→dispatch binding.
-  copyFileIfChanged(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
-  copyFileIfChanged(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
-  writeFileIfChanged(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
-  writeFileIfChanged(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
-  writeFileIfChanged(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
-  // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
-  reconcileBundleDirectory(join(bundle, 'skills'), new Set(r.skills.map((s) => s.name)))
-  reconcileBundleDirectory(join(bundle, 'agents'), new Set(r.agents.map((a) => `${a.name}.md`)))
-  reconcileBundleDirectory(join(bundle, 'commands'), new Set(r.commands.map((c) => `${c.name}.md`)))
-  for (const s of r.skills) writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content)
-  for (const a of r.agents) writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content)
-  for (const c of r.commands) writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content)
-}
-
-function reconcileBundleDirectory(dir: string, expectedNames: ReadonlySet<string>): void {
-  if (!existsSync(dir)) return
-  for (const entry of readdirSync(dir)) {
-    if (!expectedNames.has(entry)) rmSync(join(dir, entry), { recursive: true, force: true })
-  }
-}
-
-function writeBundleFile(f: string, content: string): void {
-  mkdirSync(dirname(f), { recursive: true })
-  writeFileIfChanged(f, content)
-}
-
-// the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the
-// previously-emitted folders and cleans any the current set dropped, e.g. switching plugin→native or folder A→B).
-// Identity-gated on the bundle's own plugin.json `name`, so it removes ONLY a spexcode bundle, never a folder
-// the user populated with another plugin.
-export function cleanPlugin(proj: string, folder: string): void {
-  const bundle = pluginBundleDir(proj, folder)
-  const manifest = join(bundle, '.claude-plugin', 'plugin.json')
-  if (!existsSync(manifest)) return
-  try {
-    if (String(JSON.parse(readFileSync(manifest, 'utf8'))?.name) !== PLUGIN_NAME) return
-  } catch { return }
-  rmSync(bundle, { recursive: true, force: true })
-}
-
-// the bundle version stamped into plugin.json — the monorepo root `spexcode` package version (the published
-// artifact's version), falling back to the spec-cli package, then 0.0.0.
-export function pluginVersion(): string {
-  for (const p of [join(PKG, '..', 'package.json'), join(PKG, 'package.json')]) {
-    try { const v = JSON.parse(readFileSync(p, 'utf8'))?.version; if (v) return String(v) } catch { /* keep trying */ }
-  }
-  return '0.0.0'
-}