spexcode 0.1.0

package/src/lint.ts

@@ -0,0 +1,206 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { repoRoot, stagedFiles } from './git.js'
+import { loadSpecs } from './specs.js'
+
+export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
+
+export type LintConfig = {
+  governedRoots: string[]       // dirs whose source files must each be governed by a spec (coverage)
+  sourceExtensions: string[]    // extensions coverage treats as source files
+  identifierExtensions: string[]// extensions the altitude bare-filename signal recognises (see IDENT below)
+  altitude: { lineBudget: number; charBudget: number; sizeable: number; dense: number; steps: number }
+  maxChildren: number        // breadth budget: warn at >= this many direct children
+  driftErrorThreshold: number// commit-local gate HARD-BLOCKS a commit touching a node >= this many commits behind
+  maxOwners: number          // warn when a file is governed (code:) by > this many nodes
+}
+const DEFAULT_CONFIG: LintConfig = {
+  governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
+  sourceExtensions: ['ts', 'tsx', 'js', 'jsx'],
+  identifierExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'md'],
+  altitude: { lineBudget: 50, charBudget: 4200, sizeable: 35, dense: 1.3, steps: 3 },
+  maxChildren: 8,
+  driftErrorThreshold: 3,
+  maxOwners: 3,
+}
+export function loadConfig(root: string): LintConfig {
+  try {
+    const raw = JSON.parse(readFileSync(join(root, 'spexcode.json'), 'utf8'))
+    const c = raw?.lint ?? {}
+    return { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
+  } catch {
+    return DEFAULT_CONFIG   // no file (or unreadable) → tuned defaults; lint is the same as before.
+  }
+}
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.vite'])
+
+function sourceFiles(root: string, rel: string, acc: string[], src: RegExp) {
+  const abs = join(root, rel)
+  if (!existsSync(abs)) return
+  for (const e of readdirSync(abs, { withFileTypes: true })) {
+    if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) sourceFiles(root, join(rel, e.name), acc, src) }
+    else if (src.test(e.name)) acc.push(join(rel, e.name))
+  }
+}
+
+// code-identifier signals: camelCase | snake_case | foo( | `backticked` | /a/path.ext | bare file.ext. Only
+// the bare-filename branch needs the extension allowlist (config, so a non-TS project recognises its own
+// sources) — without it a bare `word.word` would match ordinary prose like "e.g".
+function identRe(extensions: string[]): RegExp {
+  const ext = extensions.join('|')
+  return new RegExp(`[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*|\\b[a-z]+_[a-z0-9_]+\\b|\\b\\w+\\(|\`[^\`]+\`|\\/[\\w./-]+\\.\\w+|\\b[\\w-]+\\.(${ext})\\b`, 'g')
+}
+// step-by-step how-to phrasing: numbered steps, or sequencing connectives that walk through mechanics.
+const STEP_LINE = /^\s*(\d+[.)]\s|[-*]\s*(first|then|next|finally)\b)|(^|[,;]\s*)(first|then|next|finally),/i
+// returns a one-line reason naming whichever low-altitude proxy(ies) tripped (length / identifier density /
+// step-by-step), or null when the body is at altitude.
+function altitude(body: string, cfg: LintConfig, ident: RegExp): string | null {
+  const a = cfg.altitude
+  const lines = body.split('\n')
+  const nb = lines.filter((l) => l.trim()).length
+  const chars = body.length
+  // identifiers and step phrasing are read from PROSE only — a fenced code sample is acknowledged code,
+  // not low-altitude narration, so it inflates length but not density.
+  let inFence = false, signals = 0, steps = 0
+  for (const l of lines) {
+    if (/^\s*```/.test(l)) { inFence = !inFence; continue }
+    if (inFence || !l.trim()) continue
+    signals += l.match(ident)?.length ?? 0
+    if (STEP_LINE.test(l)) steps++
+  }
+  const density = signals / Math.max(1, nb)
+  const why: string[] = []
+  if (nb > a.lineBudget || chars > a.charBudget) why.push(`${nb} non-blank lines / ${chars} chars over budget (${a.lineBudget}/${a.charBudget})`)
+  if (nb > a.sizeable && density > a.dense) why.push(`code-identifier density ${density.toFixed(2)}/line over ${a.dense}`)
+  if (nb > a.sizeable && steps >= a.steps) why.push(`${steps} step-by-step how-to lines`)
+  return why.length ? why.join('; ') : null
+}
+
+export async function specLint(): Promise<Finding[]> {
+  const root = repoRoot()
+  const cfg = loadConfig(root)
+  const ident = identRe(cfg.identifierExtensions)
+  const srcRe = new RegExp(`\\.(${cfg.sourceExtensions.join('|')})$`)
+  const specs = await loadSpecs()
+  const out: Finding[] = []
+
+  // integrity + build the file -> owners map.
+  const owners = new Map<string, string[]>()
+  for (const s of specs) {
+    for (const f of s.code) {
+      if (!existsSync(join(root, f)))
+        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
+      owners.set(f, [...(owners.get(f) ?? []), s.id])
+    }
+  }
+  // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
+  // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
+  // related, not govern (see [[governed-related]]). It carries coverage but never drift/yatsu.
+  const claimed = new Set<string>(owners.keys())
+  for (const s of specs) for (const f of s.related) {
+    if (!existsSync(join(root, f)))
+      out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
+    claimed.add(f)
+  }
+
+  // living: a spec body describes the node's CURRENT intent — it is not a changelog. Version history
+  // (every content commit, its reason/session/line-diff) is read from git and shown in the dashboard's
+  // recent/history tabs, so a `## vN`-style heading in the body is duplicated, drift-prone state.
+  // Reject it. Fence-aware — a `## v2` inside a ``` block is sample text, not a heading.
+  const VER_HEADING = /^#{1,6}\s+v\d+\b/
+  for (const s of specs) {
+    let inFence = false
+    for (const line of s.body.split('\n')) {
+      if (/^\s*```/.test(line)) { inFence = !inFence; continue }
+      if (!inFence && VER_HEADING.test(line))
+        out.push({ level: 'error', rule: 'living', spec: s.id, msg: `'${s.id}' has a changelog heading "${line.trim()}" — keep the body current-state; version history lives in git (recent/history tabs)` })
+    }
+  }
+
+  // altitude: a body that re-narrates mechanics instead of stating contract/intent (WARN — soft budget).
+  for (const s of specs) {
+    const why = altitude(s.body, cfg, ident)
+    if (why) out.push({ level: 'warn', rule: 'altitude', spec: s.id, msg: `'${s.id}' body reads low-altitude (mechanics, not contract): ${why}` })
+  }
+
+  // breadth: a node with too many DIRECT children is altitude's structural twin — splitting a node to pass
+  // altitude shouldn't just relocate the sprawl into a wide flat fan-out (WARN — soft, advisory). Children
+  // are derived from the parent links loadSpecs already computes; no explicit child array to keep in sync.
+  const childCount = new Map<string, number>()
+  for (const s of specs) if (s.parent) childCount.set(s.parent, (childCount.get(s.parent) ?? 0) + 1)
+  for (const s of specs) {
+    const n = childCount.get(s.id) ?? 0
+    if (n >= cfg.maxChildren)
+      out.push({ level: 'warn', rule: 'breadth', spec: s.id, msg: `'${s.id}' has ${n} direct child nodes (>= ${cfg.maxChildren}) — is an intermediate grouping layer missing? (a flat list of genuine peers is sometimes right — ignore if so)` })
+  }
+
+  // coverage: every governed source file must be claimed by at least one spec.
+  const governed: string[] = []
+  for (const r of cfg.governedRoots) sourceFiles(root, r, governed, srcRe)
+  // no governed source found at all → the defaults name this repo's own dirs, so an adopter who never set
+  // lint.governedRoots would otherwise see a falsely-clean board. Make it loud and point at the knob.
+  if (governed.length === 0)
+    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — no source files under governedRoots [${cfg.governedRoots.join(', ')}]. Set lint.governedRoots in spexcode.json to your project's source dirs.` })
+  for (const f of governed)
+    if (!claimed.has(f)) out.push({ level: 'warn', rule: 'coverage', file: f, msg: `no spec governs: ${f}` })
+
+  // too-many-owners: many nodes governing one file is ordinary composition (drift fans to each — correct,
+  // every owner has a stake), so this is NOT flagged. Only an OVER-owned file is a smell — governed by more
+  // than maxOwners nodes, it has accreted more independently-specified functionality than one file should
+  // hold (see [[governed-related]]). ONE summary line (not one per file — its own wall of noise): the count,
+  // the worst offenders, and the remedy, which blames the FILE not the ownership — SPLIT it so each governor
+  // reclaims its own module; or merge the nodes if they're one concern; or give it a single foundation owner.
+  const over = [...owners].filter(([, ids]) => ids.length > cfg.maxOwners).sort((a, b) => b[1].length - a[1].length)
+  if (over.length) {
+    const top = over.slice(0, 5).map(([f, ids]) => `${f.split('/').pop()}(${ids.length})`).join(', ')
+    out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
+  }
+
+  // drift: a governed file has commits NOT yet reflected in its spec. Rigorous by git ancestry —
+  // loadSpecs computes `driftFiles` via `git rev-list <spec's last version>..HEAD -- <file>` (see
+  // commitsSince in git.ts), so each warning is "N commit(s) ahead", not a timestamp guess.
+  for (const s of specs) {
+    for (const d of s.driftFiles)
+      out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
+  }
+
+  return out
+}
+
+export const DRIFT_GUIDANCE = `DRIFT — a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth
+broke along  raw intent → expanded spec → code: link → code structure → implementation, fix THAT layer.
+
+  Inspect:  spex lint                                                       which files, against which spec
+            the node's spec.md                                             its raw source + expanded spec
+            git diff $(git log -1 --format=%H -- <spec.md>)..HEAD -- <file>   the code delta since the spec
+
+Diagnose, then apply the one honest remedy:
+  • contract changed        → rewrite the spec body to the new intent, commit it (re-versions the node)
+  • only mechanics changed  → spex ack <node>   "checked — spec still valid"   (give a real reason)
+  • implementation is WRONG → the spec is right; fix the CODE back toward it, then ack
+  • wrong code: link        → the node shouldn't own this file (or owns it too broadly); fix frontmatter
+  • expanded spec ≠ raw     → the spec drifted from human intent; fix the expanded spec to serve the raw
+  • structural mismatch     → one file owned by many specs / a feature with no home: refactor so a file
+                              maps to a node, or file an issue and link it (defer honestly)
+
+Never patch. A reasoned ack or a real fix are recorded and re-judged at review; a blind ack is a lie.`
+
+// commit-local: an empty staged index (CI, audit) → no blockers, drift stays advisory; non-empty → block
+// only when an OWN staged file belongs to a node already >= driftErrorThreshold behind. Sub-threshold drift
+// on a touched node is returned for an advisory nudge; the backlog on untouched nodes never blocks.
+export async function driftGate(): Promise<{ blocked: string[]; touched: { id: string; drift: number }[]; threshold: number }> {
+  const root = repoRoot()
+  const cfg = loadConfig(root)
+  const staged = stagedFiles(root)
+  if (!staged.length) return { blocked: [], touched: [], threshold: cfg.driftErrorThreshold }
+  const specs = await loadSpecs()
+  const owners = new Map<string, string[]>()
+  for (const s of specs) for (const f of s.code) owners.set(f, [...(owners.get(f) ?? []), s.id])
+  const byId = new Map(specs.map((s) => [s.id, s]))
+  const ids = new Set<string>()
+  for (const f of staged) for (const o of owners.get(f) ?? []) ids.add(o)
+  const touched = [...ids].map((id) => byId.get(id)!).filter((s) => s && s.drift > 0)
+    .map((s) => ({ id: s.id, drift: s.drift })).sort((a, b) => b.drift - a.drift)
+  return { blocked: touched.filter((t) => t.drift >= cfg.driftErrorThreshold).map((t) => t.id), touched, threshold: cfg.driftErrorThreshold }
+}

package/src/login-page.ts

@@ -0,0 +1,79 @@
+// @@@ login page - the gateway's gate is a DESIGNED page, not the browser's Basic-auth dialog (which can't
+// be styled and feels like a 1998 intranet). Self-contained: inline CSS + SVG, zero external assets, so it
+// renders before anything is authorised. Dark, calm, a single password field; an error state when the
+// password is wrong. The form POSTs to /login (same-origin), which mints the auth cookie and redirects.
+export function loginPage(error = false): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SpexCode — sign in</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    color: #e7ecf3;
+    background:
+      radial-gradient(900px 600px at 50% -10%, #1b2b4d 0%, rgba(27,43,77,0) 60%),
+      radial-gradient(700px 500px at 85% 110%, #1d3b39 0%, rgba(29,59,57,0) 55%),
+      #080b12;
+  }
+  .card {
+    width: min(92vw, 360px); padding: 38px 34px 30px;
+    background: linear-gradient(180deg, rgba(22,28,40,0.92), rgba(15,19,28,0.92));
+    border: 1px solid rgba(120,150,200,0.16); border-radius: 18px;
+    box-shadow: 0 30px 80px -30px rgba(0,0,0,0.8), inset 0 1px 0 rgba(255,255,255,0.04);
+    backdrop-filter: blur(8px);
+  }
+  .mark { display: flex; align-items: center; gap: 11px; margin-bottom: 26px; }
+  .mark svg { width: 30px; height: 30px; }
+  .mark b { font-size: 17px; font-weight: 650; letter-spacing: 0.2px; }
+  .mark b span { color: #6ea0ff; }
+  h1 { font-size: 15px; font-weight: 550; margin: 0 0 4px; }
+  p.sub { margin: 0 0 22px; font-size: 12.5px; line-height: 1.5; color: #8b97aa; }
+  label { display: block; font-size: 11px; letter-spacing: 0.4px; text-transform: uppercase; color: #8b97aa; margin: 0 0 8px; }
+  input {
+    width: 100%; padding: 12px 14px; font-size: 14px; color: #eef2f8;
+    background: #0c1019; border: 1px solid rgba(120,150,200,0.22); border-radius: 11px;
+    outline: none; transition: border-color .15s, box-shadow .15s;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: 2px;
+  }
+  input:focus { border-color: #4f7fe0; box-shadow: 0 0 0 3px rgba(79,127,224,0.18); }
+  button {
+    width: 100%; margin-top: 16px; padding: 12px 14px; font-size: 14px; font-weight: 600;
+    color: #fff; cursor: pointer; border: 0; border-radius: 11px;
+    background: linear-gradient(180deg, #4f86f7, #3f6fe0);
+    box-shadow: 0 8px 22px -8px rgba(63,111,224,0.7); transition: filter .15s, transform .05s;
+  }
+  button:hover { filter: brightness(1.07); }
+  button:active { transform: translateY(1px); }
+  .err {
+    margin: 0 0 16px; padding: 9px 12px; font-size: 12.5px; border-radius: 9px;
+    color: #ffd2cf; background: rgba(220,80,70,0.12); border: 1px solid rgba(220,80,70,0.32);
+  }
+  .foot { margin-top: 22px; font-size: 11px; color: #69748a; text-align: center; line-height: 1.5; }
+</style>
+</head>
+<body>
+  <form class="card" method="POST" action="/login" autocomplete="off">
+    <div class="mark">
+      <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <rect x="2" y="2" width="28" height="28" rx="8" fill="#0e1626" stroke="#3f6fe0" stroke-opacity="0.5"/>
+        <path d="M11 12.5C11 10.6 12.6 9 14.5 9h3a3.5 3.5 0 0 1 0 7h-3a3.5 3.5 0 0 0 0 7h3c1.9 0 3.5-1.6 3.5-3.5" stroke="#6ea0ff" stroke-width="2" stroke-linecap="round"/>
+      </svg>
+      <b>Spex<span>Code</span></b>
+    </div>
+    <h1>Restricted access</h1>
+    <p class="sub">This is a private agent workspace. Enter the access password to continue.</p>
+    ${error ? '<div class="err">Incorrect password — try again.</div>' : ''}
+    <label for="password">Password</label>
+    <input id="password" name="password" type="password" autofocus required placeholder="••••••••••">
+    <button type="submit">Sign in</button>
+    <div class="foot">Trusted collaborators only.</div>
+  </form>
+</body>
+</html>`
+}

package/src/materialize.ts

@@ -0,0 +1,85 @@
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+import { loadSystemConfig, loadSkillConfig } from './specs.js'
+import { compileManifest } from './hooks.js'
+import { HARNESSES, writeManagedBlock } from './harness.js'
+import { runtimeRoot } from './layout.js'
+
+// @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
+// .config content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each
+// consumer reads cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the
+// whole system via harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it),
+// (2) the CONTRACT as a managed <spexcode> block in each harness's contract file(s) — user content
+// preserved, (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST (Codex's deterministic
+// trusted_hash; Claude none) so the self-launch is zero-prompt. EVERY harness-specific fact is owned by the
+// [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES, so adding a harness adds an adapter,
+// not a branch here. All writes are idempotent + scoped. The content-hash marker is stamped last.
+
+const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
+const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
+const SPEX = `${join(PKG, 'node_modules', '.bin', 'tsx')} ${join(PKG, 'src', 'cli.ts')}`
+// the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
+// worktree — the worktree keeps zero SpexCode-rendered runtime; only the harness-discovered contract files +
+// shims (which the harness must find in-tree) are written under proj below.
+
+// the deterministic content fingerprint of the config roots. ONE definition — `hp_config_hash` in the shell
+// mirror (harness.sh) — which the dispatch.sh gate ALSO calls, so the gate and this renderer can never disagree
+// on "changed" (they used to inline the identical find-pipeline in two places, each commenting the other "MUST match").
+export function contentHash(proj: string): string {
+  try {
+    const harnessSh = join(PKG, 'hooks', 'harness.sh')
+    return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`]).toString().trim()
+  } catch { return '' }
+}
+
+// the whole pay-per-change render. proj defaults to cwd. Returns the new content-hash it stamped.
+export function materialize(proj = process.cwd()): string {
+  const rt = runtimeRoot(proj)                                            // global per-project store, not the worktree
+  mkdirSync(rt, { recursive: true })
+  // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
+  writeFileSync(join(rt, 'hooks-manifest'), compileManifest())
+  // (2) the contract = the surface:system bodies, in name order, written into EACH harness's contract file(s)
+  //     + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
+  const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n')
+  // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
+  // over the body instructions. One pure render shared by every harness — divergence is only its skillDir.
+  const renderSkill = (sk: { name: string; desc: string; body: string }) =>
+    `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n`
+  const shimPaths: string[] = []
+  for (const h of HARNESSES) {
+    if (contract) for (const f of h.contractFiles(proj)) writeManagedBlock(f, contract)
+    const shimFile = h.shimFile(proj)
+    mkdirSync(dirname(shimFile), { recursive: true })
+    const shim = h.shim(DISPATCH, SPEX)
+    writeFileSync(shimFile, shim.json)
+    h.writeTrust(proj, shim.cmd)
+    shimPaths.push(relative(proj, shimFile))
+  }
+  // (6) skills - each `surface: skill` node → a SKILL.md the harness auto-discovers, written into every
+  //     harness's own skillDir (Claude .claude/skills, Codex .codex/skills). Generated wiring, so the paths
+  //     join the same managed .gitignore block below. A harness with no skill primitive (skillDir null) is skipped.
+  for (const sk of loadSkillConfig()) {
+    for (const h of HARNESSES) {
+      const dir = h.skillDir(proj); if (!dir) continue
+      const f = join(dir, sk.name, 'SKILL.md')
+      mkdirSync(dirname(f), { recursive: true })
+      writeFileSync(f, renderSkill(sk))
+      shimPaths.push(relative(proj, f))   // reuse the same managed .gitignore block
+    }
+  }
+  // (4b) the shims are machine-specific generated wiring (they bake this machine's absolute install path), so
+  // gitignore them — regenerated per-machine by this same gate. Derived from the adapters' shimFile(), not
+  // hardcoded; written as a managed `#` block so the user's own .gitignore is preserved. Keeps the worktree
+  // free of tracked machine-specific files (the contract md files stay tracked — they carry the user's prose).
+  // only ignore paths that live INSIDE proj. The codex hooks shim now materializes at the MAIN checkout (codex
+  // reads a linked worktree's hooks from the root checkout — see harness.ts); from a linked worktree that path
+  // escapes proj (`../…`) and is gitignored by the main checkout's OWN materialize, not the worktree's.
+  const ignorable = shimPaths.filter((p) => !p.startsWith('..'))
+  if (ignorable.length) writeManagedBlock(join(proj, '.gitignore'), ignorable.sort().join('\n'), ['# ', ''])
+  // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
+  const h = contentHash(proj)
+  writeFileSync(join(rt, 'content-hash'), h)
+  return h
+}

package/src/pty-bridge.ts

@@ -0,0 +1,235 @@
+import * as pty from 'node-pty'
+import type { IPty } from 'node-pty'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { listSessions, alive } from './sessions.js'
+
+const pexec = promisify(execFile)
+const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
+// cold fallback size for a session no viewer has ever sized (see lastFit).
+const DEFAULT_COLS = 120, DEFAULT_ROWS = 40
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+// a viewer: anything we can push pane bytes to (a WebSocket, wrapped).
+export type Viewer = { send: (data: Buffer) => void }
+
+type Bridge = { id: string; pty: IPty; cols: number; rows: number; prewarmed: boolean; clientTty?: string; repaintToken: number }
+const bridges = new Map<string, Bridge>()
+// viewers keyed by session id (not the Bridge), so a subscription outlives any bridge death/respawn.
+const subscribers = new Map<string, Set<Viewer>>()
+
+// last size each viewer fitted (per session + a global fallback), so pre-warm spawns at the wanted size.
+const lastFit = new Map<string, { cols: number; rows: number }>()
+let lastFitAny: { cols: number; rows: number } | null = null
+function prewarmSize(id: string): { cols: number; rows: number } {
+  return lastFit.get(id) ?? lastFitAny ?? { cols: DEFAULT_COLS, rows: DEFAULT_ROWS }
+}
+
+async function tmuxRaw(args: string[]): Promise<void> {
+  try { await pexec('tmux', ['-L', TMUX_SOCK, ...args]) } catch { /* best-effort */ }
+}
+// how many clients are attached — pre-warm skips a session a human is already in (avoids a size-fight).
+async function attachedCount(id: string): Promise<number> {
+  try {
+    const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, 'display-message', '-p', '-t', id, '-F', '#{session_attached}'])
+    return Number(stdout.trim()) || 0
+  } catch { return 0 }
+}
+
+// mouse on + deep history. set -g is the server default: mouse is inherited live, history-limit applies
+// only to panes created afterwards.
+let optsEnsured = false
+async function ensureTmuxOpts(): Promise<void> {
+  if (optsEnsured) return
+  optsEnsured = true
+  await tmuxRaw(['set', '-g', 'mouse', 'on'])
+  await tmuxRaw(['set', '-g', 'history-limit', '50000'])
+}
+
+// spawn the shared tmux client for a session (idempotent). Returns null if node-pty can't spawn.
+function ensureBridge(id: string, prewarm = false): Bridge | null {
+  let b = bridges.get(id)
+  if (b) { if (prewarm) b.prewarmed = true; return b }
+  // spawn at the last-known viewer size so a pre-warmed bridge already matches the dashboard's pane.
+  const { cols, rows } = prewarmSize(id)
+  let p: IPty
+  try {
+    // -u + a UTF-8 LANG force this client to emit UTF-8 even when the host locale is empty (a LaunchAgent
+    // gives LANG="" → tmux substitutes `_` for every wide char).
+    p = pty.spawn('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], {
+      name: 'xterm-256color', cols, rows,
+      env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' } as Record<string, string>,
+    })
+  } catch { return null }
+  b = { id, pty: p, cols, rows, prewarmed: prewarm, repaintToken: 0 }
+  bridges.set(id, b)
+  // tmux output → broadcast as raw bytes to every viewer in `subscribers` (which survives a bridge swap).
+  p.onData((data) => {
+    const buf = Buffer.from(data, 'utf8')
+    for (const v of subscribers.get(id) ?? []) { try { v.send(buf) } catch { /* drop a wedged viewer */ } }
+  })
+  // attach-session exited (session died or we detached): drop the bridge, and if viewers remain kick a
+  // reconcile to re-bind fast instead of waiting a full tick (the kick is alive-gated + serialized).
+  p.onExit(() => {
+    if (bridges.get(id) === b) bridges.delete(id)
+    if ((subscribers.get(id)?.size ?? 0) > 0) kickSupervisor()
+  })
+  return b
+}
+
+function killBridge(id: string): void {
+  const b = bridges.get(id)
+  if (!b) return
+  bridges.delete(id)
+  try { b.pty.kill() } catch { /* already gone */ }
+}
+
+// a browser viewer connects: subscribe it to the (warm or fresh) bridge, then settleAndRepaint for one
+// coherent frame (a refresh-client down the same pty, never a spliced capture-pane snapshot).
+export function attachViewer(id: string, v: Viewer): boolean {
+  let s = subscribers.get(id)
+  if (!s) subscribers.set(id, s = new Set())
+  s.add(v)
+  const b = ensureBridge(id)
+  if (!b) return false   // spawn failed → caller closes the socket → detachViewer prunes this subscriber
+  void settleAndRepaint(b)
+  return true
+}
+// our attach client's tty, matched by pid (b.pty.pid === client_pid) and cached. refresh-client must
+// target OUR client so the redraw hits only the dashboard's pty, not a human sharing the same session.
+async function clientTty(b: Bridge): Promise<string | null> {
+  if (b.clientTty) return b.clientTty
+  try {
+    const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, 'list-clients', '-t', b.id, '-F', '#{client_pid} #{client_tty}'])
+    for (const line of stdout.split('\n')) {
+      const sp = line.indexOf(' ')
+      if (sp > 0 && Number(line.slice(0, sp)) === b.pty.pid) return (b.clientTty = line.slice(sp + 1).trim())
+    }
+  } catch { /* client not registered yet; a size-changing open resize will repaint instead */ }
+  return null
+}
+// force a full coherent repaint of our client down the shared pty. On a fresh respawn the new client may
+// not be registered yet (clientTty briefly null), so retry until it resolves, bounded (~0.5s); a newer
+// token supersedes us so we never clobber a fresher size.
+async function repaint(b: Bridge, token: number): Promise<void> {
+  for (let i = 0; i < 24; i++) {
+    if (token !== b.repaintToken) return
+    const tty = await clientTty(b)
+    if (tty) { await tmuxRaw(['refresh-client', '-t', tty]); return }
+    await sleep(20)
+  }
+}
+// tmux's actual pane geometry for our session — the ground truth we wait on before repainting.
+async function paneSize(b: Bridge): Promise<{ cols: number; rows: number } | null> {
+  try {
+    const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, 'display-message', '-p', '-t', b.id, '-F', '#{pane_width}x#{pane_height}'])
+    const m = stdout.trim().match(/^(\d+)x(\d+)$/)
+    if (m) return { cols: Number(m[1]), rows: Number(m[2]) }
+  } catch { /* session momentarily ungettable; treat as not-yet-settled */ }
+  return null
+}
+// every (re)attach and resize routes here. A per-bridge token coalesces a burst (attach + open-time
+// resize) to one run: settle, poll tmux's real pane geometry until it equals the size we asked for, then
+// fire a single refresh-client. A newer token supersedes us at every checkpoint. Bounded (~0.5s).
+async function settleAndRepaint(b: Bridge): Promise<void> {
+  const token = ++b.repaintToken
+  await sleep(30)                                   // coalesce an attach+resize burst to the final size
+  for (let i = 0; i < 24; i++) {
+    if (token !== b.repaintToken) return            // superseded by a newer attach/resize → let it win
+    const sz = await paneSize(b)
+    if (sz && sz.cols === b.cols && sz.rows === b.rows) break
+    await sleep(20)
+  }
+  if (token !== b.repaintToken) return
+  await repaint(b, token)
+}
+export function detachViewer(id: string, v: Viewer): void {
+  const s = subscribers.get(id)
+  if (!s) return
+  s.delete(v)
+  if (s.size > 0) return
+  // last viewer gone → drop the registry entry, then release the client unless it's kept warm. An empty
+  // subscriber set is the single authority for "no one watching" (used here and in the supervisor reap).
+  subscribers.delete(id)
+  const b = bridges.get(id)
+  if (b && !b.prewarmed) killBridge(id)
+}
+// raw terminal input (keystrokes + mouse) straight into the shared tmux client.
+export function writeViewer(id: string, data: Buffer): void {
+  bridges.get(id)?.pty.write(data.toString('utf8'))
+}
+// a viewer fitted xterm → record the size as the last-known fit (even with no bridge yet, for pre-warm)
+// and resize the shared client. Repaints even on an unchanged size (a reconnect needs the frame).
+export function resizeBridge(id: string, cols: number, rows: number): void {
+  if (!(cols > 0 && rows > 0)) return
+  lastFit.set(id, { cols, rows }); lastFitAny = { cols, rows }
+  const b = bridges.get(id)
+  if (b) applySize(b, cols, rows)
+}
+// resize the client + repaint WITHOUT recording a viewer fit — the primitive both a real resize and the
+// supervisor's pre-sizing share, so the supervisor can't clobber lastFit/lastFitAny with a stale value.
+function applySize(b: Bridge, cols: number, rows: number): void {
+  if (cols !== b.cols || rows !== b.rows) {
+    b.cols = cols; b.rows = rows
+    try { b.pty.resize(cols, rows) } catch { /* dead pty; next fit/tick retries */ }
+  }
+  void settleAndRepaint(b)
+}
+
+// one reconcile pass: warm a bridge per live session, re-bind a watched session whose pty died, reap a
+// dead+unwatched bridge. Re-bind lives here (not pty.onExit) because this pass is alive-gated and
+// rate-limited, so a flaky session can't storm respawns.
+async function reconcileOnce(): Promise<void> {
+  const live = new Set<string>()
+  for (const s of await listSessions()) {
+    if (!(await alive(s.id))) continue
+    live.add(s.id)
+    // already ours → keep warm and resize a stale warm bridge to the last-known viewer size off-screen,
+    // so a first open finds the pane already at its size. The size-diff guard makes a converged bridge a no-op.
+    const existing = bridges.get(s.id)
+    if (existing) {
+      existing.prewarmed = true
+      const want = prewarmSize(s.id)
+      if (want.cols !== existing.cols || want.rows !== existing.rows) applySize(existing, want.cols, want.rows)
+      continue
+    }
+    // no bridge for a live session: viewers waiting → re-bind and settleAndRepaint (nothing else re-arms an
+    // idle pane); else pre-warm an idle detached session, but only if no human client is already attached.
+    if ((subscribers.get(s.id)?.size ?? 0) > 0) {
+      const b = ensureBridge(s.id, true)
+      if (b) void settleAndRepaint(b)
+    } else if ((await attachedCount(s.id)) === 0) {
+      ensureBridge(s.id, true)
+    }
+  }
+  for (const [id, b] of bridges) {
+    if (live.has(id)) continue
+    if ((subscribers.get(id)?.size ?? 0) === 0) killBridge(id)   // dead + unwatched → release
+    else b.prewarmed = false                                     // dead but still watched → serve until they leave
+  }
+}
+
+// serialize reconcile passes (one running, one queued), so a burst of onExit kicks collapses to one rerun.
+let reconciling = false
+let reconcilePending = false
+async function runReconcile(): Promise<void> {
+  if (reconciling) { reconcilePending = true; return }
+  reconciling = true
+  try { await reconcileOnce() } catch { /* transient git/tmux hiccup; the periodic tick retries */ }
+  reconciling = false
+  if (reconcilePending) { reconcilePending = false; void runReconcile() }
+}
+
+let supervising = false
+export function superviseBridges(intervalMs = 4000): void {
+  if (supervising) return
+  supervising = true
+  void ensureTmuxOpts()
+  const tick = () => { void runReconcile(); setTimeout(tick, intervalMs) }
+  tick()
+}
+
+// a watched bridge's pty died — recover now instead of waiting a full tick (alive-gated + serialized).
+function kickSupervisor(): void {
+  if (supervising) void runReconcile()
+}