spexcode 0.5.2 → 0.5.3

package/spec-cli/src/maintenance-wrapper.ts

@@ -0,0 +1,276 @@
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import type { Duplex, Readable, Writable } from 'node:stream'
+import type { Capability, LeaseOwner, MaintenanceState } from './session-maintenance.js'
+import { processStartToken } from './process-identity.js'
+import {
+  clientMaintenanceAcquire,
+  clientMaintenanceHeartbeat,
+  clientMaintenanceOperation,
+  clientMaintenanceRelease,
+  clientMaintenanceStatus,
+} from './client.js'
+
+type BrokerRequest = {
+  v?: number
+  id?: string
+  op?: string
+  sessionId?: string
+  force?: boolean
+  client?: { pid?: number; startToken?: string }
+}
+type PlannedCapability = {
+  capability: Capability
+  state: 'unused' | 'inflight' | 'committed' | 'indeterminate'
+  requestId?: string
+}
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+const capabilityKey = (capability: Capability): string => JSON.stringify(capability)
+const capabilityList = (rows: unknown): Capability[] => Array.isArray(rows)
+  ? rows.map((row: any) => row?.capability ?? row)
+  : []
+const sameCapabilities = (left: readonly Capability[], right: readonly Capability[]): boolean =>
+  JSON.stringify(left) === JSON.stringify(right)
+const sameOwner = (left: LeaseOwner | null | undefined, right: LeaseOwner): boolean =>
+  !!left && left.instanceId === right.instanceId && left.pid === right.pid && left.startToken === right.startToken
+const assertLeaseView = (view: Pick<MaintenanceState, 'state' | 'epoch' | 'owner' | 'capabilities'>, epoch: number, owner: LeaseOwner, capabilities: readonly Capability[], allowDraining = false) => {
+  if (view.epoch !== epoch || (!allowDraining && view.state !== 'active') || (allowDraining && view.state !== 'active' && view.state !== 'draining'))
+    throw new Error('maintenance lease changed epoch or state')
+  if (!sameOwner(view.owner, owner)) throw new Error('maintenance lease owner generation changed')
+  if (!sameCapabilities(capabilityList(view.capabilities), capabilities)) throw new Error('maintenance lease changed its capability plan')
+}
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+const reapCommandGroup = async (child: ReturnType<typeof spawn>, closed: Promise<[number | null, NodeJS.Signals | null]>) => {
+  if (!child.pid) return
+  const groupAlive = () => {
+    try { process.kill(-child.pid!, 0); return true } catch { return false }
+  }
+  if (groupAlive()) {
+    try { process.kill(-child.pid, 'SIGTERM') } catch { /* already exited */ }
+    const deadline = Date.now() + 1_000
+    while (groupAlive() && Date.now() < deadline) await wait(20)
+    if (groupAlive()) {
+      try { process.kill(-child.pid, 'SIGKILL') } catch { /* already exited */ }
+    }
+  }
+  const closedAfterReap = await new Promise<boolean>((resolve) => {
+    let settled = false
+    const finish = (value: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => finish(false), 2_000)
+    timer.unref()
+    void closed.then(() => finish(true))
+  })
+  if (!closedAfterReap) throw new Error('maintenance operator pipes did not close after exact process-group reap')
+}
+
+export async function runMaintenanceWrapper(input: {
+  capabilities: Capability[]
+  ttlMs: number
+  waitMs: number
+  command: string[]
+}): Promise<number> {
+  const acquired = await clientMaintenanceAcquire(input.capabilities, input.ttlMs, input.waitMs)
+  const { token, epoch, owner } = acquired.lease
+  const releaseable = typeof token === 'string' && /^[0-9a-f]{64}$/i.test(token) && Number.isSafeInteger(epoch)
+  let released = false
+  let authorityLost = false
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+  let child: ReturnType<typeof spawn> | null = null
+  const pendingOperations = new Set<AbortController>()
+  let closeAdmission = () => {}
+  try {
+    if (!releaseable) throw new Error('maintenance acquire returned malformed private authority')
+    if (!owner || typeof owner.instanceId !== 'string' || !Number.isInteger(owner.pid) || typeof owner.startToken !== 'string')
+      throw new Error('maintenance acquire returned malformed supervisor authority')
+    if (!sameCapabilities(capabilityList(acquired.lease.capabilities), input.capabilities)) throw new Error('maintenance acquire returned a different capability plan')
+
+    let state = acquired.lease.state
+    const activationDeadline = Date.now() + input.ttlMs
+    try {
+      while (state === 'draining') {
+        const current = await clientMaintenanceHeartbeat(token, epoch, input.ttlMs)
+        assertLeaseView(current, epoch, owner, input.capabilities, true)
+        const status = await clientMaintenanceStatus()
+        assertLeaseView(status, epoch, owner, input.capabilities, true)
+        state = status.state as 'draining' | 'active'
+        if (state !== 'active') {
+          if (Date.now() >= activationDeadline) throw new Error('maintenance acquisition did not become active before its ttl')
+          await sleep(50)
+        }
+      }
+      if (state !== 'active') throw new Error(`maintenance acquisition entered unexpected state ${state}`)
+    } catch (error) {
+      authorityLost = true
+      throw error
+    }
+    if (!input.command.length) throw new Error('maintenance wrapper needs a command after --')
+
+    const plan: PlannedCapability[] = input.capabilities.map((capability) => ({ capability: { ...capability }, state: 'unused' }))
+    let heartbeatFailure: Error | null = null
+    let heartbeatBusy = false
+    let failAuthority!: (error: Error) => void
+    const authorityFailure = new Promise<never>((_, reject) => {
+      failAuthority = (error) => {
+        if (heartbeatFailure) return
+        heartbeatFailure = error
+        reject(error)
+      }
+    })
+    heartbeat = setInterval(() => {
+      if (heartbeatBusy || heartbeatFailure) return
+      heartbeatBusy = true
+      void clientMaintenanceHeartbeat(token, epoch, input.ttlMs)
+        .then((current) => assertLeaseView(current, epoch, owner, input.capabilities))
+        .catch((error) => failAuthority(error instanceof Error ? error : new Error(String(error))))
+        .finally(() => { heartbeatBusy = false })
+    }, Math.max(250, Math.min(1_000, Math.floor(input.ttlMs / 3))))
+    heartbeat.unref()
+
+    child = spawn(input.command[0], input.command.slice(1), {
+      stdio: ['inherit', 'inherit', 'inherit', 'pipe', 'pipe', 'pipe'],
+      env: { ...process.env, SPEXCODE_MAINTENANCE_BROKER_FDS: '3,4,5' },
+      detached: true,
+    })
+    const exited = once(child, 'exit') as Promise<[number | null, NodeJS.Signals | null]>
+    const closed = once(child, 'close') as Promise<[number | null, NodeJS.Signals | null]>
+    const childStdio = child.stdio as Array<Readable | Writable | Duplex | null | undefined>
+    const requestPipe = childStdio[3] as Readable
+    const responsePipe = childStdio[4] as Writable
+    const turnPipe = childStdio[5] as Duplex
+    requestPipe.setEncoding('utf8')
+    let pending = ''
+    let serial = Promise.resolve()
+    let brokerWork = 0
+    let brokerOpen = true
+    let transportLossTimer: ReturnType<typeof setTimeout> | null = null
+    const brokerTransportLost = (error: unknown) => {
+      if (!brokerOpen || transportLossTimer) return
+      transportLossTimer = setTimeout(() => {
+        transportLossTimer = null
+        if (brokerOpen && child?.exitCode === null && child.signalCode === null) {
+          failAuthority(error instanceof Error ? error : new Error('maintenance broker transport closed while the operator command was live'))
+        }
+      }, 50)
+      transportLossTimer.unref()
+    }
+    requestPipe.on('error', brokerTransportLost)
+    requestPipe.on('end', () => brokerTransportLost(new Error('maintenance broker request pipe closed while the operator command was live')))
+    responsePipe.on('error', brokerTransportLost)
+    responsePipe.on('close', () => brokerTransportLost(new Error('maintenance broker response pipe closed while the operator command was live')))
+    turnPipe.on('error', brokerTransportLost)
+    turnPipe.on('end', () => brokerTransportLost(new Error('maintenance broker turn pipe closed while the operator command was live')))
+    closeAdmission = () => {
+      if (!brokerOpen) return
+      brokerOpen = false
+      for (const controller of pendingOperations) controller.abort(new Error('maintenance broker admission closed'))
+      if (transportLossTimer) clearTimeout(transportLossTimer)
+      transportLossTimer = null
+      try { requestPipe.destroy() } catch { /* already closed */ }
+      try { turnPipe.destroy() } catch { /* already closed */ }
+    }
+    turnPipe.on('data', (chunk: Buffer) => {
+      if (!brokerOpen) return
+      for (const byte of chunk) {
+        if (byte !== 1) return failAuthority(new Error('maintenance broker turn token was corrupted'))
+        turnPipe.write(Buffer.from([1]))
+      }
+    })
+    turnPipe.write(Buffer.from([1]))
+    const reply = (id: string | undefined, body: Record<string, unknown>) => {
+      if (brokerOpen) responsePipe.write(`${JSON.stringify({ id, ...body })}\n`)
+    }
+    const handle = async (request: BrokerRequest) => {
+      if (!brokerOpen) return
+      if (request.v !== 1 || typeof request.id !== 'string' || typeof request.op !== 'string' || typeof request.sessionId !== 'string'
+        || !Number.isInteger(request.client?.pid) || typeof request.client?.startToken !== 'string'
+        || processStartToken(request.client.pid!) !== request.client.startToken) {
+        reply(request.id, { ok: false, code: 'maintenance_invalid', error: 'malformed broker request' })
+        return
+      }
+      const candidate: Capability | null = request.op === 'stop'
+        ? { op: 'stop', sessionId: request.sessionId }
+        : request.op === 'resume' && typeof request.force === 'boolean'
+          ? { op: 'resume', sessionId: request.sessionId, force: request.force }
+          : null
+      const matching = candidate && plan.find((entry) => capabilityKey(entry.capability) === capabilityKey(candidate))
+      const planned = matching?.state === 'unused' ? matching : null
+      if (!planned) {
+        reply(request.id, {
+          ok: false,
+          code: matching ? 'maintenance_capability_used' : 'maintenance_capability_missing',
+          error: matching ? 'operation is already inflight, committed, or indeterminate' : 'operation is not in the exact maintenance plan',
+        })
+        return
+      }
+      planned.state = 'inflight'
+      planned.requestId = request.id
+      const controller = new AbortController()
+      pendingOperations.add(controller)
+      try {
+        const result = await clientMaintenanceOperation(token, candidate!, { signal: controller.signal, timeoutMs: Math.min(5_000, input.ttlMs) })
+        planned.state = result.outcome === 'committed' ? 'committed' : result.outcome === 'refused' ? 'unused' : 'indeterminate'
+        delete planned.requestId
+        reply(request.id, result)
+      } catch (error) {
+        planned.state = 'indeterminate'
+        delete planned.requestId
+        reply(request.id, { ok: false, code: 'maintenance_broker_failed', error: error instanceof Error ? error.message : String(error) })
+      } finally {
+        pendingOperations.delete(controller)
+      }
+    }
+    requestPipe.on('data', (chunk: Buffer | string) => {
+      pending += chunk.toString()
+      for (;;) {
+        const newline = pending.indexOf('\n')
+        if (newline < 0) break
+        const line = pending.slice(0, newline); pending = pending.slice(newline + 1)
+        if (!line) continue
+        brokerWork++
+        serial = serial.then(async () => {
+          try { await handle(JSON.parse(line) as BrokerRequest) }
+          catch (error) { reply(undefined, { ok: false, code: 'maintenance_broker_failed', error: error instanceof Error ? error.message : String(error) }) }
+        }).finally(() => { brokerWork-- })
+      }
+    })
+    const outcome = await Promise.race([
+      exited.then(([code, signal]) => ({ kind: 'exit' as const, code, signal })),
+      authorityFailure.catch((error) => ({ kind: 'lost' as const, error: error instanceof Error ? error : new Error(String(error)) })),
+    ])
+    if (outcome.kind === 'lost') {
+      authorityLost = true
+      closeAdmission()
+      await reapCommandGroup(child, closed)
+      throw outcome.error
+    }
+    const brokerIndeterminate = brokerWork > 0 || pendingOperations.size > 0 || pending.trim().length > 0
+    if (brokerIndeterminate) authorityLost = true
+    closeAdmission()
+    await serial
+    try { await reapCommandGroup(child, closed) }
+    catch (error) { authorityLost = true; throw error }
+    if (brokerIndeterminate) {
+      throw new Error('operator exited while a maintenance broker operation was indeterminate')
+    }
+    if (heartbeatFailure) {
+      authorityLost = true
+      throw heartbeatFailure
+    }
+    return outcome.code ?? (outcome.signal ? 1 : 0)
+  } finally {
+    if (heartbeat) clearInterval(heartbeat)
+    closeAdmission()
+    try { child?.stdio[3]?.destroy() } catch { /* child already closed */ }
+    try { child?.stdio[4]?.destroy() } catch { /* child already closed */ }
+    try { (child?.stdio as Array<Readable | Writable | null | undefined> | undefined)?.[5]?.destroy() } catch { /* child already closed */ }
+    if (releaseable && !released && !authorityLost) {
+      await clientMaintenanceRelease(token, epoch)
+      released = true
+    }
+  }
+}

package/spec-cli/src/materialize.ts

@@ -23,7 +23,7 @@ export type MaterializeResult = { contentHash: string; planted: MaterializedArti
 // a trigger. It turns 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 — the
-// tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies — written WHOLE into each
+// surface:system plugin bodies (in name order) — written WHOLE into each
 // harness's contract file(s), (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST
 // (Codex's deterministic trusted_hash; Claude none). EVERY harness-specific fact is owned by the
 // [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES.
@@ -192,13 +192,12 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   const manifest = join(rt, 'hooks-manifest')
   writeFileSync(manifest, compileManifest())
   record('hook manifest', manifest)
-  // (2) the contract = the tracked docs guide (the hand-written agent/contributor notes — the ONE piece of
-  //     in-tree prose) FOLLOWED BY the surface:system bodies (in name order), written WHOLE into EACH harness's
+  // (2) the contract = the surface:system plugin bodies (in name order), written WHOLE into EACH harness's
   //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
-  const guidePath = join(proj, 'docs', 'AGENT_GUIDE.md')
-  const guide = existsSync(guidePath) ? readFileSync(guidePath, 'utf8').trim() : ''
-  const systemBodies = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean)
-  const contract = [guide, ...systemBodies].filter(Boolean).join('\n\n')
+  // ONE source, no per-project escape hatch: the contract IS the surface:system plugin bodies. A project's
+  // own hand-written prose is not folded in — repo-local notes belong in the harness file's own
+  // block-outside region (untracked, per-clone), and anything that must reach EVERY agent is a plugin node.
+  const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n')
   // WHICH harnesses to deliver into ([[harness-select]]): the spexcode.json `harnesses` set (default = every
   // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
   const cfg = readConfig(mainCheckout(proj))

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

@@ -3,18 +3,14 @@ import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir, userInfo } from 'node:os'
 import { join } from 'node:path'
 import { promisify } from 'node:util'
-import { fileURLToPath } from 'node:url'
-import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+import { headlessTurnFailureShell, type DispatchResult, type HarnessDeliveryRecord } from './harness.js'
+import { shQuote } from './sh.js'
 
 const pexec = promisify(execFile)
-const SPEX = join(fileURLToPath(new URL('..', import.meta.url)), 'bin', 'spex.mjs')
 const WAKE_EARLY_EXIT_MS = 5_000
 const OUTCOME_POLL_MS = 25
 
-const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-const turnFailureShell = (swallow: boolean) =>
-  `${shQuote(SPEX)} internal session-turn-fail "$SPEXCODE_SESSION_ID" ${shQuote('opencode-headless')} "$__spex_rc"${swallow ? ' || true' : ''}`
 
 function accountLoginShell(): string {
   try { return userInfo().shell || '' } catch { return '' }
@@ -33,12 +29,12 @@ function turnHome(command: string, outcomePath?: string): string {
     '__spex_cas_rc=0',
     'if [ "$__spex_rc" -ne 0 ]; then',
     '  __spex_outcome "reporting:$$:$__spex_rc" || true',
-    `  ${turnFailureShell(false)}`,
+    `  ${headlessTurnFailureShell('opencode-headless', false)}`,
     '  __spex_cas_rc=$?',
     'fi',
     '__spex_outcome "exit:$__spex_rc:cas:$__spex_cas_rc" || printf "[spex opencode-headless] could not finalize turn outcome marker\\n" >&2',
   ] : [
-    `if [ "$__spex_rc" -ne 0 ]; then ${turnFailureShell(true)}; fi`,
+    `if [ "$__spex_rc" -ne 0 ]; then ${headlessTurnFailureShell('opencode-headless')}; fi`,
   ]
   const script = [
     ...outcomeSetup,

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

@@ -1,10 +1,12 @@
-import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { createServer, type Server, type Socket } from 'node:net'
 import { spawn, type ChildProcess } from 'node:child_process'
 import { mkdirSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+import { controlRequest, withTimeout } from './headless-controller.js'
+import { shQuote } from './sh.js'
 
 type ControlRequest = { type: 'deliver'; text: string }
 type ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
@@ -14,8 +16,6 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 const CONTROL_TIMEOUT_MS = 30_000
 const START_TIMEOUT_MS = 30_000
 
-const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
-
 /** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
 export const piHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ph-${id}.sock`)
 
@@ -23,53 +23,11 @@ export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: s
   return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ')
 }
 
-function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(message)), ms)
-    promise.then(
-      (value) => { clearTimeout(timer); resolve(value) },
-      (error) => { clearTimeout(timer); reject(error) },
-    )
-  })
-}
-
-function controlRequest(id: string, request: ControlRequest): Promise<DispatchResult> {
-  return new Promise((resolve) => {
-    let socket: Socket | undefined
-    let settled = false
-    let buffer = ''
-    const finish = (result: DispatchResult) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      socket?.destroy()
-      resolve(result)
-    }
-    const timer = setTimeout(() => finish({ ok: false, error: `pi-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
-    try { socket = createConnection(piHeadlessSock(id)) } catch (error) {
-      finish({ ok: false, error: `pi-headless controller connect failed for session ${id}: ${(error as Error).message}` })
-      return
-    }
-    socket.setEncoding('utf8')
-    socket.on('connect', () => socket!.write(`${JSON.stringify(request)}\n`))
-    socket.on('data', (chunk) => {
-      buffer += chunk
-      const nl = buffer.indexOf('\n')
-      if (nl < 0) return
-      try {
-        const response = JSON.parse(buffer.slice(0, nl)) as DispatchResult
-        finish(response.ok ? { ok: true } : { ok: false, error: response.error || 'pi-headless controller rejected the request' })
-      } catch (error) {
-        finish({ ok: false, error: `pi-headless returned an invalid control response: ${(error as Error).message}` })
-      }
-    })
-    socket.on('error', (error) => finish({ ok: false, error: `pi-headless controller unreachable for session ${id}: ${error.message}` }))
-    socket.on('close', () => finish({ ok: false, error: `pi-headless controller closed before confirming session ${id}` }))
-  })
-}
-
 export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
-  controlRequest(rec.session, { type: 'deliver', text })
+  controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the request',
+  })
 
 export class PiHeadlessController {
   private server: Server | null = null
@@ -111,9 +69,10 @@ export class PiHeadlessController {
       if (!this.server) return resolve()
       this.server.close(() => resolve())
     })
-    try { rmSync(this.socketPath, { force: true }) } catch { /* best-effort cleanup after close */ }
-    const { rvSock } = await import('./harness.js')
-    try { rmSync(rvSock(this.id), { force: true }) } catch { /* pi may already have removed it */ }
+    // same proof-before-removal rule as every other teardown (harness.ts unlinkSocks): a socket path is keyed
+    // by session id alone, so only a listener PROVEN dead is ours to unlink.
+    const { rvSock, unlinkSocks } = await import('./harness.js')
+    await unlinkSocks(this.socketPath, rvSock(this.id))
   }
 
   private accept(socket: Socket): void {
@@ -144,14 +103,12 @@ export class PiHeadlessController {
 
     // A live extension listener is an in-flight pi turn. The native steer path is parse-confirmed by the
     // shared rendezvous protocol. Only a proven absent listener may cold-wake a saved session.
-    const { deliverViaRendezvous, rendezvousListening } = await import('./harness.js')
-    const listener = await rendezvousListening(this.id)
-    if (listener === 'live') return deliverViaRendezvous(this.id, request.text)
-    if (listener === 'unproven') return { ok: false, error: `could not determine whether pi turn ${this.id} is live — prompt NOT delivered` }
-
-    if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
-    await this.spawnTurn(request.text, true)
-    return { ok: true }
+    const { deliverViaSocketOrWake } = await import('./harness.js')
+    return deliverViaSocketOrWake(this.id, request.text, async () => {
+      if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
+      await this.spawnTurn(request.text, true)
+      return { ok: true }
+    }, `could not determine whether pi turn ${this.id} is live — prompt NOT delivered`)
   }
 
   private async spawnTurn(text: string, resume: boolean): Promise<void> {

package/spec-cli/src/process-identity.ts

@@ -0,0 +1,49 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { join } from 'node:path'
+
+export type ProcessIdentity = { pid: number; startToken: string }
+export type ProcessTopology = ProcessIdentity & { processGroupId: number; sessionId: number }
+
+export function parseProcStat(text: string): { ppid: number; processGroupId: number; sessionId: number; ticks: number; startToken: string; rssPages: number } {
+  const end = text.lastIndexOf(')')
+  if (end < 0) throw new Error('malformed proc stat')
+  const fields = text.slice(end + 2).trim().split(/\s+/)
+  if (fields.length < 22) throw new Error('short proc stat')
+  return {
+    ppid: Number(fields[1]),
+    processGroupId: Number(fields[2]),
+    sessionId: Number(fields[3]),
+    ticks: Number(fields[11]) + Number(fields[12]),
+    startToken: fields[19],
+    rssPages: Number(fields[21]),
+  }
+}
+
+export function processTopology(pid: number, procRoot = '/proc'): ProcessTopology | null {
+  if (platform() === 'linux' || procRoot !== '/proc') {
+    try {
+      const stat = parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8'))
+      return { pid, startToken: stat.startToken, processGroupId: stat.processGroupId, sessionId: stat.sessionId }
+    } catch { return null }
+  }
+  try {
+    const [processGroupId, sessionId] = execFileSync('ps', ['-o', 'pgid=', '-o', 'sess=', '-p', String(pid)], { encoding: 'utf8' }).trim().split(/\s+/).map(Number)
+    const startToken = processStartToken(pid, procRoot)
+    return startToken && Number.isFinite(processGroupId) && Number.isFinite(sessionId)
+      ? { pid, startToken, processGroupId, sessionId }
+      : null
+  } catch { return null }
+}
+
+export function processStartToken(pid: number, procRoot = '/proc'): string | null {
+  if (platform() === 'linux' || procRoot !== '/proc') {
+    try { return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken }
+    catch { return null }
+  }
+  try {
+    const started = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8' }).trim()
+    return started || null
+  } catch { return null }
+}

package/spec-cli/src/project-store.ts

@@ -0,0 +1,17 @@
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+// One pure identity seam for every project-scoped runtime consumer. Git discovery stays with callers;
+// once they have the shared common dir, sessions, materialize, history indexes, backends, and uninstall
+// all resolve the same top-level store.
+export function spexcodeHome(): string {
+  return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
+}
+
+export function encodeProject(root: string): string {
+  return root.replace(/[/.]/g, '-')
+}
+
+export function projectRuntimeRoot(commonDir: string): string {
+  return join(spexcodeHome(), 'projects', encodeProject(dirname(commonDir)))
+}

package/spec-cli/src/pty-bridge.ts

@@ -1,7 +1,8 @@
 import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
-import { alive } from './sessions.js'
+import { alive, withSessionInputLock } from './sessions.js'
+import { runSessionOperationSync } from './session-maintenance.js'
 
 const pexec = promisify(execFile)
 const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
@@ -362,8 +363,10 @@ const MAX_INPUT_BYTES = 64 * 1024
 export function forwardInput(id: string, viewer: Viewer, data: string): boolean {
   const subscription = currentSubscription(id, viewer)
   if (!subscription?.visible || !subscription.bridge || !data || Buffer.byteLength(data, 'utf8') > MAX_INPUT_BYTES) return false
-  sendControl(subscription.bridge, { t: 'input', data })
-  return true
+  return runSessionOperationSync({ op: 'terminal-input', sessionId: id }, () => withSessionInputLock(id, () => {
+      sendControl(subscription.bridge!, { t: 'input', data })
+      return true
+    }) ?? false)
 }
 
 async function restoreBridge(id: string, viewer: Viewer, subscription: Subscription): Promise<void> {

package/spec-cli/src/reviews.ts

@@ -15,6 +15,11 @@ import { EVAL_QUERY_DEFAULT, ISSUE_QUERY_DEFAULT, readToken } from '../../spec-d
 export const REVIEW_PER_PAGE = 25
 
 type ReviewItem = Record<string, unknown>
+// A section count is one number, or — when the domain adapter splits that section — its named buckets,
+// which re-add to the same whole population ([[review-filters]] owns the split; Evals splits its measured
+// verdicts into {fresh,stale} so the remeasurement debt travels with the count instead of being recomputed
+// per surface). The fold happens ONCE, here on the server, over the complete filtered population.
+export type ReviewCount = number | Record<string, number>
 type ReviewOption = { value: string; label?: string; count?: number }
 type ReviewFacet = { key: string; label?: string; value: string; meaningful?: boolean; options: ReviewOption[] }
 type EvalNeighbor = { node: string; scenario: string; state: string }
@@ -29,7 +34,7 @@ export type PagedReview<T extends ReviewItem = ReviewItem> = {
   prev: number | null
   next: number | null
   revision: string
-  counts: Record<string, number>
+  counts: Record<string, ReviewCount>
   facets: Record<string, ReviewFacet>
   section: { key: string; value: string; options: ReviewOption[] } | null
 }
@@ -129,12 +134,12 @@ export async function issuesReview(query: string | undefined, requestedPage: unk
   }
 }
 
-const byNewest = (a: any, b: any): number => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
+const byNewest = (a: any, b: any): number => Number(b.filterKind === EVAL_FILTER_KIND.RESULT) - Number(a.filterKind === EVAL_FILTER_KIND.RESULT)
+  || String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
   || String(a.node ?? '').localeCompare(String(b.node ?? ''))
   || String(a.scenario ?? '').localeCompare(String(b.scenario ?? ''))
 
 export function trunkEvalReviewItems(nodes: any[]): ReviewItem[] {
-  const blind: any[] = []
   const items: any[] = []
   for (const node of nodes ?? []) {
     const latest = new Map<string, any>()
@@ -142,7 +147,7 @@ export function trunkEvalReviewItems(nodes: any[]): ReviewItem[] {
     for (const scenario of node.scenarios ?? []) {
       const reading = latest.get(scenario.name)
       if (!reading) {
-        blind.push({
+        items.push({
           scenario: scenario.name,
           expected: scenario.expected,
           tags: scenario.tags,
@@ -163,21 +168,18 @@ export function trunkEvalReviewItems(nodes: any[]): ReviewItem[] {
       })
     }
   }
-  blind.sort((a, b) => String(a.node).localeCompare(String(b.node)) || String(a.scenario).localeCompare(String(b.scenario)))
-  return [...blind, ...items.sort(byNewest)]
+  return items.sort(byNewest)
 }
 
 export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
-  const blind: any[] = []
-  const own: any[] = []
-  const inherited: any[] = []
+  const items: any[] = []
   for (const node of model.nodes ?? []) {
     const latest = new Map<string, any>()
     for (const reading of node.evals ?? []) if (!latest.has(reading.scenario)) latest.set(reading.scenario, reading)
     for (const scenario of node.scenarios ?? []) {
       const reading = latest.get(scenario.name)
       if (!reading) {
-        blind.push({
+        items.push({
           scenario: scenario.name,
           expected: scenario.expected,
           tags: scenario.tags,
@@ -192,15 +194,16 @@ export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
         ...reading,
         expected: scenario.expected ?? reading.expected,
         tags: scenario.tags,
+        impact: scenario.impact,
         state: evalReviewState(reading),
         node: node.id,
         hue: node.hue,
         filterKind: EVAL_FILTER_KIND.RESULT,
       }
-      ;(reading.inSession ? own : inherited).push(item)
+      items.push(item)
     }
   }
-  return [...blind, ...own.sort(byNewest), ...inherited.sort(byNewest)]
+  return items.sort(byNewest)
 }
 
 const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
@@ -327,9 +330,10 @@ export async function evalsReview(query: string | undefined, requestedPage: unkn
       unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
       summary: model.summary,
       evalRevision: model.evalRevision,
+      impact: model.impact,
       ...paginateReview(items, filtered.shown, filtered, requestedPage, {
         domain: 'evals', scope, items, gates: model.gates, summary: model.summary,
-        evalRevision: model.evalRevision, sessions: sessions.map((session) => session.id),
+        evalRevision: model.evalRevision, impact: model.impact, sessions: sessions.map((session) => session.id),
       }),
     }
   }