spexcode 0.5.7 → 0.5.9

package/spec-cli/src/materialize.ts

@@ -17,27 +17,6 @@ export type MaterializedArtifact = {
 }
 export type MaterializeResult = { contentHash: string; planted: MaterializedArtifact[] }
 
-// @@@ materialize - the materialize step (≈0.85s), anchored on GIT-NATIVE events only ([[commit-surgery]]):
-// spex verbs (init/materialize), session-worktree creation, and the planted git hooks (pre-commit,
-// post-checkout, post-merge) — never a harness event; the harness is a READER of the materialized files, not
-// 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
-// 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.
-//
-// THE FORGETTING LAW ([[harness-delivery]]): materialize(P₂) ∘ materialize(P₁) = materialize(P₂) — one pass
-// under the current policy fully forgets every prior policy's artifacts; idempotence is the special case
-// P₂ = P₁, and dematerialize (= materialize(∅), what `spex uninstall` builds on) is the empty policy. The
-// implementation is ERASE-THEN-ASSERT over a CLOSED set of landing points: each is first erased
-// unconditionally by its IDENTITY STAMP (sentinel blocks, the shim's dispatch.sh command line, the generated
-// mark on skills/agents, the filter config namespace, the skip-worktree bit), then rewritten per the current
-// policy (possibly to nothing). There are no policy-pair branches. The one cross-tree migration receipt below
-// preserves old common ignore entries until every registered tree owns its local projection; it never reads or
-// reconstructs a sibling policy.
-
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
 // the ONE spex entry: the launcher (bin/spex.mjs), never a raw `tsx cli.ts` pair — the launcher owns tsx
@@ -62,14 +41,6 @@ export function contentHash(proj: string): string {
   } catch { return '' }
 }
 
-// @@@ footprint kinds ([[residence]]) - the vote axis is RETIRED: materialized artifacts carry no facts, so
-// they are NEVER tracked — there is exactly ONE residence behavior, not three. `.spec` + `spexcode.json` are ALWAYS
-// tracked (git is the database — no knob can untrack them); machine facts (shims, spexcode.local.json),
-// run residue (.worktrees/) stays in the common exclude; tree-selected artifacts are hidden by a managed
-// working .gitignore block whose tracked bytes stay pristine through the content filter. A contract file the host TRACKS — or one the user has begun
-// writing THEIR OWN prose into — is covered by the clean/smudge content filter ([[content-filter]]). An
-// environment without the generator (a teammate's clone, CI, a cloud agent) runs `spex materialize` in its
-// setup step — there is no committed-artifact delivery mode.
 export function retiredAxisNotice(cfg: { render?: string; private?: boolean }): void {
   if (!cfg.render?.trim() && !cfg.private) return
   const field = cfg.render?.trim() ? `"render": "${cfg.render.trim()}"` : '"private": true'
@@ -123,12 +94,6 @@ function publishSelection(path: string, body: string): void {
   renameSync(prepared, path)
 }
 
-// @@@ contract kind detection ([[residence]]) - a contract file's residence is a LIVE CONTENT FACT, not
-// an install-time choice, re-judged on every materialize: TRACKED → filter domain; untracked + wholly ours
-// (nothing left after stripping our sentinel block) → exclude domain; untracked + HOST CONTENT present (the
-// user began writing their own prose into it) → neither hidden nor tracked-for-them: the exclude entry is
-// withheld (hiding user content would make their prose invisible to git — data-loss shaped) and the clean
-// filter is pre-armed so their eventual, entirely-their-own `git add` strips our block automatically.
 const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
 export function stripSpexcodeBlock(text: string): string {
   const m = SENTINEL_RE.exec(text)
@@ -170,13 +135,6 @@ function sweepGeneratedAgents(dir: string | null): void {
   }
 }
 
-// @@@ dematerialize - materialize(∅): the ERASE phase, also the whole of a backout ([[spex-uninstall]] adds
-// only the global store + plugin sweep + optional git hooks on top). Every removal is gated on an identity
-// stamp, so it deletes ONLY what a materialize wrote — never the user's prose, settings, or any .spec data. Order
-// matters once: the managed blocks leave the WORKING contract files before the content filter's config goes
-// (edge ③ in [[content-filter]] — a block outliving its clean filter surfaces as an uncommitted change).
-// `arts` (live skill/agent node names) widens the sweep to pre-stamp legacy files; the GENERATED_MARK sweep
-// covers everything materialized since, including products of renamed/deleted nodes.
 function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolean): void {
   for (const h of HARNESSES) {
     // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-

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 {