spexcode 0.5.1 → 0.5.3

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'
@@ -20,6 +21,7 @@ type Subscription = {
   bridge?: Bridge
   lingerTimer?: ReturnType<typeof setTimeout>
   restoreTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 type Bridge = {
@@ -37,6 +39,7 @@ type Bridge = {
   refreshRunning: boolean
   refreshOffset?: number
   deliveryTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 const subscribers = new Map<string, Map<Viewer, Subscription>>()
@@ -103,6 +106,8 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
     const ready = line.match(/^READY (\d+)$/)
     if (ready) {
       bridge.ptyPid = Number(ready[1])
+      const subscription = currentSubscription(bridge.id, bridge.viewer)
+      if (subscription) subscription.startupError = undefined
       if (bridge.delivery === 'initial') {
         armDeliveryBoundary(bridge)
         queueRefresh(bridge)
@@ -117,11 +122,28 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
         queueRefresh(bridge)
       }
     } else if (line) {
+      const failed = line.match(/^ERROR (.+)$/)
+      if (failed) reportStartupError(bridge, failed[1])
       console.error(`[terminal helper ${bridge.id}/${bridge.ptyPid ?? 'starting'}] ${line}`)
     }
   }
 }
 
+function reportStartupError(bridge: Bridge, detail: string): void {
+  const subscription = currentSubscription(bridge.id, bridge.viewer)
+  if (!subscription || subscription.bridge !== bridge) return
+  const message = boundedStartupError(detail)
+  bridge.startupError = message
+  if (!message || subscription.startupError === message) return
+  subscription.startupError = message
+  deliver(bridge, Buffer.from(`\r\n[SpexCode terminal unavailable] ${message}\r\n`, 'utf8'))
+}
+
+function boundedStartupError(detail: unknown): string {
+  return (detail instanceof Error ? detail.message : String(detail))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500) || 'native PTY failed to start'
+}
+
 function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, cols: number, rows: number): { bridge: Bridge | null; created: boolean } {
   if (subscription.bridge) return { bridge: subscription.bridge, created: false }
   let proc: ChildProcessWithoutNullStreams | undefined
@@ -130,8 +152,13 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
       stdio: ['pipe', 'pipe', 'pipe'],
       env: process.env,
     })
-  } catch {
+  } catch (error) {
     try { proc?.kill() } catch { /* spawn did not complete */ }
+    const detail = boundedStartupError(error)
+    if (subscription.startupError !== detail) {
+      subscription.startupError = detail
+      try { viewer.send(Buffer.from(`\r\n[SpexCode terminal unavailable] ${detail}\r\n`, 'utf8')) } catch { /* socket closed */ }
+    }
     return { bridge: null, created: false }
   }
   const bridge: Bridge = {
@@ -142,18 +169,19 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
   proc.stdout.on('data', (data: Buffer) => onHelperOutput(bridge, data))
   proc.stderr.on('data', (data: Buffer) => onHelperStderr(bridge, data))
   let reaped = false
-  const gone = () => {
+  const gone = (detail?: string) => {
     if (reaped) return
     reaped = true
     const current = currentSubscription(id, viewer)
     if (current?.bridge !== bridge) return
+    if (!bridge.ptyPid && !bridge.startupError) reportStartupError(bridge, detail || 'helper exited before native PTY startup')
     current.bridge = undefined
     clearDelivery(bridge)
     try { bridge.proc.kill() } catch { /* already gone */ }
     scheduleRestore(id, viewer, current)
   }
-  proc.on('exit', gone)
-  proc.on('error', gone)
+  proc.on('exit', (code, signal) => gone(`helper exited before native PTY startup (${signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`})`))
+  proc.on('error', (error) => gone(`helper process failed: ${error.message}`))
   return { bridge, created: true }
 }
 
@@ -335,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/pty-helper.mjs

@@ -1,5 +1,6 @@
 import * as pty from 'node-pty'
 import { execFileSync } from 'node:child_process'
+import { ensureExecutableIfPresent, nodePtySpawnHelperPath } from './pty-native-helper.mjs'
 
 const [id, colsArg, rowsArg] = process.argv.slice(2)
 const cols = Number(colsArg)
@@ -40,12 +41,21 @@ try {
   }
 } catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
 
-const terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
-  name: 'xterm-256color',
-  cols,
-  rows,
-  env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
-})
+let terminal
+try {
+  ensureExecutableIfPresent(nodePtySpawnHelperPath(pty.native))
+  terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+    name: 'xterm-256color',
+    cols,
+    rows,
+    env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+  })
+} catch (error) {
+  const detail = (error instanceof Error ? error.message : String(error))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500)
+  process.stderr.write(`ERROR ${detail || 'native PTY failed to start'}\n`)
+  process.exit(1)
+}
 
 terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')))
 terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1))

package/spec-cli/src/pty-native-helper.mjs

@@ -0,0 +1,22 @@
+import { chmodSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+export function nodePtySpawnHelperPath(nativeModule) {
+  const nativeAddon = Object.values(require.cache).find((loaded) => loaded?.exports === nativeModule)?.filename
+  if (!nativeAddon) throw new Error('cannot locate node-pty loaded native addon')
+  return join(dirname(nativeAddon), 'spawn-helper')
+}
+
+export function ensureExecutableIfPresent(path) {
+  let mode
+  try {
+    mode = statSync(path).mode & 0o777
+  } catch (error) {
+    if (error?.code === 'ENOENT') return
+    throw error
+  }
+  if ((mode & 0o111) !== 0o111) chmodSync(path, mode | 0o111)
+}

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),
       }),
     }
   }

package/spec-cli/src/runtime-ownership.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { repoRoot } from './git.js'
+import { readJsonConfig, runtimeRoot } from './layout.js'
+import { processStartToken, processTopology, type ProcessIdentity } from './process-identity.js'
+
+export type BackendInstanceRecord = {
+  version: 1
+  instanceId: string
+  pid: number
+  startToken: string
+  projectRoot: string
+  startedAt: string
+}
+
+const backendInstancesDir = () => join(runtimeRoot(), 'backend-instances')
+const backendInstancePath = (instanceId: string) => join(backendInstancesDir(), `${instanceId}.json`)
+
+const atomicJson = (path: string, value: unknown) => {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+  renameSync(tmp, path)
+}
+
+export function readBackendInstanceRecords(root = repoRoot()): BackendInstanceRecord[] {
+  let names: string[]
+  try { names = readdirSync(backendInstancesDir()) } catch { return [] }
+  return names.flatMap((name) => {
+    try {
+      const rec = readJsonConfig(join(backendInstancesDir(), name)) as BackendInstanceRecord
+      return rec?.version === 1 && rec.projectRoot === root ? [rec] : []
+    } catch { return [] }
+  })
+}
+
+export function registerBackendInstance(instanceId: string, pid = process.pid, root = repoRoot()): BackendInstanceRecord {
+  const startToken = processStartToken(pid)
+  if (!startToken) throw new Error(`cannot identify backend supervisor PID ${pid}`)
+  const record: BackendInstanceRecord = { version: 1, instanceId, pid, startToken, projectRoot: root, startedAt: new Date().toISOString() }
+  atomicJson(backendInstancePath(instanceId), record)
+  return record
+}
+
+export function unregisterBackendInstance(instanceId: string, pid = process.pid): void {
+  try {
+    const record = readJsonConfig(backendInstancePath(instanceId)) as BackendInstanceRecord
+    if (record.instanceId === instanceId && record.pid === pid && record.startToken === processStartToken(pid)) rmSync(backendInstancePath(instanceId), { force: true })
+  } catch { /* not ours / already removed */ }
+}
+
+export function writeIsolationStamp(pid: number, file: string): void {
+  const topology = processTopology(pid)
+  if (!topology) throw new Error(`cannot identify shared runtime PID ${pid}`)
+  if (topology.processGroupId !== pid || topology.sessionId !== pid)
+    throw new Error(`shared runtime PID ${pid} is not detached from its launch session (pgrp=${topology.processGroupId}, session=${topology.sessionId})`)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `detached-v3 ${pid} ${topology.startToken} ${topology.processGroupId} ${topology.sessionId}\n`, { mode: 0o600 })
+}
+
+export function spawnDetachedRuntime(opts: {
+  cwd: string
+  logFile: string
+  pidFile: string
+  isolationFile: string
+  command: string
+  args: string[]
+  env?: NodeJS.ProcessEnv
+}): ProcessIdentity {
+  mkdirSync(dirname(opts.logFile), { recursive: true })
+  mkdirSync(dirname(opts.pidFile), { recursive: true })
+  const log = openSync(opts.logFile, 'a', 0o600)
+  let child: ReturnType<typeof spawn>
+  try {
+    child = spawn(opts.command, opts.args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      detached: true,
+      stdio: ['ignore', log, log],
+    })
+  } finally { closeSync(log) }
+  child.once('error', () => {})
+  if (!child.pid) throw new Error(`could not spawn detached shared runtime: ${opts.command}`)
+  child.unref()
+  try {
+    writeIsolationStamp(child.pid, opts.isolationFile)
+    const startToken = processStartToken(child.pid)
+    if (!startToken) throw new Error(`cannot identify detached shared runtime PID ${child.pid}`)
+    writeFileSync(opts.pidFile, `${child.pid}\n`, { mode: 0o600 })
+    return { pid: child.pid, startToken }
+  } catch (error) {
+    try { child.kill('SIGTERM') } catch { /* exact just-spawned child already exited */ }
+    rmSync(opts.pidFile, { force: true })
+    rmSync(opts.isolationFile, { force: true })
+    throw error
+  }
+}