spexcode 0.6.1 → 0.6.5

package/spec-cli/src/supervise.ts

@@ -1,245 +0,0 @@
-// SO_REUSEPORT is ENOTSUP on macOS/Node, so the supervisor owns the public port as a raw-TCP proxy and
-// runs the Hono server as a child on a private port (raw piping carries WS upgrades too).
-import net from 'node:net'
-import http from 'node:http'
-import { randomUUID } from 'node:crypto'
-import { spawn, type ChildProcess } from 'node:child_process'
-import type { Dirent } from 'node:fs'
-import { stat, readdir } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
-import { installProcessGuards } from './resilience.js'
-import { listenOrExit } from './listen.js'
-import { resolvePublicConfig, startGateway, ensureDashboardBuilt, resolveDistDir } from './gateway.js'
-import { tsxBin } from './tsx-bin.js'
-import { publishEndpoint, dropOwnEndpoint } from './host.js'
-import { repoRoot as servedRepoRoot } from './git.js'
-import { resolveProjectIdentity } from './project-identity.js'
-import { startResourceMonitor } from './host-resources.js'
-import { registerBackendInstance, unregisterBackendInstance } from './runtime-ownership.js'
-import { sessionIdentityEnvVars } from './harness.js'
-
-// the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
-// logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
-installProcessGuards()
-
-const here = dirname(fileURLToPath(import.meta.url))
-const tsx = tsxBin(join(here, '..'))   // tsx's JS entry (dist/cli.mjs), run via `node` below — dev or published
-const entry = join(here, 'index.ts')                          // the real Hono server
-const publicPort = Number(process.env.PORT || 8787)
-
-// @@@ public mode ([[public-mode]]) - with `spex serve --public`, the supervisor is NOT the internet face:
-// the gateway is. The raw-TCP proxy retreats to a loopback internal port (the trusted boundary local agents
-// reach) and the password-gated TLS gateway takes the public port, proxying /api + WS back to that loopback
-// port. Off → unchanged: the proxy itself owns the public port and SPEXCODE_API_URL points there.
-const publicCfg = resolvePublicConfig(join(here, '..', '..'))
-// the port the raw-TCP proxy actually binds: a private loopback port in public mode, the public port otherwise.
-const proxyPort = publicCfg ? await freePort() : publicPort
-// what launched agents inherit as their `spex` endpoint — ALWAYS the loopback proxy, so local agents never
-// meet the password gate (loopback is the trust boundary). Equals the public port when public mode is off.
-const childApiBase = `http://127.0.0.1:${proxyPort}`
-
-// every package src tree the child imports at runtime; spec-dashboard is absent (its own vite/HMR).
-const repoRoot = join(here, '..', '..')
-const watchRoots = [
-  here,                                  // spec-cli/src — the backend's own source
-  join(repoRoot, 'spec-forge', 'src'),
-  join(repoRoot, 'spec-eval', 'src'),
-]
-
-// @@@ instance identity - one id for this serve's whole lifetime, minted at supervisor start and handed to
-// every child via env, so the endpoint record and the live backend answer with the SAME identity across
-// zero-downtime reloads. The host gateway ([[host-gateway]]) validates a record by comparing this id (and the
-// served root) against the live /api/instance answer — a recycled port serving a DIFFERENT project or a
-// different serve generation fails the match and is treated as offline, never proxied to.
-const instanceId = randomUUID()
-const projectRoot = servedRepoRoot() // the actual git tree whose source/spec/config the child serves
-// A backend is a project control plane, never the session that happened to invoke `spex serve`. Strip every
-// adapter identity before any hot child is spawned; otherwise all backend work is falsely charged to that
-// caller long after its session ends.
-for (const key of sessionIdentityEnvVars()) delete process.env[key]
-process.env.SPEXCODE_PROJECT_ROOT = projectRoot
-process.env.SPEXCODE_INSTANCE_ID = instanceId
-registerBackendInstance(instanceId, process.pid, projectRoot)
-
-type Backend = { port: number; child: ChildProcess }
-let current: Backend | null = null   // which internal port new proxy connections forward to
-let reloading = false                // single-flight guard for reload()
-let pending = false                  // a code change arrived mid-reload → reload again when done
-
-// grab an ephemeral port by binding :0, then release it for the child to claim (negligible rebind race).
-function freePort(): Promise<number> {
-  return new Promise((res, rej) => {
-    const s = net.createServer()
-    s.once('error', rej)
-    s.listen(0, '127.0.0.1', () => { const p = (s.address() as net.AddressInfo).port; s.close(() => res(p)) })
-  })
-}
-
-// poll GET /health until 200; ~15s budget (150 × 100ms) covers a slow tsx+Hono cold start. False → keep old.
-function waitHealthy(port: number, tries = 150): Promise<boolean> {
-  return new Promise((resolve) => {
-    const retry = (left: number) => { if (left <= 1) resolve(false); else setTimeout(() => attempt(left - 1), 100) }
-    const attempt = (left: number) => {
-      const req = http.get({ host: '127.0.0.1', port, path: '/health', timeout: 1000 }, (r) => {
-        r.resume()
-        if (r.statusCode === 200) resolve(true); else retry(left)
-      })
-      req.on('error', () => retry(left))
-      req.on('timeout', () => { req.destroy(); retry(left) })
-    }
-    attempt(tries)
-  })
-}
-
-// boot a fresh backend child on a free internal port and wait until it's serving.
-async function boot(): Promise<Backend | null> {
-  const port = await freePort()
-  // PORT pins the child's PRIVATE bind port; SPEXCODE_API_URL pins everything the child SPAWNS (launched
-  // sessions + their hooks) at the PUBLIC port, so a launched agent's own `spex` reaches the stable proxy
-  // and never inherits this ephemeral, soon-retired port. ALWAYS childApiBase, never the ambient
-  // process.env.SPEXCODE_API_URL: the env this serve itself inherited may carry ANOTHER project's backend
-  // (the exact misroute [[remote-client]]'s ladder exists to kill), and a worker's env is its routing
-  // LIFELINE — it must be a deterministic backend-injected fact, not an inheritance gamble.
-  const child = spawn(process.execPath, [tsx, entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase, SPEXCODE_INSTANCE_ID: instanceId } })
-  // if the ACTIVE backend dies unexpectedly (crash, OOM), restart it so the public port keeps serving.
-  // Planned retirement sets current to the NEW child first, so the old child's exit fails this identity
-  // check and is ignored. boot()'s ~5s health budget rate-limits any crash loop.
-  child.on('exit', (code, sig) => {
-    if (current?.child === child) { console.error(`[supervisor] active backend exited (${code ?? sig}) — restarting`); current = null; void reload('crash') }
-  })
-  if (await waitHealthy(port)) return { port, child }
-  try { child.kill('SIGKILL') } catch { /* already gone */ }
-  return null
-}
-
-// boot → health-gate → atomic flip → drain old. The flip is a single assignment; the old child is killed
-// only after a drain delay, so a connection mid-flip is never refused.
-async function reload(reason: string): Promise<void> {
-  if (reloading) { pending = true; return }
-  reloading = true
-  try {
-    do {
-      pending = false
-      const next = await boot()
-      if (!next) { console.error(`[supervisor] new backend failed health check (${reason}) — keeping current`); break }
-      const old = current
-      current = next   // atomic flip: new connections now route to `next`
-      console.log(`[supervisor] reloaded (${reason}) → backend :${next.port}`)
-      if (old) setTimeout(() => { try { old.child.kill('SIGTERM') } catch { /* already gone */ } }, 500)
-    } while (pending)
-  } finally { reloading = false }
-}
-
-// the public port: a raw byte pipe to the current backend. Works for HTTP and WS upgrades alike.
-// @@@ connection reaping ([[spec-cli]]) - a raw TCP proxy must tear down the PAIR when EITHER end goes, or it
-// leaks the still-open half. The wedge that started the mass-restore incident was exactly this: every
-// client-side timeout-kill left the client's UPSTREAM socket half-open to the child (the old handler bailed
-// only on `error`, so a clean FIN / a silent drop never reaped the upstream) — 135 leaked conns piled on the
-// child and it looked dead. So a close on either side destroys BOTH (idempotent). The abandoned-but-silent
-// case (no FIN/RST ever arrives) is reaped from the CHILD instead — its socket-level reaper (reaper.ts)
-// destroys an idle/stalled socket, whose close then propagates here — so an active WS/SSE (not idle
-// keep-alive) is never mistaken for abandoned and cut.
-const proxy = net.createServer((client) => {
-  const target = current
-  if (!target) { client.destroy(); return }
-  const up = net.connect(target.port, '127.0.0.1')
-  client.setNoDelay(true); up.setNoDelay(true)   // proxy a request promptly — don't let Nagle add latency
-  const bail = () => { client.destroy(); up.destroy() }
-  client.on('error', bail); up.on('error', bail)
-  client.once('close', () => up.destroy())   // client abandoned → reap its upstream (THE leak that wedged :8787); nothing left to flush to a gone client
-  // upstream gone → drop the client half, but ONLY force it when the close was ABNORMAL: on a normal FIN,
-  // `up.pipe(client)` has already called `client.end()` (writableEnded), so let the client flush the last of a
-  // large response (e.g. /api/graph) rather than truncate it with a destroy; a crash/half-open close (no prior
-  // end) still gets reaped.
-  up.once('close', () => { if (!client.writableEnded) client.destroy() })
-  client.pipe(up); up.pipe(client)
-})
-
-// @@@ endpoint record - this project's live backend endpoint, published into the per-project runtime tier
-// (~/.spexcode/projects/<enc>/backend.json) only AFTER the public bind succeeds. It's what lets a bare
-// `spex` run from this project's tree find ITS OWN backend instead of an env URL inherited from another
-// project's ([[remote-client]]'s resolution ladder), and what the host gateway ([[host-gateway]]) reconciles
-// its project list from. The write is ATOMIC (tmp + rename) and carries the serve's actual git toplevel +
-// resolved identity — so a reader can VALIDATE the record against the live /api/instance answer,
-// never just trust a URL. Readers health-probe before trusting, so a crashed serve leaves at worst a dead
-// record that is ignored — never followed. The recorded URL is the LOOPBACK face local agents reach (equals
-// the public port when public mode is off), never the password-gated gateway. A linked worktree therefore
-// gets its own encoded slot and can never overwrite the main checkout's endpoint.
-function recordEndpoint(url: string): void {
-  try {
-    publishEndpoint({
-      version: 2,
-      url,
-      pid: process.pid,
-      instanceId,
-      root: projectRoot,
-      identity: resolveProjectIdentity(projectRoot, projectRoot),
-      startedAt: new Date().toISOString(),
-    })
-  } catch (e) {
-    console.error(`[supervisor] could not record the backend endpoint (${(e as Error).message}) — cwd-based \`spex\` discovery won't find this backend`)
-  }
-}
-// best-effort removal on a clean stop, only if the record is OURS — matched by instanceId, so a newer serve
-// that already overwrote the record (or another project's) is never deleted by a retiring one.
-function dropEndpoint(): void {
-  try { dropOwnEndpoint(instanceId, projectRoot) } catch { /* not ours / already gone */ }
-}
-
-const shutdown = () => { dropEndpoint(); unregisterBackendInstance(instanceId); try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
-process.on('SIGINT', shutdown)
-process.on('SIGTERM', shutdown)
-
-const first = await boot()
-if (!first) { console.error('[supervisor] initial backend failed to start'); process.exit(1) }
-current = first
-// reap the booted child if a port bind fails, so a "can't own my port → exit" never leaves a zombie child.
-// SIGTERM (not SIGKILL): the child is a `tsx` wrapper around the real node server — SIGKILL kills the wrapper
-// instantly and ORPHANS the server still bound to its port, whereas tsx FORWARDS SIGTERM to it (the same
-// signal the reload drain uses). Sent synchronously here, before the process.exit that follows.
-const reapChild = () => { unregisterBackendInstance(instanceId); try { current?.child.kill('SIGTERM') } catch { /* already gone */ } }
-if (publicCfg) {
-  // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
-  const distDir = resolveDistDir() // bundled <pkg>/dashboard-dist when installed, else monorepo spec-dashboard/dist
-  ensureDashboardBuilt(repoRoot, distDir)
-  listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`) } })
-  startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild })
-} else {
-  listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`) } })
-}
-startResourceMonitor()
-
-// watch every imported source tree; debounce a burst of writes (a merge touching several files across
-// packages) into one reload. A root that can't be watched (a package absent in some checkout) is logged
-// and skipped — the supervisor owns the public port and must never die over a missing watch.
-// fs.watch — even recursive — is NOT reliable for a long-lived supervisor: its inotify watches are silently
-// dropped when a watched dir is rewritten (a git merge, a `materialize`) and NEVER re-established, so reloads
-// quietly stop (observed: the watcher fired a few times then went deaf for hours). A cheap mtime poll can't go
-// deaf: every 2s, take the newest .ts/.js/.json mtime across the trees; a jump triggers the debounced reload
-// (a burst of writes still lands as one). Polling a few small src trees is negligible cost.
-let timer: NodeJS.Timeout | undefined
-const newestMtime = async (dir: string): Promise<number> => {
-  let max = 0
-  let entries: Dirent[]
-  try { entries = await readdir(dir, { withFileTypes: true }) } catch { return 0 }   // a tree absent in some checkout → skip
-  for (const e of entries) {
-    if (e.isDirectory()) { if (e.name !== 'node_modules') max = Math.max(max, await newestMtime(join(dir, e.name))) }
-    else if (/\.(ts|js|mjs|json)$/.test(e.name)) { try { max = Math.max(max, (await stat(join(dir, e.name))).mtimeMs) } catch { /* raced unlink */ } }
-  }
-  return max
-}
-const scanMtime = async (): Promise<number> => {
-  let m = 0
-  for (const root of watchRoots) m = Math.max(m, await newestMtime(root))
-  return m
-}
-let lastMtime = await scanMtime()   // baseline at boot — only a LATER change reloads
-let scanning = false
-setInterval(() => {
-  if (scanning) return
-  scanning = true
-  void scanMtime().then((m) => {
-    if (m > lastMtime) { lastMtime = m; clearTimeout(timer); timer = setTimeout(() => void reload('code change'), 150) }
-  }).finally(() => { scanning = false })
-}, 2000).unref()

package/spec-cli/src/tree.ts

@@ -1,118 +0,0 @@
-// @@@ spex graph - the CLI's human-readable graph view: the same assembled board the dashboard's
-// tidy-tree renders, as an indented terminal tree. Pure presentation over buildBoard()'s nodes —
-// no read path of its own; status colours and badge semantics mirror the dashboard (drift /
-// stale-eval / open-issues counts). Governed by the spex-tree spec node.
-
-// the subset of a board node this view consumes (buildBoard attaches more; we read only these).
-export type TreeNode = {
-  id: string
-  parent: string | null
-  title: string
-  status: string
-  version?: number
-  drift?: number
-  ghost?: boolean
-  reviewSummary?: {
-    issues?: { open: number }
-    evals?: { stalePass: number; staleFail: number }
-  }
-}
-
-export type TreeOpts = { node?: string; depth?: number; color?: boolean }
-
-// dashboard status palette mapped onto ANSI: merged=green, active=cyan (live/in-flight, distinct
-// from the warning yellow), drift=yellow (the dashboard's warning colour), pending=muted grey.
-const STATUS_ANSI: Record<string, string> = { merged: '32', active: '36', drift: '33', pending: '90' }
-
-// stale-eval count: declared scenarios whose LATEST reading exists but is no longer fresh.
-// board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
-// axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
-function staleYatsu(n: TreeNode): number {
-  const summary = n.reviewSummary?.evals
-  return summary ? summary.stalePass + summary.staleFail : 0
-}
-
-function childrenIndex(nodes: TreeNode[]): Map<string | null, TreeNode[]> {
-  const byParent = new Map<string | null, TreeNode[]>()
-  for (const n of nodes) {
-    const list = byParent.get(n.parent) ?? []
-    list.push(n)
-    byParent.set(n.parent, list)
-  }
-  return byParent
-}
-
-// resolve the display roots: --node picks one subtree; default is the forest of parentless nodes
-// (a node whose parent id isn't on the board — a ghost mid-add, say — surfaces as a root rather
-// than vanishing). Unknown --node throws (fail loud, caller prints + exits 2), never an empty tree.
-function roots(nodes: TreeNode[], nodeId?: string): TreeNode[] {
-  if (nodeId) {
-    const hit = nodes.find((n) => n.id === nodeId)
-    if (!hit) throw new Error(`no spec node "${nodeId}" — spex graph lists every id; spex spec search <topic> finds one by intent`)
-    return [hit]
-  }
-  const ids = new Set(nodes.map((n) => n.id))
-  return nodes.filter((n) => n.parent === null || !ids.has(n.parent))
-}
-
-export function renderTree(nodes: TreeNode[], opts: TreeOpts = {}): string {
-  const color = opts.color ?? false
-  const c = (code: string, t: string) => (color ? `\x1b[${code}m${t}\x1b[0m` : t)
-  const byParent = childrenIndex(nodes)
-  const lines: string[] = []
-
-  const badges = (n: TreeNode): string => {
-    const parts: string[] = []
-    if (n.ghost) parts.push(c('90', 'ghost'))
-    if (n.drift) parts.push(c('33', `drift:${n.drift}`))
-    const stale = staleYatsu(n)
-    if (stale) parts.push(c('90', `stale:${stale}`))
-    if (n.reviewSummary?.issues?.open) parts.push(c('31', `issues:${n.reviewSummary.issues.open}`))
-    return parts.length ? '  ' + parts.join(' ') : ''
-  }
-
-  const line = (n: TreeNode, prefix: string, branch: string) => {
-    const code = STATUS_ANSI[n.status] ?? '0'
-    // base state is invisible: merged (~80% of nodes) is the healthy ground state, already carried by
-    // the dot's colour — only deviations get a text label. Without colour the word IS the signal, so
-    // every status (merged included) prints in plain-text mode.
-    const label = color && n.status === 'merged' ? '' : ' ' + c(code, `[${n.status}]`)
-    const title = n.title && n.title !== n.id ? ' ' + c('90', '· ' + n.title) : ''
-    lines.push(`${prefix}${branch}${c(code, '●')} ${n.id}${label}${title}${badges(n)}`)
-  }
-
-  const walk = (n: TreeNode, prefix: string, branch: string, childPrefix: string, depth: number) => {
-    line(n, prefix, branch)
-    const kids = byParent.get(n.id) ?? []
-    if (!kids.length) return
-    if (opts.depth !== undefined && depth >= opts.depth) {
-      lines.push(`${childPrefix}${c('90', `└─ … ${kids.length} more (raise --depth)`)}`)
-      return
-    }
-    kids.forEach((k, i) => {
-      const last = i === kids.length - 1
-      walk(k, childPrefix, last ? '└─ ' : '├─ ', childPrefix + (last ? '   ' : '│  '), depth + 1)
-    })
-  }
-
-  for (const r of roots(nodes, opts.node)) walk(r, '', '', '', 0)
-  return lines.join('\n')
-}
-
-// the machine exit: the same filtered subtree as NESTED objects, badge counts precomputed — a
-// shaped view, not a replacement for `spex graph --json` (which stays the full flat payload). Pruned
-// children degrade to their ids, so --depth still tells the machine what exists below the cut.
-export function treeJson(nodes: TreeNode[], opts: TreeOpts = {}): object[] {
-  const byParent = childrenIndex(nodes)
-  const shape = (n: TreeNode, depth: number): object => {
-    const kids = byParent.get(n.id) ?? []
-    const pruned = opts.depth !== undefined && depth >= opts.depth
-    return {
-      id: n.id, title: n.title, status: n.status, version: n.version ?? 0,
-      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.reviewSummary?.issues?.open ?? 0,
-      ...(n.ghost ? { ghost: true } : {}),
-      children: pruned ? kids.map((k) => k.id) : kids.map((k) => shape(k, depth + 1)),
-    }
-  }
-  return roots(nodes, opts.node).map((r) => shape(r, 0))
-}

package/spec-cli/src/tsx-bin.ts

@@ -1,18 +0,0 @@
-import { createRequire } from 'node:module'
-import { dirname, join } from 'node:path'
-
-// @@@ tsxBin - tsx's JS ENTRY (dist/cli.mjs), dev-or-published, run through `node` by the caller
-// (`spawn(process.execPath, [tsxBin(pkgDir), entry, …])`). In the dev monorepo tsx sits in
-// spec-cli/node_modules; in an installed `spexcode` package npm may hoist it to the consumer's node_modules
-// — Node's own package resolver from spec-cli covers dev, global, and project-local installs in one rule.
-// We resolve the .mjs entry rather than the `.bin/tsx` shim on purpose: the shim is an unspawnable sh
-// script on Windows, so `node dist/cli.mjs` (identical to the shim on POSIX) is the one cross-platform form.
-// `pkgDir` is the spec-cli directory.
-export function tsxBin(pkgDir: string): string {
-  try {
-    const req = createRequire(join(pkgDir, 'package.json'))
-    return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
-  } catch {
-    throw new Error(`tsx runtime not found from ${pkgDir} — run \`npm install\` in the SpexCode package`)
-  }
-}

package/spec-cli/src/uninstall.ts

@@ -1,171 +0,0 @@
-import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
-import { basename, join, resolve, relative } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execFileSync } from 'node:child_process'
-import { HARNESSES, type HarnessArtifacts } from './harness.js'
-import { runtimeRoot, readConfig, mainCheckout } from './layout.js'
-import { resolveHarnessTargets } from './harness-select.js'
-import { loadSkillConfig, loadAgentConfig } from './specs.js'
-import { dematerialize } from './materialize.js'
-import { gitBinary } from './git.js'
-
-// the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
-const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex', '.zcode'] as const
-
-// Init and uninstall share one ownership source for generated git hooks: the shipped canonical templates.
-// Exact bytes prove the destination is still our derivative; any user edit withdraws that ownership.
-const HOOK_TEMPLATES = fileURLToPath(new URL('../templates/hooks', import.meta.url))
-
-// is this dir a SpexCode plugin bundle? Either its folder name is the identity stamp, or its
-// `.claude-plugin/plugin.json` declares `name: spexcode`. Read-gated so a user's other plugin is never touched.
-function isSpexcodeBundle(dir: string): boolean {
-  if (basename(dir) === 'spexcode') return true
-  const manifest = join(dir, '.claude-plugin', 'plugin.json')
-  if (!existsSync(manifest)) return false
-  try {
-    return (JSON.parse(readFileSync(manifest, 'utf8')) as { name?: unknown }).name === 'spexcode'
-  } catch {
-    return false
-  }
-}
-
-// sweep any spexcode-stamped plugin bundle (`<host>/plugins/spexcode`, or a `.claude-plugin/plugin.json` named
-// spexcode) under the project's plugin-host folders. The bundle EMITTER is a later node, so a native-only install
-// has nothing here today; the sweep keeps uninstall a true inverse once it lands (and cleans a hand-dropped one).
-function sweepPluginBundles(proj: string, hosts: readonly string[]): string[] {
-  const removed: string[] = []
-  for (const host of new Set(hosts)) {
-    const pluginsDir = join(proj, host, 'plugins')
-    if (!existsSync(pluginsDir)) continue
-    for (const e of readdirSync(pluginsDir, { withFileTypes: true })) {
-      if (!e.isDirectory()) continue
-      const dir = join(pluginsDir, e.name)
-      if (isSpexcodeBundle(dir)) {
-        rmSync(dir, { recursive: true, force: true })
-        removed.push(relative(proj, dir))
-      }
-    }
-  }
-  return removed
-}
-
-// Arbitrary plugin landing folders are the one materialized path set that cannot be reconstructed from stamps
-// alone, so materialize records them as data. Read every current per-tree ledger plus the legacy project-global
-// ledger before uninstall removes the store; a stale bundle remains removable even after current config stopped
-// naming its former host folder.
-function pluginLedgerHosts(store: string): string[] {
-  const ledgers = [join(store, 'plugin-folders')]
-  const trees = join(store, 'trees')
-  if (existsSync(trees)) {
-    for (const e of readdirSync(trees, { withFileTypes: true })) {
-      if (e.isDirectory()) ledgers.push(join(trees, e.name, 'plugin-folders'))
-    }
-  }
-  const hosts: string[] = []
-  for (const ledger of ledgers) {
-    if (!existsSync(ledger)) continue
-    hosts.push(...readFileSync(ledger, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean))
-  }
-  return hosts
-}
-
-// resolve the repo's shared git hooks dir (the common dir's hooks/), or null when <dir> isn't a git repo.
-function hooksDir(proj: string): string | null {
-  try {
-    const common = execFileSync(gitBinary(process.env), ['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim()
-    return join(common, 'hooks')
-  } catch {
-    return null
-  }
-}
-
-// Remove only byte-identical products of the canonical hook templates. Enumerating the same template directory
-// init copies keeps every generated hook covered without a second name list; modified and unrelated hooks survive.
-function removeHooks(proj: string): string[] {
-  const dir = hooksDir(proj)
-  if (!dir) return []
-  const removed: string[] = []
-  for (const e of readdirSync(HOOK_TEMPLATES, { withFileTypes: true })) {
-    if (!e.isFile()) continue
-    const hook = join(dir, e.name)
-    if (!existsSync(hook) || !readFileSync(hook).equals(readFileSync(join(HOOK_TEMPLATES, e.name)))) continue
-    rmSync(hook, { force: true })
-    removed.push(e.name)
-  }
-  return removed
-}
-
-export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean } = {}): void {
-  const proj = resolve(targetArg ?? process.cwd())
-  console.log(`spex uninstall → ${proj}`)
-
-  // cwd = the project so the .plugins loaders read THIS tree's surface nodes (the live skill/agent names tell
-  // each adapter's clean() exactly which name-scoped on-demand files were its to remove).
-  const prevCwd = process.cwd()
-  let arts: HarnessArtifacts = { skills: [], agents: [] }
-  try {
-    process.chdir(proj)
-    arts = { skills: loadSkillConfig().map((s) => s.name), agents: loadAgentConfig().map((a) => a.name) }
-  } catch {
-    // no readable .plugins (already partly torn down, or never adopted) — clean still strips the harness wiring.
-  } finally {
-    process.chdir(prevCwd)
-  }
-
-  // 1+2. materialize(∅): every harness's artifacts (contract block, shim, trust, skills/agents), the managed
-  //    .gitignore + info/exclude blocks, any legacy skip-worktree bit, and the content filter — the SAME
-  //    erase phase every materialize runs, asserted against the empty policy. One inverse, never a parallel one.
-  dematerialize(proj, arts)
-
-  // 3. Locate the global per-project store and recover every current/legacy plugin landing folder from its
-  //    ledgers BEFORE deleting it. The store is the runtime tier, not the user's tracked intent asset.
-  let store: string | null = null
-  let ledgerHosts: string[] = []
-  try {
-    store = runtimeRoot(proj)
-  } catch {
-    store = null
-  }
-  if (store) ledgerHosts = pluginLedgerHosts(store)
-
-  // 4. Any spexcode-stamped plugin bundle under configured, standard, or ledger-recovered hosts. The ledger
-  //    input is what closes plugin-folder A -> native/folder B even when the previous materialize never finished.
-  let pluginHosts: string[] = [...DEFAULT_PLUGIN_HOSTS, ...ledgerHosts]
-  try {
-    const targets = resolveHarnessTargets(readConfig(mainCheckout(proj)).harnesses)
-    pluginHosts = [...pluginHosts, ...targets.filter((t) => t.kind === 'plugin').map((t) => (t as { folder: string }).folder)]
-  } catch {
-    // an illegal harnesses set doesn't block backout — fall through to the standard hosts.
-  }
-  const bundles = sweepPluginBundles(proj, pluginHosts)
-
-  // 5. The whole store: per-tree manifests/hashes/ledgers and sessions.
-  const removedStores: string[] = []
-  for (const candidate of new Set([store].filter((path): path is string => !!path))) {
-    if (!existsSync(candidate)) continue
-    rmSync(candidate, { recursive: true, force: true })
-    removedStores.push(candidate)
-  }
-
-  console.log(`✓ dematerialized (contract blocks, shims, Codex trust, skills, sub-agents, ignore blocks, content filter) for ${HARNESSES.map((h) => h.id).join(', ')}`)
-  if (removedStores.length) console.log(`✓ removed the global per-project store (${removedStores.join(', ')})`)
-  if (bundles.length) console.log(`✓ removed plugin bundle(s): ${bundles.join(', ')}`)
-
-  // Git hooks are per-clone and may carry user logic → preserved unless --hooks (and even then only while
-  // byte-identical to a canonical generated template; a user edit withdraws our ownership).
-  if (opts.hooks) {
-    const removed = removeHooks(proj)
-    if (removed.length) console.log(`✓ removed git hooks (${removed.join(', ')})`)
-    else console.log('• no spexcode git hooks to remove')
-  } else {
-    console.log('• left git hooks in place (per-clone; pass --hooks to remove the spexcode ones)')
-  }
-
-  console.log(`
-SpexCode wiring removed. Your spec data is untouched:
-  • .spec/ (including .plugins/) and spexcode.json remain — your tracked intent is never deleted by uninstall.
-  • To re-adopt later: \`spex init\` regenerates the shims, contract, trust, and global store.`)
-}