spexcode 0.5.8 → 0.5.9

package/spec-cli/src/mentions.ts

@@ -1,225 +1,81 @@
-// @@@ mentions - the two universal in-text reference primitives ([[mentions]]): `[[node]]` (a TOPIC — a spec
-// node) and `@session` (an ACTOR — a live session, or `@new` for a fresh worker). The same parser resolves
-// them in ANY input box; the resolve+dispatch live HERE (CLI-first) so the issues page, the composer, and an agent's
-// own prompt share one implementation. An `@` "just auto-sends a prompt": resolve it against the live board
-// sessions and dispatch via [[dispatch]]'s sendText / [[launch]]'s bounded create owner — storage and delivery stay
-// separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
-
-// ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
-// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Token chars are any unicode
-// letter/number plus [_-] (a CJK session handle or node id is first-class — same charset the launch-side
-// MENTION and the dashboard's MENTION_RE use); a session id, a short label/prefix, or the literal `new`.
-// Only `new` may carry `:<launcher>` ([[launcher-select]]); keeping that choice in the token makes the same
-// prose work from the CLI and dashboard, with no composer-only field. Both forms are deduped first-seen.
-const ACTOR_RE = /(?:^|\s)@([\p{L}\p{N}_-]+)(?::([\p{L}\p{N}_.-]+))?/gu
+// @@@ mentions - the two passive in-text references: `[[node]]` names a topic and
+// `@session` names a retained session. The grammar is shared by every composer; neither
+// reference is control. Sending to a session, launching one, and inheriting one remain
+// explicit `spex session send`, `spex session new`, and `/distill <id>` actions.
+const SESSION_RE = /(?:^|\s)@([\p{L}\p{N}_-]+(?::[\p{L}\p{N}_.-]+)?)/gu
 const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 const uniq = (xs: string[]): string[] => [...new Set(xs)]
 
-// ── CLI sigil tolerance ───────────────────────────────────────────────────────────────────────────────
-// In FREE TEXT the sigils are required — they are what marks a reference apart from prose. In a CLI
-// ARGUMENT the whole token IS the reference, so the sigil is optional: `spex session review @graph` ≡
-// `spex session review graph`, `spex eval add [[cli-surface]]` ≡ `spex eval add cli-surface`. One shared strip,
-// applied by the session-selector matcher and every node-arg read site, so the habit a user learns in the
-// dashboard's input boxes works verbatim on the CLI — never a second grammar to learn.
+// In free text a sigil separates a reference from prose. A CLI argument is already a
+// reference, so it tolerates either sigil without widening its normal matching grammar.
 export function stripRefSigil(token: string): string {
   const wrapped = /^\[\[(.*)\]\]$/.exec(token)
   if (wrapped) return wrapped[1]
   return token.startsWith('@') ? token.slice(1) : token
 }
 
-export function parseMentions(text: string): { actors: string[]; nodes: string[] } {
-  const actors: string[] = []
+export function parseMentions(text: string): { sessions: string[]; nodes: string[] } {
+  const sessions: string[] = []
   const nodes: string[] = []
-  for (const m of text.matchAll(ACTOR_RE)) actors.push(m[1] === 'new' && m[2] ? `new:${m[2]}` : m[1])
+  for (const m of text.matchAll(SESSION_RE)) sessions.push(m[1])
   for (const m of text.matchAll(NODE_RE)) nodes.push(m[1])
-  return { actors: uniq(actors), nodes: uniq(nodes) }
-}
-
-// ── resolve actors against live sessions (pure) ───────────────────────────────────────────────────────
-// A minimal shape of what dispatchMentions needs from a Session (so this stays testable without sessions.ts).
-export type ActorSession = { id: string; node: string | null; name: string | null; title: string | null; liveness: string }
-export type Resolved =
-  | { token: string; kind: 'new'; launcher?: string }
-  | { token: string; kind: 'session'; session: ActorSession }
-  | { token: string; kind: 'unresolved' }
-
-// Resolve each actor token to a `new` sentinel (optionally carrying its explicit launcher), an ONLINE
-// session (never a dead one — you don't summon a closed agent; `@new` acts on its behalf), or unresolved.
-// Match order: new/new:<launcher> → exact id → id prefix → name/title (case-insensitive) → name/title prefix.
-// First online match wins.
-export function resolveActors(tokens: string[], sessions: ActorSession[]): Resolved[] {
-  const online = sessions.filter((s) => s.liveness === 'online')
-  return tokens.map((token): Resolved => {
-    const fresh = /^new(?::(.+))?$/.exec(token)
-    if (fresh) return { token, kind: 'new', ...(fresh[1] ? { launcher: fresh[1] } : {}) }
-    const t = token.toLowerCase()
-    const label = (s: ActorSession) => (s.name || s.title || '').toLowerCase()
-    const hit =
-      online.find((s) => s.id === token) ||
-      online.find((s) => s.id.startsWith(token)) ||
-      online.find((s) => label(s) === t) ||
-      online.find((s) => label(s).startsWith(t) && t.length >= 2)
-    return hit ? { token, kind: 'session', session: hit } : { token, kind: 'unresolved' }
-  })
+  return { sessions: uniq(sessions), nodes: uniq(nodes) }
 }
 
-// Any spawn's parent = its originator ([[session-nesting]]): the `@new` worker nests under the session that
-// wrote the mention — but ONLY when the author IS a real board session id. A dashboard 'human', a CLI
-// 'unknown', or a forge login resolves to no session → null → a top-level worker, never a phantom nest.
-// Exact id match only (lineage is provenance, not addressing — no prefix/name resolution), any liveness:
-// a parent that later closes is auto-promoted at read time by the derived tree.
-export function spawnParent(author: string, sessions: { id: string }[]): string | null {
-  return sessions.some((s) => s.id === author) ? author : null
+// The originator courtesy is the only automatic notification left in this module. It
+// resolves explicit stored session ids against online rows; prose @ references never call it.
+type Session = { id: string; node: string | null; name: string | null; title: string | null; liveness: string }
+
+function resolveOnlineSession(token: string, sessions: Session[]): Session | null {
+  const online = sessions.filter((session) => session.liveness === 'online')
+  const text = token.toLowerCase()
+  const label = (session: Session) => (session.name || session.title || '').toLowerCase()
+  return online.find((session) => session.id === token)
+    || online.find((session) => session.id.startsWith(token))
+    || online.find((session) => label(session) === text)
+    || online.find((session) => label(session).startsWith(text) && text.length >= 2)
+    || null
 }
 
-// ── dispatch (integration) ─────────────────────────────────────────────────────────────────────────────
-export type DispatchOutcome = { token: string; result: 'sent' | 'spawned' | 'offline' | 'unresolved' | 'failed'; detail?: string; note?: string }
-
-// The prompt an @-mentioned actor receives: the comment verbatim + a pointer back to the thread. It is a
-// nudge to look, never a rigid command — what to do is up to the comment's words.
-function mentionPrompt(threadId: string, node: string | null, author: string, text: string): string {
-  const re = node ? ` (re: ${node})` : ''
-  return `You were @-mentioned in issue thread "${threadId}"${re} by ${author}:\n\n  ${text.trim()}\n\n` +
-    `Read the thread and act as the comment asks (often just a look): \`spex issue ls --all\` lists them; ` +
-    `reply with \`spex issue reply ${threadId} --body -\`.`
-}
-// A non-open thread is settled work: a fresh worker spawned onto it must not re-implement what already
-// landed, so the prompt leads with the status and a verify-on-main-first instruction.
-export function newWorkerPrompt(threadId: string, node: string | null, author: string, text: string, status?: string | null): string {
-  // Keep inherited scope inside the text the worker receives: the create transaction derives its node only from the
-  // raw prompt's first [[id]] mention, so issue dispatch gets no private node-binding argument.
-  const on = node ? ` on node [[${node}]]` : ''
-  const settled = status && status !== 'open'
-    ? `NOTE: this thread is already resolved (status: ${status}) — the work it describes has likely LANDED. ` +
-      `Verify the current state on main FIRST; if main already satisfies the thread, reply with that finding ` +
-      `instead of re-implementing.\n\n`
-    : ''
-  return `Issue thread "${threadId}"${on} @-mentioned @new (by ${author}) for a fresh look:\n\n  ${text.trim()}\n\n` +
-    settled +
-    `Read the thread (\`spex issue ls --all\`, find ${threadId}) and act on it${node ? `; the relevant node is ${node}` : ''}.`
-}
+export type LoopIn = { originator: string }
+export type LoopInPick =
+  | { kind: 'deliver'; originator: string; session: Session }
+  | { kind: 'none' }
 
-// Parse a committed issue post's text for `@` actors and deliver to each. Best-effort and LOUD: the thread is
-// already committed, so a failed dispatch never fails the post — it is reported. sessions.ts is imported
-// lazily; with no actor mentions this returns [] without loading it or hitting the backend.
-export async function dispatchMentions(
-  text: string,
-  ctx: { threadId: string; node: string | null; author: string; status?: string | null },
-): Promise<DispatchOutcome[]> {
-  const { actors } = parseMentions(text)
-  if (!actors.length) return []
-  const { sendText, listSessions, sessionCreateRequest } = await import('./sessions.js')
-  const sessions = await listSessions()
-  const resolved = resolveActors(actors, sessions as unknown as ActorSession[])
-  const out: DispatchOutcome[] = []
-  for (const r of resolved) {
-    if (r.kind === 'unresolved') { out.push({ token: r.token, result: 'unresolved' }); continue }
-    if (r.kind === 'new') {
-      // the drain guard ([[mentions]]): @new on a settled thread still spawns (the summons may be a
-      // deliberate audit/re-measure), but the worker prompt carries the status and the outcome line warns.
-      const settled = ctx.status && ctx.status !== 'open' ? ctx.status : undefined
-      try {
-        const created = await sessionCreateRequest({
-          prompt: newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status),
-          parent: spawnParent(ctx.author, sessions),
-          launcher: r.launcher,
-        })
-        if (created.status !== 201) throw new Error(`${created.code || 'session_create_failed'}: ${created.error}`)
-        out.push({ token: r.token, result: 'spawned', detail: created.session.id, ...(settled ? { note: `thread ${settled}` } : {}) })
-      } catch (e) { out.push({ token: r.token, result: 'failed', detail: e instanceof Error ? e.message : String(e) }) }
-      continue
-    }
-    const res = await sendText(r.session.id, mentionPrompt(ctx.threadId, ctx.node, ctx.author, text), 'issues')
-    out.push(res.ok ? { token: r.token, result: 'sent', detail: r.session.id }
-                    : { token: r.token, result: 'offline', detail: res.error })
+// A committed reply can notify its originator as a courtesy. This is not a mention
+// dispatch or assignment, and it never creates a worker or retries an offline session.
+export function pickLoopIn(chain: (string | null)[], replier: string, sessions: Session[]): LoopInPick {
+  const seen = new Set<string>()
+  for (const originator of chain) {
+    if (!originator || originator === replier || seen.has(originator)) continue
+    seen.add(originator)
+    const session = resolveOnlineSession(originator, sessions)
+    if (session) return { kind: 'deliver', originator, session }
   }
-  return out
+  return { kind: 'none' }
 }
 
-// ── implicit originator loop-in + the dispatch fallback chain ([[mentions]] / [[remark-substrate]] R3) ────
-// A committed reply is ALSO auto-delivered as a COURTESY — never an assignment — to a FALLBACK CHAIN of
-// candidates, in order, stopping at the FIRST one that can be reached: for a remark this is the reading's
-// filer session, then the node's governing session, then nobody (it still surfaces on the board via the
-// teeth). This is a NOTIFICATION chain only — it resolves NOTHING (resolve stays a deliberate `spex remark resolve`,
-// R3); it just reaches an agent who can act. It is the same delivery pipe as dispatchMentions (one
-// online-resolution + one sendText), with the same cuts that keep courtesy ≠ assignment: deliver ONLY to an
-// ONLINE session (an unreachable link is skipped for the next, NEVER spawns a worker, NEVER drains — only an
-// explicit @new spawns); SKIP a candidate that is the replier (no self-notify); a candidate already reached by
-// an explicit @-target of this same text counts as delivered, so the chain STOPS (no double-delivery, no
-// needless escalation). Store-agnostic: a forge issue's author is a github login, resolves to no live session,
-// and the chain runs dry silently — exactly right.
-export type LoopIn = { originator: string }   // the candidate we actually reached (a filer OR a governing-session fallback)
-
-// The courtesy prompt — framed as a heads-up, never a command (that is what an @-mention's mentionPrompt is).
 function originatorPrompt(threadId: string, node: string | null, replier: string, text: string): string {
   const re = node ? ` (re: ${node})` : ''
-  return `A new reply landed on a thread you originated — "${threadId}"${re}, from ${replier}:\n\n  ${text.trim()}\n\n` +
-    `This is a courtesy heads-up (you started this thread), not an assignment. Look if it concerns you; ` +
-    `\`spex issue ls --all\` lists them, reply with \`spex issue reply ${threadId} --body -\`.`
+  return `A new reply landed on a thread you originated - "${threadId}"${re}, from ${replier}:\n\n  ${text.trim()}\n\n` +
+    `This is a courtesy heads-up, not an assignment. Look if it concerns you; ` +
+    `\`spex issue ls --all\` lists threads and \`spex issue reply ${threadId} --body -\` replies.`
 }
 
-// The pure fallback decision (testable without sessions.ts): walk the ordered chain (nulls/dupes/the-replier
-// pruned) and return the FIRST link that resolves to an online session — that is who the courtesy goes to. A
-// link already reached by an explicit @-target of this same text short-circuits to `reached` (stop, no
-// double-delivery — the actor already has it); an offline/absent link falls through to the next. `none` means
-// the chain ran dry (nobody online). This is the whole fallback logic; delivery is a thin sendText around it.
-export type LoopInPick =
-  | { kind: 'deliver'; originator: string; session: ActorSession }
-  | { kind: 'reached' }
-  | { kind: 'none' }
-export function pickLoopIn(
-  chain: (string | null)[],
-  replier: string,
-  sessions: ActorSession[],
-  alreadyDelivered?: Set<string>,
-): LoopInPick {
-  const seen = new Set<string>()
-  const candidates = chain.filter((c): c is string => !!c && c !== replier && !seen.has(c) && (seen.add(c), true))
-  for (const originator of candidates) {
-    const [resolved] = resolveActors([originator], sessions)
-    if (resolved.kind !== 'session') continue                 // offline / no live session → try the next fallback link
-    if (alreadyDelivered?.has(resolved.session.id)) return { kind: 'reached' }   // already an explicit @-target: stop
-    return { kind: 'deliver', originator, session: resolved.session }
-  }
-  return { kind: 'none' }
-}
-
-// `chain` is the ordered fallback list. We deliver the courtesy to the first online link and STOP; an
-// offline/failed link falls through to the next. NOTIFICATION ONLY — this never touches a `resolved` bit
-// (resolve is a deliberate `spex remark resolve`), never spawns (only `@new` spawns).
 export async function notifyOriginator(
   chain: (string | null)[],
   replier: string,
   text: string,
-  ctx: { threadId: string; node: string | null; alreadyDelivered?: Set<string> },
+  ctx: { threadId: string; node: string | null },
 ): Promise<LoopIn | null> {
-  const seen = new Set<string>()
-  if (!chain.some((c) => c && c !== replier && !seen.has(c) && (seen.add(c), true))) return null   // nothing to do → no session load
+  if (!chain.some((candidate) => candidate && candidate !== replier)) return null
   const { sendText, listSessions } = await import('./sessions.js')
-  const pick = pickLoopIn(chain, replier, await listSessions() as unknown as ActorSession[], ctx.alreadyDelivered)
-  if (pick.kind !== 'deliver') return null                    // reached via @ / nobody online → silent
-  const res = await sendText(pick.session.id, originatorPrompt(ctx.threadId, ctx.node, replier, text), 'issues')
-  return res.ok ? { originator: pick.originator } : null      // a failed send behaves like offline: silent
+  const pick = pickLoopIn(chain, replier, await listSessions() as unknown as Session[])
+  if (pick.kind !== 'deliver') return null
+  const result = await sendText(pick.session.id, originatorPrompt(ctx.threadId, ctx.node, replier, text), 'issues')
+  return result.ok ? { originator: pick.originator } : null
 }
 
-// The set of session ids a dispatch ALREADY reached (sent or spawned) — what the loop-in skips to avoid a
-// double-delivery to an originator who was also an explicit @-target.
-export function deliveredIds(outcomes: DispatchOutcome[]): Set<string> {
-  return new Set(outcomes.filter((o) => (o.result === 'sent' || o.result === 'spawned') && o.detail).map((o) => o.detail!))
-}
-
-// A one-line human summary of what a dispatch did, for the CLI to echo after a post. The optional loop-in is
-// noted DISTINCT from the @-dispatch — a courtesy copy, not an assignment.
-export function summarize(outcomes: DispatchOutcome[], loopIn?: LoopIn | null): string {
-  const parts: string[] = []
-  if (outcomes.length) parts.push('@ ' + outcomes.map((o) => {
-    if (o.result === 'sent') return `${o.token}→sent`
-    if (o.result === 'spawned') return `${o.token}→${o.detail}${o.note ? ` ⚠ ${o.note} — likely already landed` : ''}`
-    if (o.result === 'offline') return `${o.token}→offline (stored)`
-    if (o.result === 'unresolved') return `${o.token}→? (no live session; stored)`
-    return `${o.token}→failed (${o.detail})`
-  }).join('  ·  '))
-  if (loopIn) parts.push(`↩ looped in originator @${loopIn.originator} (online)`)
-  return parts.join('  ·  ')
-}
+export const summarizeLoopIn = (loopIn?: LoopIn | null): string =>
+  loopIn ? `looped in originator @${loopIn.originator} (online)` : ''

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

@@ -131,7 +131,7 @@ function turnExited(rec: HarnessDeliveryRecord, outcome: Extract<TurnOutcome, {
   const cas = outcome.casCode === 0 ? '' : `; error CAS reporter also exited with code ${outcome.casCode}`
   return {
     ok: false,
-    error: `opencode-headless turn exited with code ${outcome.code} during startup for session ${rec.session}${cas} - prompt delivery FAILED`,
+    error: `opencode-headless turn exited with code ${outcome.code} during startup for session ${rec.session}${cas} - immediate wake failed`,
   }
 }
 
@@ -173,7 +173,7 @@ export async function spawnOpenCodeHeadlessTurn(
       const outcome = readTurnOutcome(outcomePath)
       if (outcome?.state === 'exit') return turnExited(rec, outcome)
       if (outcome?.state === 'invalid') {
-        return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - prompt delivery NOT confirmed` }
+        return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - immediate wake not confirmed` }
       }
       if (Date.now() >= deadline) break
       await sleep(Math.min(OUTCOME_POLL_MS, deadline - Date.now()))
@@ -181,19 +181,19 @@ export async function spawnOpenCodeHeadlessTurn(
 
     const first = readTurnOutcome(outcomePath)
     if (first?.state === 'exit') return turnExited(rec, first)
-    if (!first) return { ok: false, error: `opencode-headless turn for session ${rec.session} never confirmed startup - prompt delivery FAILED` }
-    if (first.state === 'invalid') return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - prompt delivery NOT confirmed` }
+    if (!first) return { ok: false, error: `opencode-headless turn for session ${rec.session} never confirmed startup - immediate wake failed` }
+    if (first.state === 'invalid') return { ok: false, error: `opencode-headless turn for session ${rec.session} wrote an invalid exit outcome - immediate wake not confirmed` }
     if (first.state === 'reporting') {
-      return { ok: false, error: `opencode-headless turn exited with code ${first.code} but its error CAS reporter did not finish for session ${rec.session} - prompt delivery FAILED` }
+      return { ok: false, error: `opencode-headless turn exited with code ${first.code} but its error CAS reporter did not finish for session ${rec.session} - immediate wake failed` }
     }
     if (!pidAlive(first.pid)) {
-      return { ok: false, error: `opencode-headless turn wrapper died before reporting an outcome for session ${rec.session} - prompt delivery FAILED` }
+      return { ok: false, error: `opencode-headless turn wrapper died before reporting an outcome for session ${rec.session} - immediate wake failed` }
     }
     await sleep(OUTCOME_POLL_MS)
     const settled = readTurnOutcome(outcomePath)
     if (settled?.state === 'exit') return turnExited(rec, settled)
     if (settled?.state !== 'running' || settled.pid !== first.pid || !pidAlive(settled.pid)) {
-      return { ok: false, error: `opencode-headless turn did not remain live through startup for session ${rec.session} - prompt delivery FAILED` }
+      return { ok: false, error: `opencode-headless turn did not remain live through startup for session ${rec.session} - immediate wake failed` }
     }
     return { ok: true }
   } catch (error) {

package/spec-cli/src/opencode.ts

@@ -92,11 +92,8 @@ export const SpexcodePlugin = async (ctx) => {
     })()
   }
 
-  // the rendezvous daemon, from the shared runtime: {type:"reply"} injects into the root session (a plugin
-  // that adopted no session yet reply-rejects synchronously, BEFORE repaint-done, so the sender fails loud
-  // instead of confirming a prompt that can never inject); {type:"repaint"} answers repaint-done in the same
-  // synchronous parse pass — confirmation means PARSED, not processed. The injection itself (a whole model
-  // turn: the SDK prompt call resolves only when the TURN ends) runs BEHIND the confirm.
+  // The shared rendezvous server receives best-effort reply pokes. An unadopted plugin simply leaves the
+  // timeline line for its next turn boundary; the SDK injection remains host-owned.
   rt.serveRendezvous(injectPrompt, { canInject: () => !!(client && rootSession) })
 
   const toolPayload = (input, output) => {

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

@@ -8,7 +8,7 @@ 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 ControlRequest = { type: 'deliver'; text: string; mid?: string }
 type ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))
@@ -24,7 +24,7 @@ export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: s
 }
 
 export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
-  controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text }, {
+  controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text, mid: rec.mid }, {
     name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
     rejected: 'pi-headless controller rejected the request',
   })
@@ -101,10 +101,10 @@ export class PiHeadlessController {
     if (request.type !== 'deliver') return { ok: false, error: 'unknown pi-headless control request' }
     if (!request.text) return { ok: false, error: 'empty prompt - nothing to deliver' }
 
-    // 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.
+    // A live extension listener is an in-flight pi turn. Only a proven absent listener may cold-wake a saved
+    // session; an inconclusive probe must not start a duplicate turn.
     const { deliverViaSocketOrWake } = await import('./harness.js')
-    return deliverViaSocketOrWake(this.id, request.text, async () => {
+    return deliverViaSocketOrWake(this.id, request.text, request.mid, 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 }

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

@@ -2,7 +2,6 @@ import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 import { alive, withSessionInputLock } from './sessions.js'
-import { runSessionOperationSync } from './session-maintenance.js'
 
 const pexec = promisify(execFile)
 const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
@@ -363,10 +362,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
-  return runSessionOperationSync({ op: 'terminal-input', sessionId: id }, () => withSessionInputLock(id, () => {
-      sendControl(subscription.bridge!, { t: 'input', data })
-      return true
-    }) ?? false)
+  return 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/reviewSnapshot.ts

@@ -9,6 +9,7 @@ export type ReviewEvalNode = {
 export type ReviewSnapshot = {
   issues: any[]
   evalNodes: ReviewEvalNode[]
+  forgeRevision: number
 }
 
 let current: ReviewSnapshot | null = null

package/spec-cli/src/reviews.ts

@@ -1,11 +1,12 @@
 import { createHash } from 'node:crypto'
 import { listSessions } from './sessions.js'
-import { getBoard } from './graphCache.js'
+import { getBoard, getBoardForForgeRevision } from './graphCache.js'
 import { buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
 import { evalTimeline } from '../../spec-eval/src/evaltab.js'
 import { issuesEnabled as issuesEnabledForReview } from './localIssues.js'
 import { issueStores as issueStoresForReview } from './issues.js'
 import { hasReviewSnapshot, readReviewSnapshot } from './reviewSnapshot.js'
+import { residentForgeRevision, residentForgeState } from '../../spec-forge/src/resident.js'
 // @ts-expect-error The dashboard module is deliberately plain JS so the browser and server execute the
 // exact same tokenizer/matcher. It is shipped beside the built dashboard by the root package manifest.
 import { EVAL_FILTER_KIND, evalFilterModel, evalReviewState, issueFilterModel, tokenFilterState } from '../../spec-dashboard/src/reviewFilters.js'
@@ -124,7 +125,11 @@ export async function issuesReview(query: string | undefined, requestedPage: unk
   // The first request must wait for the first atomic publication. Once one exists, a graph refresh may be
   // rebuilding unrelated board/session state; the published review source remains a valid answer and its
   // revision/poll path will deliver the next generation without making this page join that flight.
+  residentForgeState()
   if (!hasReviewSnapshot()) await getBoard()
+  else if (readReviewSnapshot().forgeRevision < residentForgeRevision()) {
+    await getBoardForForgeRevision(residentForgeRevision())
+  }
   const sessions = await listSessions()
   const issues = readReviewSnapshot().issues.slice().sort(issueOrder)
   const text = String(query ?? '').trim() || ISSUE_QUERY_DEFAULT

package/spec-cli/src/root-lru.ts

@@ -0,0 +1,54 @@
+// @@@ root-lru - ONE bounded root→key cache policy, for every layer that keeps immutable per-HEAD work warm.
+// A leaf module on purpose: it imports nothing from the spec graph, the eval sidecar, or git, so both layers
+// can depend on it without either owning the other ([[source-of-truth]]).
+//
+// The policy is reference-counted, not plain LRU, and the distinction is the whole point. Entries are keyed by
+// something IMMUTABLE (a HEAD, or a ledger path + HEAD), so two checkouts sitting on the same commit must share
+// one entry rather than build it twice. A root moving A→B therefore drops A only when NO other root still
+// points at it; otherwise a sequence of successful rebuilds retains one whole index per commit until the slot
+// bound finally evicts them. Bumping an unchanged root is a pure recency touch (delete + reinsert), which is
+// what makes `roots` insertion-ordered enough for the eviction loop to mean "oldest root".
+//
+// This existed twice, verbatim in logic and even in name — `touchRoot` in git.ts (index/drift) and again in
+// spec-eval's scenariofresh.ts (scenario chains), whose comment said it was "mirroring historyIndex/driftIndex
+// in git.ts". Both authors knew; neither had anywhere to put it. Now they do.
+
+// slot bound for one cache family. Every caller names its own env knob and default so operators can tune the
+// families independently, but nobody gets to invent a different FLOOR or a bare literal — a cache whose bound
+// is a magic number cannot be tuned in the field at all (scenariofresh's was a hardcoded 16).
+// @@@ unparseable is not zero - the shape both copies used, `Math.max(4, Number(env || fallback))`, returns
+// NaN for a mistyped value, and `size > NaN` is always false: one typo in an env var silently turned the
+// bound OFF and let the cache grow without limit. A bound that fails open is worse than no bound, because
+// nothing reports it. Anything that does not parse to a positive number falls back to the caller's default.
+export const rootSlots = (env: string | undefined, fallback: number): number => {
+  const asked = Number(env)
+  return Math.max(4, Number.isFinite(asked) && asked > 0 ? asked : fallback)
+}
+
+// Record that `root` now wants `key`, evicting what no root wants any more and keeping `roots` within `slots`.
+// `cache` is the caller's own keyed store; this owns only the ROOT→key bookkeeping and the eviction decision.
+export function touchRoot(
+  roots: Map<string, string>,
+  cache: Map<string, unknown> & { delete(key: string): boolean },
+  root: string,
+  key: string,
+  slots: number,
+): void {
+  const previous = roots.get(root)
+  if (previous !== key) {
+    roots.set(root, key)
+    // the old key survives only while some OTHER root still names it — immutable entries are shared, so
+    // dropping one root's view must not throw away a sibling checkout's warm work.
+    if (previous && ![...roots.values()].includes(previous)) cache.delete(previous)
+  } else {
+    roots.delete(root)
+    roots.set(root, key)   // recency bump: reinsertion is what makes the eviction loop below pick the oldest
+  }
+  while (roots.size > slots) {
+    const oldest = roots.keys().next().value as string | undefined
+    if (oldest === undefined) break
+    const oldKey = roots.get(oldest)
+    roots.delete(oldest)
+    if (oldKey && ![...roots.values()].includes(oldKey)) cache.delete(oldKey)
+  }
+}

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

@@ -1,14 +1,5 @@
 import { spawnSync } from 'node:child_process'
 
-// @@@ session-runtime guard ([[platform-support]]) - SpexCode's session orchestration rests on POSIX
-// primitives with no native-Windows analog: tmux (the durable detached PTY + capture-pane scrollback +
-// multi-client reattach fabric), hand-written bash launch scripts, and filesystem-path AF_UNIX control
-// sockets. The supported runtime is POSIX — Linux, macOS, or Windows *via WSL2* (a real Linux kernel where
-// tmux/bash/unix-sockets all work). This is the honest gate at the entry to the session runtime: detect the
-// load-bearing primitive (tmux) missing and print ONE actionable line naming the fix, instead of letting a
-// cryptic downstream ENOENT be the user's first signal. Read-only CLI (init/lint/board) never calls this,
-// so it still runs anywhere the launcher does — only the session-launch path (`spex serve`) is gated.
-
 // tmux presence is the primitive we actually depend on, so probe THAT rather than assuming by platform:
 // this also catches a bare POSIX box that simply hasn't installed tmux, not only native Windows.
 export function hasTmux(): boolean {

package/spec-cli/src/session-cursors.ts

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { sessionArtifactPath, sessionStoreDir } from './layout.js'
+import type { TimelineEvent } from './session-timeline.js'
+
+// @@@ session-cursors - a reader's durable place in a log. One `cursors.json` per session in its global store
+// dir: `inbox` is its place in its OWN timeline, `follows` one entry per followed session. A position is an
+// event INDEX into timeline.ndjson (lines already consumed), so it is also the index of the next unread event.
+
+export type Cursors = { version: 1; inbox: number; follows: Record<string, number> }
+
+const cursorsPath = (id: string): string => sessionArtifactPath(id, 'cursors.json')
+const at = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0)
+
+// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
+// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
+// store dir is gone are dropped here — expiry is this read, and the next write persists it.
+export function readCursors(id: string): Cursors {
+  let raw: { inbox?: unknown; follows?: unknown } | null = null
+  try { raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8')) } catch { /* no cursors yet */ }
+  const follows: Record<string, number> = {}
+  const stored = raw?.follows
+  if (stored && typeof stored === 'object') {
+    for (const [target, pos] of Object.entries(stored as Record<string, unknown>)) {
+      if (!target || !existsSync(sessionStoreDir(target))) continue
+      follows[target] = at(pos)
+    }
+  }
+  return { version: 1, inbox: at(raw?.inbox), follows }
+}
+
+// Written whole and atomically, one field per line — the same shape as the session record, so the mark-active
+// hook can read its inbox position with an exact whole-line match in pure shell.
+function writeCursors(id: string, cursors: Cursors): void {
+  const dir = sessionStoreDir(id)
+  mkdirSync(dir, { recursive: true })
+  const tmp = join(dir, `.cursors.json.${process.pid}.tmp`)
+  writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n')
+  renameSync(tmp, cursorsPath(id))
+}
+
+export const inboxCursor = (id: string): number => readCursors(id).inbox
+
+// A reader that has shown everything up to `to`. Monotonic: a stale read can leave the position too low
+// (a message shown twice), never too high (a message lost).
+export function advanceInbox(id: string, to: number): void {
+  const cursors = readCursors(id)
+  if (to <= cursors.inbox) return
+  writeCursors(id, { ...cursors, inbox: to })
+}
+
+export const followCursor = (id: string, target: string): number | null => {
+  const stored = readCursors(id).follows[target]
+  return stored === undefined ? null : stored
+}
+
+// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
+export function advanceFollow(id: string, target: string, to: number): void {
+  const cursors = readCursors(id)
+  const stored = cursors.follows[target]
+  if (stored !== undefined && to <= stored) return
+  writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } })
+}
+
+export const followedSessions = (id: string): string[] => Object.keys(readCursors(id).follows)
+
+const sameStatus = (a: TimelineEvent, b: TimelineEvent): boolean =>
+  a.kind === 'status' && b.kind === 'status' && a.status === b.status
+  && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null)
+
+// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
+// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
+// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
+// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
+// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
+// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
+// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
+// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
+// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
+// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
+export function unreadSince(events: TimelineEvent[], from: number): { events: TimelineEvent[]; at: number[]; next: number } {
+  const start = Math.min(Math.max(0, Math.floor(from)), events.length)
+  let prev: TimelineEvent | null = null
+  for (let i = start - 1; i >= 0; i--) if (events[i].kind === 'status') { prev = events[i]; break }
+  const out: TimelineEvent[] = []
+  const at: number[] = []
+  for (let i = start; i < events.length; i++) {
+    const e = events[i]
+    if (e.kind === 'status') {
+      if (prev && sameStatus(prev, e)) continue
+      prev = e
+    }
+    out.push(e)
+    at.push(i)
+  }
+  return { events: out, at, next: events.length }
+}