spexcode 0.5.7 → 0.5.9

package/spec-cli/src/client.ts

@@ -1,20 +1,21 @@
-import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
-import { readSync, writeSync } from 'node:fs'
-import { maintenanceBrokerDescriptors, type Capability, type LeaseOwner, type MaintenanceState } from './session-maintenance.js'
-import { processStartToken } from './process-identity.js'
+import { existsSync } from 'node:fs'
+import { platform } from 'node:os'
+import { repoRoot } from './git.js'
+import { resourceBudgets, type ResourceReport } from './host-resources.js'
+import { listSessionIds, readPublicRecordEntry } from './layout.js'
+import { cockpitReview, type CockpitReview } from './cockpit.js'
+import { apiBase, apiBaseInfo, assertProjectMatch, fromRaw, resolveSession, toSession, type DisplayStatus, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
     super(message)
-    this.name = 'BackendError'   // sessions.ts's isBackendDown matches on this name (no runtime import cycle)
+    this.name = 'BackendError'   // cli.ts's top-level handler matches on the NAME, so it needs no import of this class
   }
 }
 
 // the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
 // is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
 async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
-  if (maintenanceBrokerDescriptors() && init?.method && !['GET', 'HEAD'].includes(init.method.toUpperCase()))
-    throw new BackendError('maintenance_capability_missing: the operator broker admits only its exact stop/resume plan')
   const base = await apiBase()
   try {
     return await fetch(`${base}${path}`, init)
@@ -28,122 +29,108 @@ async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
 const guarded = (verb: string) => assertProjectMatch(`spex ${verb}`)
 const post = (body: unknown): RequestInit => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
 const seg = (id: string) => encodeURIComponent(id)
-type BrokerRequest = { op: string; sessionId?: string; force?: boolean }
-type BrokerOutcome = 'committed' | 'refused' | 'indeterminate'
-type BrokerResponse = { ok: boolean; outcome?: BrokerOutcome; status?: number; body?: any; code?: string; error?: string }
-function brokerRequest(request: BrokerRequest): BrokerResponse | null {
-  const fds = maintenanceBrokerDescriptors()
-  if (!fds) return null
-  const startToken = processStartToken(process.pid)
-  if (!startToken) throw new BackendError(`maintenance broker cannot identify client PID ${process.pid}`)
-  const id = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
-  const frame = `${JSON.stringify({ v: 1, id, ...request, client: { pid: process.pid, startToken } })}\n`
-  if (Buffer.byteLength(frame) > 4_096) throw new BackendError('maintenance broker request exceeded PIPE_BUF')
-  const token = Buffer.alloc(1)
-  let ownsTurn = false
-  try {
-    if (readSync(fds.turn, token, 0, 1, null) !== 1 || token[0] !== 1)
-      throw new BackendError('maintenance broker turn token was unavailable or invalid')
-    ownsTurn = true
-    if (writeSync(fds.request, frame) !== Buffer.byteLength(frame)) throw new BackendError('maintenance broker request write was incomplete')
-    let line = ''
-    const byte = Buffer.alloc(1)
-    while (!line.endsWith('\n')) {
-      const count = readSync(fds.response, byte, 0, 1, null)
-      if (count === 0) throw new BackendError('maintenance broker closed before replying')
-      line += byte.toString('utf8', 0, count)
-      if (line.length > 64 * 1024) throw new BackendError('maintenance broker response exceeded its bound')
-    }
-    const response = JSON.parse(line) as BrokerResponse & { id?: string }
-    if (response.id !== id) throw new BackendError('maintenance broker response identity mismatch')
-    return response
-  } finally {
-    if (ownsTurn) {
-      try { writeSync(fds.turn, token) } catch { /* broker shutdown owns the failure */ }
-    }
-  }
-}
-const brokerMutation = (request: BrokerRequest): BrokerResponse | null => brokerRequest(request)
 
-export type MaintenanceLeaseResponse = { token: string; epoch: number; state: 'draining' | 'active'; owner: LeaseOwner; capabilities?: Capability[] }
-export async function clientMaintenanceAcquire(capabilities: Capability[], ttlMs: number, waitMs: number): Promise<{ status: number; lease: MaintenanceLeaseResponse }> {
-  await guarded('session maintain')
-  const r = await apiFetch('/api/session-maintenance/acquire', post({ capabilities, ttlMs, waitMs }))
-  const lease = await r.json().catch(() => ({})) as MaintenanceLeaseResponse & { error?: string }
-  if (r.status !== 201 && r.status !== 202) throw new BackendError(`backend refused maintenance acquire (${r.status}): ${lease.error || 'invalid response'}`, r.status)
-  return { status: r.status, lease }
+// A rendezvous liveness probe can displace the real delivery client.
+function cachedStatus(rec: ReturnType<typeof fromRaw>): DisplayStatus {
+  if (!rec.worktreePath || !existsSync(rec.worktreePath)) return 'retired'
+  if (rec.archived) return 'offline'
+  if (rec.status === 'awaiting') return rec.proposal === 'merge' ? 'review' : rec.proposal === 'close' ? 'close-pending' : 'done'
+  return rec.status === 'active' || rec.status === 'idle' ? 'unknown' : rec.status
 }
-export async function clientMaintenanceStatus(): Promise<MaintenanceState> {
-  const r = await apiFetch('/api/session-maintenance')
-  if (!r.ok) throw new BackendError(`backend refused maintenance status (${r.status})`, r.status)
-  return await r.json() as MaintenanceState
+
+function corruptCachedSession(id: string, reason: string): Session {
+  const label = `${id.slice(0, 8)} (unreadable record)`
+  return {
+    id, node: null, branch: null, path: '', label, headline: label, raw: { name: null, title: null },
+    parent: null, harness: 'unknown', capabilities: { headless: false }, launcher: null,
+    lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
+    note: `session record is unreadable: ${reason}`, archived: false, archiveHazard: null,
+    prompt: null, promptPreview: null, created: 0, activity: null, sortKey: null,
+  }
 }
-const maintenanceHeaders = (token: string): Record<string, string> => ({
-  'content-type': 'application/json',
-  'x-spexcode-session-maintenance': token,
-})
-export async function clientMaintenanceHeartbeat(token: string, epoch: number, ttlMs: number): Promise<MaintenanceState> {
-  const r = await apiFetch('/api/session-maintenance/heartbeat', { method: 'POST', headers: maintenanceHeaders(token), body: JSON.stringify({ epoch, ttlMs }) })
-  if (!r.ok) throw new BackendError(`backend refused maintenance heartbeat (${r.status}): ${await r.text()}`, r.status)
-  return await r.json() as MaintenanceState
+
+// Also the board a FOLLOW resolves its selectors against ([[session-follow]]): following must work with no
+// `spex serve` running, and asking a backend for the board would cost exactly the tmux/rendezvous probes the
+// follow exists to eliminate. Every field here comes from the store — nothing is probed.
+export function localCachedSessions(includeArchived = false): Session[] {
+  const rows: Session[] = []
+  for (const id of listSessionIds()) {
+    const entry = readPublicRecordEntry(id)
+    if (entry.kind === 'corrupt') {
+      rows.push(corruptCachedSession(id, entry.error))
+      continue
+    }
+    if (entry.kind !== 'ok') continue
+    const rec = fromRaw(entry.raw)
+    if (!rec.governed) continue
+    rows.push(toSession(rec, cachedStatus(rec), 'unknown'))
+  }
+  return rows.filter((session) => includeArchived || !session.archived)
+    .sort((a, b) => (a.sortKey ?? a.created) - (b.sortKey ?? b.created) || a.id.localeCompare(b.id))
 }
-export async function clientMaintenanceRelease(token: string, epoch: number): Promise<void> {
-  const r = await apiFetch('/api/session-maintenance/release', { method: 'POST', headers: maintenanceHeaders(token), body: JSON.stringify({ epoch }) })
-  if (!r.ok) throw new BackendError(`backend refused maintenance release (${r.status}): ${await r.text()}`, r.status)
+
+function localCachedResources(): ResourceReport {
+  const projectRoot = repoRoot()
+  const budgets = resourceBudgets(projectRoot)
+  const owners = localCachedSessions(true).map((session) => ({
+    kind: 'session' as const,
+    id: session.id,
+    label: session.label,
+    status: session.lifecycle,
+    liveness: 'unknown' as const,
+    proposal: session.proposal,
+    note: session.note,
+    worktreePath: session.path,
+    branch: session.branch,
+    archived: session.archived,
+    processes: [],
+    rssMiB: 0,
+    pssMiB: null,
+    cpuPercent: 0,
+    budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
+    findings: ['local-store-only: runtime liveness and process measurements are unavailable'],
+    reclaim: { eligible: false, reason: 'local store read cannot prove runtime ownership or liveness' },
+  }))
+  return {
+    version: 1,
+    measuredAt: new Date().toISOString(),
+    projectRoot,
+    platform: platform(),
+    available: false,
+    unavailableReason: 'backend unavailable; local session store has no runtime resource measurements',
+    host: { memoryTotalMiB: null, memoryUsedMiB: null, memoryAvailableMiB: null, swapTotalMiB: null, swapUsedMiB: null, cpuPercent: null },
+    budgets,
+    owners,
+    totals: { rssMiB: 0, pssMiB: null, cpuPercent: 0 },
+    findings: owners.reduce((total, owner) => total + owner.findings.length, 0),
+  }
 }
-export async function clientMaintenanceOperation(
-  token: string,
-  request: { op: 'stop' | 'resume'; sessionId: string; force?: boolean },
-  options: { signal?: AbortSignal; timeoutMs?: number } = {},
-): Promise<BrokerResponse> {
-  const path = `/api/sessions/${seg(request.sessionId)}/${request.op}`
-  const controller = new AbortController()
-  const abort = () => controller.abort(options.signal?.reason)
-  if (options.signal?.aborted) abort()
-  else options.signal?.addEventListener('abort', abort, { once: true })
-  const timer = setTimeout(() => controller.abort(new Error('maintenance operation timed out')), options.timeoutMs ?? 5_000)
-  timer.unref()
+
+async function cachedRead<T>(remote: () => Promise<T>, local: () => T | Promise<T>): Promise<T> {
   try {
-    const r = await apiFetch(path, {
-      method: 'POST', headers: maintenanceHeaders(token), signal: controller.signal,
-      body: JSON.stringify(request.op === 'resume' ? { force: request.force === true } : {}),
-    })
-    let body: any
-    try { body = await r.json() } catch {
-      return { ok: false, outcome: 'indeterminate', status: r.status, code: 'maintenance_response_malformed', error: 'maintenance operation returned malformed JSON' }
-    }
-    const committed = r.ok && body?.ok === true
-    const refused = (r.status >= 400 && r.status < 500 && (body?.ok === false || typeof body?.code === 'string'))
-      || (r.ok && body?.ok === false && body?.refused === true)
-    const outcome: BrokerOutcome = committed ? 'committed' : refused ? 'refused' : 'indeterminate'
-    const code = typeof body?.code === 'string' ? body.code
-      : refused ? 'session_operation_refused'
-        : committed ? undefined : 'maintenance_operation_indeterminate'
-    return {
-      ok: committed,
-      outcome,
-      status: r.status,
-      body,
-      ...(code ? { code } : {}),
-      ...(!committed ? { error: body?.error || `status ${r.status}` } : {}),
-    }
-  } finally {
-    clearTimeout(timer)
-    options.signal?.removeEventListener('abort', abort)
+    return await remote()
+  } catch (error) {
+    if (!(error instanceof BackendError) || error.status !== undefined || (await apiBaseInfo()).source === 'flag') throw error
+    console.error('spex session: backend unreachable; source: local session store (liveness unknown)')
+    return await local()
   }
 }
 
 // GET /api/sessions — the board, used by `spex session ls`, and by `spex session watch`/`wait` as their poll source.
 export async function clientListSessions(includeArchived = false): Promise<Session[]> {
-  const r = await apiFetch(includeArchived ? '/api/sessions?all=1' : '/api/sessions')
-  if (!r.ok) throw new BackendError(`backend error ${r.status} listing sessions`, r.status)
-  return await r.json() as Session[]
+  return cachedRead(async () => {
+    const r = await apiFetch(includeArchived ? '/api/sessions?all=1' : '/api/sessions')
+    if (!r.ok) throw new BackendError(`backend error ${r.status} listing sessions`, r.status)
+    return await r.json() as Session[]
+  }, () => localCachedSessions(includeArchived))
 }
 
 export async function clientResources(): Promise<import('./host-resources.js').ResourceReport> {
-  const r = await apiFetch('/api/resources')
-  if (!r.ok) throw new BackendError(`backend error ${r.status} loading resources: ${await r.text()}`, r.status)
-  return await r.json() as import('./host-resources.js').ResourceReport
+  return cachedRead(async () => {
+    const r = await apiFetch('/api/resources')
+    if (!r.ok) throw new BackendError(`backend error ${r.status} loading resources: ${await r.text()}`, r.status)
+    return await r.json() as import('./host-resources.js').ResourceReport
+  }, localCachedResources)
 }
 
 // resolve a selector (full id, id-prefix, node, or branch) against the live board, then call with the full id.
@@ -160,24 +147,24 @@ export async function clientCapture(id: string): Promise<CaptureResult> {
   return { ok: false, status: r.status, reason: (await r.text().catch(() => '')) || `status ${r.status}` }
 }
 
-// POST /api/sessions/:id/input {kind:"text"} — prompt dispatch (the backend routes it through the rendezvous
-// socket, socket-only + fail-loud; a non-accepted prompt comes back ok:false / HTTP 502).
+// POST /api/sessions/:id/input {kind:"text"} appends the prompt to the durable timeline, then best-effort
+// pokes the resolved adapter. HTTP failure means the append itself was refused.
 export async function clientSend(id: string, text: string, from?: string): Promise<DispatchResult> {
   await guarded('session send')
-  const brokered = brokerMutation({ op: 'send', sessionId: id })
-  if (brokered) return brokered.ok ? brokered.body as DispatchResult : { ok: false, error: brokered.code || brokered.error || 'maintenance_active' }
-  // `from` = the sending agent's own session id; the backend logs the comms edge ([[comms-edge]]) only when
+  // `from` = the sending agent's own session id; the recipient's log records the sender ([[session-timeline]]) only when
   // it's present (an agent send), so a human-shell send stays unrecorded.
   const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'text', text, ...(from ? { from } : {}) }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` })) as DispatchResult
 }
 
 // GET /api/sessions/:id/review — the manager cockpit review bundle (null on 404).
-export async function clientReview(id: string): Promise<ReviewPayload | null> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}/review`)
-  if (r.status === 404) return null
-  if (!r.ok) throw new BackendError(`backend error ${r.status} reviewing ${id}`, r.status)
-  return await r.json() as ReviewPayload
+export async function clientReview(id: string): Promise<CockpitReview | null> {
+  return cachedRead(async () => {
+    const r = await apiFetch(`/api/sessions/${seg(id)}/review`)
+    if (r.status === 404) return null
+    if (!r.ok) throw new BackendError(`backend error ${r.status} reviewing ${id}`, r.status)
+    return await r.json() as CockpitReview
+  }, () => cockpitReview(id))
 }
 
 // GET /api/sessions/:id/evals?format=html — the rendered EXPORT artifact ([[session-eval]]): the
@@ -237,11 +224,6 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 // carries a non-error advisory.
 export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean; info?: string }> {
   await guarded('session resume')
-  const brokered = brokerMutation({ op: 'resume', sessionId: id, force })
-  if (brokered) {
-    if (!brokered.ok) throw new BackendError(brokered.code || brokered.error || 'maintenance_active', brokered.status)
-    return brokered.body
-  }
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))
 }
@@ -250,11 +232,6 @@ export async function clientResume(id: string, force = false): Promise<{ ok: boo
 // resumable). Distinct from close. {ok:false} = no such session.
 export async function clientStop(id: string): Promise<boolean> {
   await guarded('session stop')
-  const brokered = brokerMutation({ op: 'stop', sessionId: id })
-  if (brokered) {
-    if (!brokered.ok) throw new BackendError(brokered.code || brokered.error || 'maintenance_active', brokered.status)
-    return !!brokered.body?.ok
-  }
   const r = await apiFetch(`/api/sessions/${seg(id)}/stop`, post({}))
   if (!r.ok) throw new BackendError(`backend refused to stop ${id}: ${await r.text()}`, r.status)
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
@@ -327,7 +304,12 @@ export async function clientSendRawKeys(id: string, keys: string[]): Promise<boo
 // originating prompt. 404 → no such session.
 export type ShowResult = { ok: true; session: Session & { prompt: string | null } } | { ok: false; status: number }
 export async function clientShow(id: string): Promise<ShowResult> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}`)
-  if (r.ok) return { ok: true, session: await r.json() as Session & { prompt: string | null } }
-  return { ok: false, status: r.status }
+  return cachedRead(async () => {
+    const r = await apiFetch(`/api/sessions/${seg(id)}`)
+    if (r.ok) return { ok: true, session: await r.json() as Session & { prompt: string | null } }
+    return { ok: false, status: r.status }
+  }, () => {
+    const session = localCachedSessions(true).find((item) => item.id === id)
+    return session ? { ok: true, session } : { ok: false, status: 404 }
+  })
 }

package/spec-cli/src/cockpit.ts

@@ -0,0 +1,43 @@
+import { reviewPayload, type ReviewEvalGate, type ReviewPayload } from './sessions.js'
+import { sessionEvalProjection } from '../../spec-eval/src/sessioneval.js'
+
+// @@@ cockpit - where the manager's review answer is ASSEMBLED ([[manager-cockpit]]). It sits above both the
+// session layer and the eval layer and may import either; that is what makes it the only honest home for a
+// value composed from both. `sessions.ts` cannot be that home — the eval package imports it, so reaching the
+// other way from there is a cycle, and the cycle used to be paid for with a deferred `await import()` whose
+// comment explained why it had to be wrong. `reviews.ts` cannot be it either: that file is [[paged-review]]'s
+// Issues/Evals paging server, and parking a session-cockpit concern under a node about paging would make that
+// node's body false. It imports the eval package for its own reasons — the same direction, a different one.
+
+// @@@ ONE composition, every entry point - `gates.evals` has exactly one producer, and it is this function.
+// The cockpit review is reachable two ways: the HTTP route, and `clientReview`'s local answer when no backend
+// resolves. If each composed its own gates, the same verb would report different shapes depending on whether a
+// backend happened to be running — the very asymmetry the remote-client role split exists to remove — and a
+// drift between the two readouts would be caught by no gate we have. So both call HERE.
+export type CockpitReview = Omit<ReviewPayload, 'gates'> & {
+  gates: ReviewPayload['gates'] & { evals: ReviewEvalGate }
+}
+
+// @@@ evalGate - the measured-loss readout, taken from [[session-eval]]'s EXISTING projection. This is a cache
+// READ and must stay one: `buildSessionEvals()` calls `reviewPayload()` itself, so BUILDING the model from here
+// would recurse. That hazard used to be held off by a comment; now it is structural — `reviewPayload` no longer
+// carries this field, so the eval side cannot re-enter through it. (It never read the field anyway: `gateRows`
+// consumes lint/conflict/ahead/dirty only. The payload was carrying a value for a caller that ignored it.)
+async function evalGate(id: string): Promise<ReviewEvalGate> {
+  const projection = sessionEvalProjection(id)
+  if (!projection) return { phase: 'unavailable' }
+  // only a `ready` projection carries a CURRENT value; last-known is deliberately not reported as current.
+  if (projection.phase !== 'ready' || !projection.value) {
+    return { phase: projection.phase === 'ready' ? 'unavailable' : projection.phase }
+  }
+  const summary = projection.value
+  return { phase: 'ready', freshPass: summary.pass, freshFail: summary.fail, needReview: summary.review, blind: summary.blind }
+}
+
+// the cockpit's whole answer for one session: the session-side review plus the eval readout, composed once.
+// The two run in parallel — the eval half is a projection read, independent of every git read in the payload.
+export async function cockpitReview(id: string): Promise<CockpitReview | null> {
+  const [payload, evals] = await Promise.all([reviewPayload(id), evalGate(id)])
+  if (!payload) return null
+  return { ...payload, gates: { ...payload.gates, evals } }
+}