spexcode 0.1.0

package/src/hooks.ts

@@ -0,0 +1,41 @@
+import { writeFileSync } from 'node:fs'
+import { loadHookConfig } from './specs.js'
+
+// @@@ hook manifest - the harness-agnostic hook system has THREE parts: (1) the discovered handlers —
+// `surface: hook` nodes under .config/core/* (spec-governed content, each shipping one co-located .sh);
+// (2) this COMPILER, which flattens them into a flat per-session manifest; (3) a pure-shell dispatcher
+// (spec-cli/hooks/dispatch.sh) the committed .claude/.codex shim binds to every harness event. The compiler
+// is the ONLY step that parses spec frontmatter, so it runs ONCE at SessionStart and the hot-path dispatcher
+// (PreToolUse fires on every tool) just greps a flat file — never walks the spec tree.
+//
+// Manifest line = `event<TAB>order<TAB>block<TAB>script` (script = repo-relative path to the node's .sh),
+// sorted by event, then order, then script — the DETERMINISTIC run order the native multi-hook model (which
+// runs matching hooks in parallel on BOTH Claude Code and Codex) cannot guarantee. One node binds many
+// events (mark-active → UserPromptSubmit+PreToolUse) → one manifest line per (node × event).
+export function compileManifest(cfgs = loadHookConfig()): string {
+  const lines: string[] = []
+  for (const h of cfgs) {
+    const script = h.files.find((f) => f.endsWith('.sh'))
+    if (!script) throw new Error(`surface:hook node '${h.name}' ships no .sh script (one co-located .sh required)`)
+    for (const ev of h.events) lines.push(`${ev}\t${h.order}\t${h.block}\t${script}`)
+  }
+  lines.sort((a, b) => {
+    const A = a.split('\t'), B = b.split('\t')
+    return A[0].localeCompare(B[0]) || Number(A[1]) - Number(B[1]) || (a < b ? -1 : a > b ? 1 : 0)
+  })
+  return lines.length ? lines.join('\n') + '\n' : ''
+}
+
+// `spex hooks compile [--out <file>]` — write the manifest (SessionStart) or print it (debug/test).
+export async function runHooks(argv: string[]): Promise<number> {
+  const sub = argv[0]
+  if (sub === 'compile') {
+    const i = argv.indexOf('--out')
+    const manifest = compileManifest()
+    if (i >= 0 && argv[i + 1]) writeFileSync(argv[i + 1], manifest)
+    else process.stdout.write(manifest)
+    return 0
+  }
+  console.error('spex hooks: compile [--out <file>]')
+  return 2
+}

package/src/index.ts

@@ -0,0 +1,233 @@
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { createNodeWebSocket } from '@hono/node-ws'
+import { loadSpecs, specHistory, specDiffAt, loadConfig } from './specs.js'
+import { resolveLayout, mainBranch } from './layout.js'
+import { buildBoard } from './board.js'
+import { gitA, gitTry } from './git.js'
+import { newSession, listSessions, sendKeys, rawKey, exitSession, closeSession, reopen, propose, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
+import { defaultHarness, HARNESSES } from './harness.js'
+import { evalTimeline, readBlobByHash } from '../../spec-yatsu/src/evaltab.js'
+import { buildProofModel, renderProofHtml } from '../../spec-yatsu/src/proof.js'
+import { saveUpload, MAX_UPLOAD_BYTES } from './uploads.js'
+import { attachViewer, detachViewer, writeViewer, resizeBridge, superviseBridges, type Viewer } from './pty-bridge.js'
+import { installProcessGuards } from './resilience.js'
+
+// last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
+// self-merge) is logged and the server KEEPS SERVING instead of exiting and dropping the public port.
+installProcessGuards()
+
+const app = new Hono()
+app.use('/api/*', cors())
+const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app })
+
+app.get('/', (c) => c.text('spec-cli — GET /api/board · /api/specs · /api/specs/:id/history · /api/layout · /api/sessions · /api/slash-commands'))
+// the supervisor's readiness gate (supervise.ts): a bare git-free 200 so a booting child reports ready the
+// instant Hono is listening. Not under /api/* — loopback-only (supervisor→child), no CORS needed.
+app.get('/health', (c) => c.text('ok'))
+// the assembled board (merged tree + overlay + sessions) — the dashboard's single source. Same data
+// as `spex board`; the frontend only adds x/y pixels on top.
+app.get('/api/board', async (c) => c.json(await buildBoard()))
+app.get('/api/specs', async (c) => c.json(await loadSpecs()))
+app.get('/api/specs/:id/history', async (c) => c.json(await specHistory(c.req.param('id'))))
+// the spec.md line diff one version introduced — the history tab's per-version proof-of-change, fetched
+// lazily when an older version's item expands (the latest version's diff ships with the board as node.lastDiff).
+app.get('/api/specs/:id/diff/:hash', async (c) => c.json(await specDiffAt(c.req.param('id'), c.req.param('hash'))))
+// a unified diff of a node's spec.md from its fork point (the worktree's merge-base with main) to that
+// worktree's working tree. An untracked brand-new node is invisible to `git diff <base>`, so when the base
+// diff is empty AND status is `??` synthesize an all-additions view via `diff --no-index` (gitTry — --no-index
+// exits 1, which gitA would swallow). Gated on `??` so a tracked file with no pending change stays empty.
+app.get('/api/edit', async (c) => {
+  const source = c.req.query('source') || '', path = c.req.query('path') || ''
+  if (!source || !path) return c.json({ patch: '' })
+  const mb = mainBranch()
+  const base = (await gitA(['-C', source, 'merge-base', mb, 'HEAD'])).trim() || mb
+  let patch = await gitA(['-C', source, 'diff', base, '--', path])
+  if (!patch) {
+    const status = await gitA(['-C', source, 'status', '--porcelain', '--untracked-files=all', '--', path])
+    if (status.startsWith('??')) patch = (await gitTry(['-C', source, 'diff', '--no-index', '--', '/dev/null', path])).stdout
+  }
+  return c.json({ patch })
+})
+// a node's eval timeline (read half of `spex yatsu`): yatsu-sidecar readings joined with a live freshness
+// flag, newest-first; `hasYatsu:false` when none declared. Contract belongs to [[spec-yatsu]].
+app.get('/api/specs/:id/evals', async (c) => c.json(await evalTimeline(c.req.param('id'))))
+// serve a reading's evidence blob by content hash (bytes never enter git): bad hash → 400, missing → 404,
+// else the bytes with a sniffed MIME and an immutable cache header (the name IS the content hash).
+app.get('/api/yatsu/blob/:hash', (c) => {
+  const r = readBlobByHash(c.req.param('hash'))
+  if (!r.ok) return c.text(r.message, r.reason === 'invalid' ? 400 : 404)
+  return c.body(new Uint8Array(r.bytes), 200, { 'Content-Type': r.mime, 'Cache-Control': 'public, max-age=31536000, immutable' })
+})
+app.get('/api/layout', async (c) => c.json(await resolveLayout()))
+// the `surface: slash` config-root plugins (built/active only) for the new-session `/` dropdown — each with
+// its prompt `body` ({{targets}} placeholder), `kind`, and folder `dir` + co-located `files`. surface is a
+// frontmatter field, not a dir (specs.ts loadSurface); `surface: system` siblings are gathered elsewhere.
+app.get('/api/config', (c) => c.json(loadConfig()))
+// the dashboard input's `/` dropdown — computed by the launcher's HARNESS adapter the same way that harness
+// computes its own `/` menu ([[harness-adapter]]). The client passes `?harness=<id>` for the ACTIVE session,
+// so a codex tab gets CODEX's menu, not the default's; unknown/absent → default. Insert-only on the client.
+app.get('/api/slash-commands', (c) => {
+  const h = HARNESSES.find((x) => x.id === c.req.query('harness')) || defaultHarness
+  return c.json(h.slashCommands())
+})
+
+// write a pasted/dropped/picked file to this (worker) machine's /tmp and return its absolute path for the
+// client to splice into the prompt. Fail-loud: no/empty file → 400, over the size cap → 413, write error → 500.
+app.post('/api/uploads', async (c) => {
+  const body = await c.req.parseBody().catch(() => ({} as Record<string, string | File>))
+  const file = body['file']
+  if (!(file instanceof File) || file.size === 0) return c.json({ error: 'no file' }, 400)
+  if (file.size > MAX_UPLOAD_BYTES) return c.json({ error: 'file too large' }, 413)
+  try {
+    return c.json({ path: await saveUpload(file) }, 201)
+  } catch (e) {
+    return c.json({ error: String((e as Error)?.message || e) }, 500)
+  }
+})
+
+// sessions: real tmux-backed Claude Code sessions. List + spawn, stream the live pane (WebSocket),
+// forward keystrokes, and close.
+app.get('/api/sessions', async (c) => c.json(await listSessions()))
+// edges derived live from `spex watch` monitors (A→B = agent A is watching B), not a stored subscription;
+// watch/unwatch register + heartbeat. A literal `graph` segment so it never collides with the `:id` routes.
+app.get('/api/sessions/graph', async (c) => c.json(await sessionGraph()))
+app.post('/api/sessions/graph/watch', async (c) => {
+  const b = await c.req.json().catch(() => ({}))
+  const selectors = Array.isArray(b?.selectors) ? b.selectors.map(String) : []
+  const ok = registerWatch(String(b?.token || ''), String(b?.watcher || ''), selectors, Number(b?.ttlMs) || undefined)
+  return c.json({ ok }, ok ? 200 : 400)
+})
+app.post('/api/sessions/graph/unwatch', async (c) => {
+  const b = await c.req.json().catch(() => ({}))
+  const ok = deregisterWatch(String(b?.token || ''))
+  return c.json({ ok }, ok ? 200 : 404)
+})
+app.post('/api/sessions', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const prompt = typeof body?.prompt === 'string' ? body.prompt : ''
+  if (!prompt.trim()) return c.json({ error: 'empty prompt' }, 400)
+  const harness = typeof body?.harness === 'string' ? body.harness : undefined
+  try {
+    return c.json(await newSession(typeof body?.node === 'string' ? body.node : null, prompt, harness), 201)
+  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown harness id → 400, not a 500
+})
+// one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
+// dashboard and `spex review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].
+app.get('/api/sessions/:id/review', async (c) => {
+  const r = await reviewPayload(c.req.param('id'))
+  return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
+})
+// the [[review-proof]] HTML: the diff grouped by node, each node's measured yatsu loss with evidence inlined
+// as data-URIs, and the merge gates. `?format=json` returns the model; default = rendered HTML. 404 unknown id.
+app.get('/api/sessions/:id/proof', async (c) => {
+  const m = await buildProofModel(c.req.param('id'))
+  if (!m) return c.text('no such session', 404)
+  if (c.req.query('format') === 'json') return c.json(m)
+  return c.html(renderProofHtml(m))
+})
+// the session's live pane as text (one-shot snapshot) for a backend client (`spex capture`). Empty and fail
+// stay distinct: an empty pane is 200 with empty body; unknown id → 404, offline (no live pane) → 409, error → 502.
+app.get('/api/sessions/:id/capture', async (c) => {
+  const r = await captureSessionResult(c.req.param('id'))
+  if (r.ok) return c.text(r.pane)
+  if (r.reason === 'unknown') return c.text('no such session', 404)
+  if (r.reason === 'offline') return c.text('session offline (no live pane)', 409)
+  return c.text('capture failed', 502)
+})
+// the session's originating prompt (what it was asked to do), for a manager client; 404 if none recorded.
+app.get('/api/sessions/:id/prompt', async (c) => {
+  const p = await sessionPrompt(c.req.param('id'))
+  return p == null ? c.text('no prompt recorded', 404) : c.text(p)
+})
+// lifecycle transitions (thin callers of the session state machine)
+app.post('/api/sessions/:id/resume', async (c) => c.json({ ok: await reopen(c.req.param('id')) }))   // back-to-working / relaunch
+app.post('/api/sessions/:id/review', async (c) => c.json({ ok: await propose(c.req.param('id'), 'merge') }))
+// a dispatch to the session's own agent (it runs the merge), never a server merge — the server never touches
+// main's tree. 200 {dispatched:true} once the prompt is accepted, 409 {dispatched:false} if the agent is unreachable.
+app.post('/api/sessions/:id/merge', async (c) => {
+  const r = await mergeSession(c.req.param('id'))
+  return c.json(r, r.dispatched ? 200 : 409)
+})
+
+// one bidirectional WS over a shared tmux client (pty-bridge): server→client = raw pane bytes (binary);
+// client→server = raw terminal input (binary) + a text control frame {t:'resize',cols,rows}. A real tmux
+// client, so scrollback is tmux's own and the first paint is one coherent repaint.
+app.get('/api/sessions/:id/socket', upgradeWebSocket((c) => {
+  const id = c.req.param('id') as string
+  let viewer: Viewer | null = null
+  return {
+    onOpen(_evt, ws) {
+      viewer = { send: (buf) => { try { ws.send(Uint8Array.from(buf)) } catch { /* viewer gone */ } } }
+      if (!attachViewer(id, viewer)) { try { ws.close() } catch { /* already closed */ } }
+    },
+    onMessage(evt) {
+      if (!viewer) return
+      const data = evt.data
+      if (typeof data === 'string') {
+        // text frame = control. Only resize today.
+        try { const m = JSON.parse(data); if (m?.t === 'resize') resizeBridge(id, Number(m.cols), Number(m.rows)) } catch { /* ignore */ }
+      } else if (data instanceof ArrayBuffer) {
+        writeViewer(id, Buffer.from(data))                              // binary: raw terminal input
+      } else if (ArrayBuffer.isView(data)) {
+        writeViewer(id, Buffer.from(data.buffer, data.byteOffset, data.byteLength))  // (keystrokes / mouse)
+      }
+    },
+    onClose() { if (viewer) detachViewer(id, viewer) },
+  }
+}))
+// the docked ❯ line input (and server-side merge dispatch) dispatch a whole prompt through the rendezvous
+// control socket. Socket-only + fail-loud: a prompt the agent doesn't confirm accepting returns 502 with the
+// reason (never a silent 200), so the dashboard/manager sees a dead dispatch instead of a false success.
+app.post('/api/sessions/:id/keys', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  // `from` (the sender's session id) rides only an agent-to-agent send → the backend records the comms
+  // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged.
+  const r = await sendKeys(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined)
+  return c.json(r, r.ok ? 200 : 502)
+})
+// the preserved tmux send-keys path (distinct from the ❯ prompt socket): one key per keydown so a human can
+// drive the agent's interactive TUI menus in real time. Forwards keystrokes only.
+app.post('/api/sessions/:id/rawkey', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const ok = await rawKey(c.req.param('id'), typeof body?.key === 'string' ? body.key : '')
+  return c.json({ ok }, ok ? 200 : 404)
+})
+// soft stop: kill the agent's tmux + socket but KEEP the worktree (relaunchable). Distinct from close, which
+// removes the worktree. {ok:false} = no such session.
+app.post('/api/sessions/:id/exit', async (c) => c.json({ ok: await exitSession(c.req.param('id')) }))
+app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
+// set (or clear, with a blank) a session's display-name override; persists to the worktree's `.session` so
+// it survives a restart. Unknown id → 404.
+app.post('/api/sessions/:id/rename', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const ok = await renameSession(c.req.param('id'), typeof body?.name === 'string' ? body.name : '')
+  return c.json({ ok }, ok ? 200 : 404)
+})
+
+// set/clear a session's sort-key ([[session-reorder]]): a finite number pins the row's slot, null (or
+// non-numeric) restores birth order. Mirrors /rename.
+app.post('/api/sessions/:id/sort', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const key = typeof body?.key === 'number' && Number.isFinite(body.key) ? body.key : null
+  const ok = await setSessionSort(c.req.param('id'), key)
+  return c.json({ ok }, ok ? 200 : 404)
+})
+
+const port = Number(process.env.PORT || 8787)
+const server = serve({ fetch: app.fetch, port })
+injectWebSocket(server)
+superviseBridges()   // keep a warm tmux client per live session, so opening a tab is instant
+superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
+console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
+
+// graceful drain (the other half of zero-downtime reload, supervise.ts): on SIGTERM stop accepting new
+// connections, let in-flight requests finish, and sweep now-idle keep-alive sockets so close() fires the
+// instant the last request drains. A hard cap still forces exit if a connection won't close.
+process.on('SIGTERM', () => {
+  const srv = server as unknown as { close(cb?: () => void): void; closeIdleConnections?(): void }
+  const sweep = setInterval(() => srv.closeIdleConnections?.(), 200)
+  srv.close(() => { clearInterval(sweep); process.exit(0) })
+  setTimeout(() => process.exit(0), 10000).unref()
+})

package/src/init.ts

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+
+// this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
+// launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
+const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
+const TEMPLATES = join(pkgRoot, 'templates')
+
+// recursively copy srcDir -> destDir, NEVER overwriting an existing file. Returns the repo-relative
+// paths of files actually written (so the caller can report exactly what was planted vs already there).
+function copyTreeNoClobber(srcDir: string, destDir: string, base: string): string[] {
+  const written: string[] = []
+  mkdirSync(destDir, { recursive: true })
+  for (const e of readdirSync(srcDir, { withFileTypes: true })) {
+    const src = join(srcDir, e.name)
+    const dest = join(destDir, e.name)
+    if (e.isDirectory()) {
+      written.push(...copyTreeNoClobber(src, dest, base))
+    } else if (existsSync(dest)) {
+      // additive only — a pre-existing file is the user's, leave it untouched.
+      continue
+    } else {
+      copyFileSync(src, dest)
+      written.push(relative(base, dest))
+    }
+  }
+  return written
+}
+
+// resolve the target repo's git hooks dir the same way scripts/install-hooks.sh does — the COMMON dir's
+// hooks/ (shared across all worktrees). Returns null (with a loud reason) when <dir> isn't a git repo.
+function resolveHooksDir(dir: string): string | null {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'], // swallow git's own "fatal: not a git repository" — our warning is the signal
+    }).trim()
+    return join(common, 'hooks')
+  } catch {
+    return null
+  }
+}
+
+export async function specInit(targetArg: string | undefined): Promise<void> {
+  const targetDir = resolve(targetArg ?? process.cwd())
+  if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
+  console.log(`spex init → ${targetDir}`)
+
+  // 1. seed the spec tree: templates/spec/* -> <dir>/.spec/* (an existing .spec aborts this phase loudly).
+  const specDest = join(targetDir, '.spec')
+  if (existsSync(specDest)) {
+    console.warn(`• .spec already exists at ${specDest} — skipping spec scaffold (won't overwrite an existing tree).`)
+  } else {
+    const planted = copyTreeNoClobber(join(TEMPLATES, 'spec'), specDest, targetDir)
+    console.log(`✓ seeded ${planted.length} spec file(s) under .spec/ (root 'project' node + default .config)`)
+  }
+
+  // 1b. plant a starter spexcode.json (the lint/layout knob), pointing governedRoots at `src/`.
+  const cfgDest = join(targetDir, 'spexcode.json')
+  if (existsSync(cfgDest)) {
+    console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
+  } else {
+    copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
+    console.log(`✓ planted spexcode.json — set lint.governedRoots to YOUR source dirs (starter: ["src"])`)
+  }
+
+  // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
+  const hooksDir = resolveHooksDir(targetDir)
+  if (!hooksDir) {
+    console.warn(`• ${targetDir} is not a git repository — skipped hook install. Run \`git init\` there, then \`spex init\` again (or \`npm run hooks\`).`)
+  } else {
+    mkdirSync(hooksDir, { recursive: true })
+    const hooksSrc = join(TEMPLATES, 'hooks')
+    const installed: string[] = []
+    for (const e of readdirSync(hooksSrc, { withFileTypes: true })) {
+      if (!e.isFile()) continue
+      const dest = join(hooksDir, e.name)
+      if (existsSync(dest)) {
+        console.warn(`• hook ${e.name} already exists in ${hooksDir} — left untouched.`)
+        continue
+      }
+      copyFileSync(join(hooksSrc, e.name), dest)
+      chmodSync(dest, 0o755)
+      installed.push(e.name)
+    }
+    if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
+  }
+
+  // 2c. RENDER the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
+  // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
+  // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
+  // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
+  // .config. Idempotent — the dispatch.sh gate keeps it fresh thereafter on every .config edit.
+  const prevCwd = process.cwd()
+  try {
+    process.chdir(targetDir)
+    const { materialize } = await import('./materialize.js')
+    materialize(targetDir)
+    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, .claude/.codex shims, Codex trust)')
+  } catch (e) {
+    console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
+  } finally {
+    process.chdir(prevCwd)
+  }
+
+  // 3. next steps — what the human must do to bring the instance to life.
+  console.log(`
+Next steps:
+  1. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
+  2. Set lint.governedRoots in spexcode.json to your source dir(s) — until you do, \`spex lint\`
+     warns it is governing nothing (it ships pointing at "src").
+  3. Start the backend and open the board:
+       spex serve                       # http://localhost:8787
+  4. \`spex lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no
+     spec node claims yet). You're adopting SpexCode — the spec tree is now ground truth.
+  (On a fresh CLONE, re-run \`spex init\` — git never clones .git/hooks/, and the harness shims are
+   gitignored machine-local files that regenerate per-machine.)`)
+}

package/src/layout.ts

@@ -0,0 +1,246 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
+import { guardWorktree } from './resilience.js'
+import { HARNESSES } from './harness.js'
+
+type Config = {
+  main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
+  mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
+  branchPrefix?: string            // how a branch names its node (default: "node/")
+  dashboard?: {
+    apiUrl?: string                // the per-project backend the board proxies to (read frontend-side; see api-endpoint)
+    title?: string                 // override for the browser-tab name (default: the repo-root basename; see tab-title)
+    icon?: string                  // the browser-tab favicon: an emoji ("🔭") or an Iconify name ("mdi:rocket-launch"); see tab-icon
+  }
+  sessions?: {
+    maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 6; see sessions.ts maxActive)
+  }
+  serve?: {
+    // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
+    // The password is NEVER read from here — flag/env only — so this file stays committable.
+    public?: {
+      enabled?: boolean              // turn public mode on without the --public flag
+      http?: boolean                 // drop TLS (the --http escape hatch) — password then travels in cleartext
+      tls?: { cert?: string; key?: string }   // PATHS to your own cert/key; omit for a cached self-signed default
+    }
+  }
+}
+// the resolved LAYOUT convention — main/mainBranch/branchPrefix filled to defaults. `dashboard`, `sessions`,
+// and `serve` are frontend/runtime concerns (read separately via readConfig; see api-endpoint / sessions.ts
+// maxActive / gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
+type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve'>>
+
+export type Worktree = {
+  path: string; branch: string | null; node: string | null
+  session: string | null; status: string | null; isMain: boolean
+  ops: NodeOp[]   // pending spec-node changes this worktree makes vs main (the board's overlay)
+}
+export type Layout = { main: string; convention: Convention; worktrees: Worktree[] }
+
+export function readConfig(root: string): Config {
+  const p = join(root, 'spexcode.json')
+  if (!existsSync(p)) return {}
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return {} }
+}
+
+// the shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it). Memoized:
+// it's a process constant, but mainBranch()/mainRoot() resolve it per call (~60 git rev-parse forks per board build without the cache).
+let commonDirCache: string | null = null
+export function gitCommonDir(): string {
+  if (commonDirCache === null) commonDirCache = git(['rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+  return commonDirCache
+}
+
+export function mainBranch(): string {
+  try {
+    const override = readConfig(mainCheckout()).mainBranch?.trim()
+    if (override) return override
+    const cur = git(['-C', mainCheckout(), 'symbolic-ref', '--short', 'HEAD']).trim()
+    if (cur) return cur
+  } catch { /* fall through to the conventional default */ }
+  return 'main'
+}
+
+// the MAIN checkout (the root working tree) for a project — the SAME answer from main OR any linked worktree
+// (dirname of the shared git common dir). Codex reads a LINKED worktree's PROJECT hooks from the root checkout's
+// `.codex` (codex-rs hooks_config_folder override), NOT the worktree's, so the codex hooks shim + trust
+// materialize here while AGENTS.md/skills stay per-worktree — see [[harness-adapter]] (harness.ts).
+export function mainCheckout(proj?: string): string {
+  const gcd = proj
+    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+    : gitCommonDir()
+  return dirname(gcd)
+}
+
+// @@@ global per-session store - Fork A: NO SpexCode files live in the worktree any more, so the worktree's
+// spec/code tree is pristine (zero per-session pollution). Every per-session runtime artifact — the
+// structured record (session.json) AND the launcher products (prompt, launch, launch.sh) AND the recorded comms AND
+// the spec-discipline sentinels — lives in a per-USER GLOBAL store, keyed by the harness `session_id` so two
+// agents in one folder never clobber, and grouped PER PROJECT (mirroring Claude's ~/.claude/projects/<enc>/)
+// so the board enumerates ONE directory. This is the single seam that knows where the store sits; sessions.ts
+// and the shell hooks resolve through the SAME scheme (the hooks reimplement it in bash, so any change here
+// must be mirrored in .config/core/*/). SPEXCODE_HOME overrides the root for test isolation.
+export function spexcodeHome(): string {
+  return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
+}
+// encode a project-root path into ONE safe directory segment (Claude's scheme: path separators → '-'). The
+// SAME transform runs in TS and in the shell hooks, so a board read and a hook write land on the SAME dir.
+export function encodeProject(root: string): string {
+  return root.replace(/[/.]/g, '-')
+}
+// the project a store groups by = the MAIN checkout root (dirname of the shared git common dir). It resolves
+// IDENTICALLY from the main checkout OR any linked worktree, so the board (running at main) and a hook
+// (running in a worktree) agree on the key — unlike `git rev-parse --show-toplevel`, which in a worktree is
+// the worktree path and would scatter a session under a per-worktree key the board never reads.
+export function projectKey(): string {
+  return encodeProject(dirname(gitCommonDir()))
+}
+// this project's per-PROJECT runtime tier — the materialized hook manifest + content-hash marker (and the
+// gate's lock) — living alongside sessions/ under the SAME global per-project dir, so NOTHING SpexCode renders
+// stays in the worktree (not even the manifest; the worktree holds only the harness-discovered CLAUDE.md/
+// AGENTS.md + shims, which must sit in-tree). proj-aware for `spex init <dir>` / materialize(proj); cwd-based
+// default for the hooks/board. The shell hooks mirror this as hp_runtime_dir.
+export function runtimeRoot(proj?: string): string {
+  const gcd = proj
+    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+    : gitCommonDir()
+  return join(spexcodeHome(), 'projects', encodeProject(dirname(gcd)))
+}
+// this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
+// all keyed by session_id under <home>/projects/<enc>/sessions/.
+export function sessionsRoot(): string { return join(runtimeRoot(), 'sessions') }
+export function sessionStoreDir(id: string): string { return join(sessionsRoot(), id) }
+export function sessionRecordPath(id: string): string { return join(sessionStoreDir(id), 'session.json') }
+export function sessionArtifactPath(id: string, name: string): string { return join(sessionStoreDir(id), name) }
+
+// the structured per-session record, as it sits on disk. Written one-field-per-line with EVERY key present
+// (see sessions.ts writeRecord) so the hot-path mark-active shell hook can value-replace status/proposal/note
+// with sed and never needs jq. Read here for the overlay; sessions.ts owns the full typed read/write.
+export type RawRecord = {
+  session_id: string; governed: boolean; worktree_path: string; branch: string | null
+  node: string | null; title: string | null; name: string | null
+  status: string; proposal: string | null; merges: number; note: string | null
+  sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
+}
+// the agent's OWN session id from the environment — the only locator now that the record left the worktree.
+// Three tiers, in order:
+//   (1) a harness's per-thread env var (`sessionEnvVar`) RESOLVED VIA THE ALIAS — when it lands on a governed
+//       record (directly, or through that record's `harness_session_id`), that record's SpexCode id is the
+//       answer. This MUST win: codex's design-C runs ONE shared per-project app-server whose env carries the
+//       FIRST launched session's `SPEXCODE_SESSION_ID`, and the agent's shell tool (its `spex session
+//       done/park/ask`) runs INSIDE that app-server process, so `SPEXCODE_SESSION_ID` is contaminated with the
+//       wrong session. But codex injects the ACTING thread's id into every spawned command's env as
+//       CODEX_THREAD_ID (== codex's `sessionEnvVar`), so the per-thread var aliases to the RIGHT record while
+//       the shared `SPEXCODE_SESSION_ID` does not.
+//   (2) else `SPEXCODE_SESSION_ID` (the GOVERNED record id the launcher bakes in) — the claude path and the
+//       non-shared baseline, mirroring the shell hooks' `hp_session_id`.
+//   (3) else a harness's env var RAW — a self-launched, non-governed agent's own minted id, which has no
+//       governed record to alias to (codex CODEX_THREAD_ID / claude CLAUDE_CODE_SESSION_ID). The RAW form must
+//       stay BELOW (2): an un-aliased codex thread id is not a record key, so it must never beat a real
+//       `SPEXCODE_SESSION_ID`.
+// Claude is UNCHANGED: its `sessionEnvVar` (CLAUDE_CODE_SESSION_ID) already EQUALS its record id, so tier (1)
+// resolves to that very id — the same value `SPEXCODE_SESSION_ID` would have returned; there is no shared
+// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu
+// reads it to resolve the current node.)
+export function envSessionId(): string | null {
+  for (const h of HARNESSES) {
+    const v = process.env[h.sessionEnvVar]
+    if (v && v.trim()) { const r = readAliasedRawRecord(v.trim()); if (r) return r.session_id }
+  }
+  const o = process.env.SPEXCODE_SESSION_ID
+  if (o && o.trim()) return o.trim()
+  for (const h of HARNESSES) { const v = process.env[h.sessionEnvVar]; if (v && v.trim()) return v.trim() }
+  return null
+}
+export function readRawRecord(id: string): RawRecord | null {
+  try {
+    const raw = JSON.parse(readFileSync(sessionRecordPath(id), 'utf8'))
+    return raw && typeof raw === 'object' && raw.session_id ? raw as RawRecord : null
+  } catch { return null }
+}
+// resolve a possibly-ALIASED session id to its raw record. A codex hook fires from the shared per-project
+// app-server (no SPEXCODE_SESSION_ID in its env), so the id it carries is the codex THREAD id — the payload
+// session_id — not the SpexCode record id the store is keyed by. Direct id wins; else the one record that
+// captured this id as `harness_session_id` (the backend stored it at thread/start, before any tool turn).
+// Null when neither resolves. Mirrors the shell `hp_store_dir` alias grep — one resolution rule, both layers.
+export function readAliasedRawRecord(id: string): RawRecord | null {
+  const direct = readRawRecord(id)
+  if (direct) return direct
+  for (const sid of listSessionIds()) {
+    const r = readRawRecord(sid)
+    if (r && r.harness_session_id && r.harness_session_id === id) return r
+  }
+  return null
+}
+// every session_id this project has a record for (the board's enumeration source — replaces `git worktree
+// list`). A MISSING store dir means no session ever launched → []. But any OTHER readdir failure THROWS
+// (preserving the fail-loud-enumeration invariant `git worktree list` had): a transient FS error must never
+// read as "every session vanished" — the watch poll skips the tick on a throw, never emitting a false mass-close.
+export function listSessionIds(): string[] {
+  let ents
+  try { ents = readdirSync(sessionsRoot(), { withFileTypes: true }) }
+  catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return []; throw e }
+  return ents.filter((d) => d.isDirectory()).map((d) => d.name)
+}
+
+// memo the overlay (3 git diffs/worktree) keyed on fork-point merge-base + HEAD + spec sig — keying on the
+// merge-base NOT main's HEAD means unrelated merges that don't move the fork point stay cache hits.
+const deltaCache = new Map<string, { key: string; ops: NodeOp[] }>()
+const safeHead = (p: string): string => { try { return headSha(p) } catch { return '' } }
+const safeMergeBase = async (wtPath: string, mainRef: string): Promise<string> => {
+  try { return (await gitA(['-C', wtPath, 'merge-base', mainRef, 'HEAD'])).trim() } catch { return '' }
+}
+let layoutHeadWarned = false
+async function cachedDelta(wtPath: string, mainRef: string): Promise<NodeOp[]> {
+  const wtHead = safeHead(wtPath)
+  const base = await safeMergeBase(wtPath, mainRef)
+  // fail loud, never stale: if the merge-base or HEAD can't be read the key is untrustworthy — bypass the
+  // cache and recompute (warn once) rather than risk serving a delta keyed on an empty sha across a real change.
+  if (!base || !wtHead) {
+    if (!layoutHeadWarned) { layoutHeadWarned = true; console.warn('spec-cli: layout overlay cache bypassed (unreadable merge-base/HEAD), recomputing every read') }
+    return worktreeSpecDelta(wtPath, mainRef)
+  }
+  const key = `${base}\0${wtHead}\0${worktreeSpecSig(wtPath)}`
+  const hit = deltaCache.get(wtPath)
+  if (hit && hit.key === key) return hit.ops
+  const ops = await worktreeSpecDelta(wtPath, mainRef, base)
+  deltaCache.set(wtPath, { key, ops })
+  return ops
+}
+
+export async function resolveLayout(): Promise<Layout> {
+  const root = repoRoot()
+  const main = dirname(gitCommonDir())   // the main checkout — same answer from main OR any linked worktree
+  const cfg = readConfig(main)
+  const base = mainBranch()
+  const convention: Convention = {
+    main: cfg.main || '',
+    mainBranch: base,
+    branchPrefix: cfg.branchPrefix ?? 'node/',
+  }
+  const mainRef = base
+  // the board enumerates the GLOBAL per-session store (NOT `git worktree list`): every GOVERNED record this
+  // project owns, each carrying the worktree_path its spec-delta is computed from. Non-governed (user-self-
+  // launched) records are excluded — board state is a managed-session concern ([[state]]). Each delta is
+  // independent → compute (or cache-hit) in parallel, keyed by worktree path as before. guardWorktree wraps
+  // each: a worktree whose dir was genuinely removed mid-read (a worker self-merged + retired it) is OMITTED;
+  // one that still exists but hit a transient detail failure is kept as a DEGRADED row from the last cached delta.
+  const records = listSessionIds().map(readRawRecord).filter((r): r is RawRecord => !!r && r.governed)
+  const rows = await Promise.all(records.map((r) => {
+    const node = r.node ?? (r.branch && r.branch.startsWith(convention.branchPrefix) ? r.branch.slice(convention.branchPrefix.length) : null)
+    const base: Worktree = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ops: [] }
+    return guardWorktree<Worktree>(r.worktree_path,
+      async (): Promise<Worktree> => ({ ...base, ops: await cachedDelta(r.worktree_path, mainRef) }),
+      (): Worktree => ({ ...base, ops: deltaCache.get(r.worktree_path)?.ops ?? [] }))
+  }))
+  const sessionWorktrees = rows.filter((w): w is Worktree => w !== null)
+  // the main checkout row (isMain) — always present, carries no overlay; it anchors the merged tree the board draws.
+  const mainRow: Worktree = { path: main, branch: base, node: null, session: null, status: null, isMain: true, ops: [] }
+  const worktrees = [mainRow, ...sessionWorktrees]
+  // drop cache entries for worktrees no longer in the store (closed sessions), so the map stays bounded.
+  const live = new Set(sessionWorktrees.map((w) => w.path))
+  for (const k of [...deltaCache.keys()]) if (!live.has(k)) deltaCache.delete(k)
+  return { main: convention.main || main || root, convention, worktrees }
+}