spexcode 0.5.2 → 0.5.4

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,174 @@
+import { randomUUID } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export type ProcessIdentity = { pid: number; startToken: string }
+
+export type ProcessAdapter = Readonly<{
+  platform: NodeJS.Platform
+  startToken(pid: number): string | null
+  processGroupId(pid: number): number | null
+  linuxSessionId(pid: number): number | null
+}>
+
+export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
+  receiptVersion: 4
+  processGroupId: number
+  linuxSessionId?: number
+}>
+
+export type DetachedRuntimeVerification =
+  | { ok: true; identity: VerifiedDetachedRuntime }
+  | { ok: false; reason: string }
+
+type DetachedLaunchReceiptV4 = {
+  version: 4
+  kind: 'spexcode-detached-runtime'
+  pid: number
+  startToken: string
+  processGroupId: number
+  linuxSessionId?: 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 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 }
+}
+
+const procField = (pid: number, field: 'processGroupId' | 'sessionId'): number | null => {
+  try {
+    const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'))
+    return stat[field]
+  } catch { return null }
+}
+
+const psProcessGroupId = (pid: number): number | null => {
+  try {
+    const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
+    return Number.isInteger(value) && value > 0 ? value : null
+  } catch { return null }
+}
+
+export const hostProcessAdapter: ProcessAdapter = Object.freeze({
+  platform: platform(),
+  startToken: (pid) => processStartToken(pid),
+  processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
+  linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
+})
+
+const exactKeys = (value: Record<string, unknown>, expected: string[]) => {
+  const actual = Object.keys(value).sort()
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
+}
+
+const parseDetachedLaunchReceipt = (text: string, hostPlatform: NodeJS.Platform): DetachedLaunchReceiptV4 | null => {
+  let value: unknown
+  try { value = JSON.parse(text) } catch { return null }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const receipt = value as Record<string, unknown>
+  const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort()
+  if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
+    !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
+    !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
+    (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0))) return null
+  return receipt as DetachedLaunchReceiptV4
+}
+
+const observeDetachedRuntime = (pid: number, adapter: ProcessAdapter): DetachedRuntimeVerification => {
+  if (adapter.platform === 'win32') return { ok: false, reason: 'detached runtime identity is unsupported on win32' }
+  const startBefore = adapter.startToken(pid)
+  if (!startBefore) return { ok: false, reason: `PID ${pid} has no readable process-start identity` }
+  const processGroupId = adapter.processGroupId(pid)
+  if (processGroupId !== pid) return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` }
+  let linuxSessionId: number | undefined
+  if (adapter.platform === 'linux') {
+    const sessionId = adapter.linuxSessionId(pid)
+    if (sessionId !== pid) return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` }
+    linuxSessionId = sessionId
+  }
+  const startAfter = adapter.startToken(pid)
+  if (!startAfter || startAfter !== startBefore)
+    return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` }
+  return {
+    ok: true,
+    identity: Object.freeze({
+      pid,
+      startToken: startAfter,
+      receiptVersion: 4,
+      processGroupId,
+      ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
+    }),
+  }
+}
+
+export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): DetachedRuntimeVerification {
+  let text: string
+  try { text = readFileSync(receiptFile, 'utf8') }
+  catch { return { ok: false, reason: 'detached launch receipt is missing or unreadable' } }
+  const receipt = parseDetachedLaunchReceipt(text, adapter.platform)
+  if (!receipt) return { ok: false, reason: 'detached launch receipt has the wrong version or shape' }
+  if (receipt.pid !== pid) return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` }
+  if (receipt.processGroupId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` }
+  if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` }
+  const live = observeDetachedRuntime(pid, adapter)
+  if (!live.ok) return live
+  if (live.identity.startToken !== receipt.startToken)
+    return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` }
+  return live
+}
+
+export function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): VerifiedDetachedRuntime {
+  const observed = observeDetachedRuntime(pid, adapter)
+  if (!observed.ok) throw new Error(`cannot prove detached shared runtime: ${observed.reason}`)
+  const receipt: DetachedLaunchReceiptV4 = {
+    version: 4,
+    kind: 'spexcode-detached-runtime',
+    pid,
+    startToken: observed.identity.startToken,
+    processGroupId: observed.identity.processGroupId,
+    ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
+  }
+  mkdirSync(dirname(receiptFile), { recursive: true })
+  const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`
+  let published = false
+  try {
+    writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 })
+    renameSync(tmp, receiptFile)
+    published = true
+    const verified = verifyDetachedRuntime(pid, receiptFile, adapter)
+    if (!verified.ok) throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`)
+    return verified.identity
+  } catch (error) {
+    rmSync(tmp, { force: true })
+    if (published) rmSync(receiptFile, { force: true })
+    throw error
+  }
+}
+
+export const detachedRuntimeGenerationToken = (identity: VerifiedDetachedRuntime) =>
+  `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`

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