spexcode 0.5.9 → 0.6.1

package/spec-cli/src/reviews.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { listSessions } from './sessions.js'
 import { getBoard, getBoardForForgeRevision } from './graphCache.js'
-import { buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
+import { type SessionEvalOrderRow, 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'
@@ -217,15 +217,26 @@ export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
 
 const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
 
-function evalNeighbor(item: any): EvalNeighbor {
+function evalNeighbor(item: any, stateOf: (row: { node: string; scenario: string }) => string): EvalNeighbor {
   return {
     node: String(item.node),
     scenario: String(item.scenario),
-    state: String(item.state ?? evalReviewState(item)),
+    state: stateOf(item),
   }
 }
 
-export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario: string, want = 5) {
+// `sequence` is the whole measured population in list order; `stateOf` answers only for rows whose freshness
+// was actually computed. On a focused build those are two different sets — the sequence spans the scope, the
+// states cover the selected row and its window — which is exactly why the state is looked up rather than
+// carried: a row this response does not render contributes its POSITION and nothing else.
+export function boundedEvalNeighbors(
+  sequence: { node: string; scenario: string }[],
+  node: string,
+  scenario: string,
+  stateOf: (row: { node: string; scenario: string }) => string,
+  want = 5,
+) {
+  const items = sequence
   const key = `${node}\0${scenario}`
   const index = items.findIndex((item) => evalItemKey(item) === key)
   if (index < 0) return { prev: [], next: [], total: items.length, index: null, order: 'default' as const }
@@ -235,8 +246,8 @@ export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario
   const nextN = Math.min(after, Math.max(Math.ceil(take / 2), take - before))
   const prevN = Math.min(before, take - nextN)
   return {
-    prev: items.slice(index - prevN, index).reverse().map(evalNeighbor),
-    next: items.slice(index + 1, index + 1 + nextN).map(evalNeighbor),
+    prev: items.slice(index - prevN, index).reverse().map((item) => evalNeighbor(item, stateOf)),
+    next: items.slice(index + 1, index + 1 + nextN).map((item) => evalNeighbor(item, stateOf)),
     total: items.length,
     index,
     order: 'default' as const,
@@ -248,12 +259,22 @@ export function projectEvalDetail(
   historySource: ReviewItem[],
   node: string,
   scenario: string,
-  metadata: { scope?: string | null; summary?: SessionEvals['summary']; evalRevision?: SessionEvals['evalRevision'] } = {},
+  metadata: {
+    scope?: string | null
+    summary?: SessionEvals['summary']
+    evalRevision?: SessionEvals['evalRevision']
+    // the scope's whole measured sequence, when `items` deliberately holds only the rendered window
+    sequence?: { node: string; scenario: string }[]
+  } = {},
 ): EvalDetailReview {
   const results = items.filter((item: any) => item.filterKind === EVAL_FILTER_KIND.RESULT)
   const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null
   const history = historySource.filter((reading: any) => String(reading.scenario) === scenario)
-  const neighbors = boundedEvalNeighbors(results, node, scenario)
+  const stateByKey = new Map(results.map((item: any) => [evalItemKey(item), String(item.state ?? evalReviewState(item))]))
+  const sequence = metadata.sequence
+    ?? results.map((item: any) => ({ node: String(item.node), scenario: String(item.scenario) }))
+  const neighbors = boundedEvalNeighbors(sequence, node, scenario,
+    (row) => stateByKey.get(evalItemKey(row)) ?? 'empty')
   const scope = metadata.scope ?? null
   return {
     scope,
@@ -266,15 +287,38 @@ export function projectEvalDetail(
   }
 }
 
+// the measured population in list order, from the freshness-free rows: a filed reading leads (newest first),
+// and the tie-breaks are the identity ones — the SAME comparison `byNewest` applies, over the only fields it
+// actually reads. Blind rows never enter, exactly as the detail's own `results` filter excludes them.
+export function measuredSequence(order: SessionEvalOrderRow[]): { node: string; scenario: string }[] {
+  return order.filter((row) => row.ts)
+    .sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
+      || a.node.localeCompare(b.node) || a.scenario.localeCompare(b.scenario))
+    .map((row) => ({ node: row.node, scenario: row.scenario }))
+}
+
+// the nodes whose verdicts the response will publish: the selected row's, plus a window wide enough to
+// contain any neighbour boundedEvalNeighbors can choose (it takes at most five, split around the index).
+export function focusNodes(order: SessionEvalOrderRow[], node: string, scenario: string): string[] {
+  const sequence = measuredSequence(order)
+  const index = sequence.findIndex((row) => row.node === node && row.scenario === scenario)
+  if (index < 0) return [node]
+  return [...new Set([node, ...sequence.slice(Math.max(0, index - 6), index + 7).map((row) => row.node)])]
+}
+
 export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview | null> {
   if (scope) {
-    const model = await buildSessionEvals(scope)
+    // A detail renders ONE row plus at most five neighbours, but owes the whole population's index/total.
+    // So name the window from the freshness-free sequence and let only those nodes pay the freshness pass;
+    // a build that finds a full cached model ignores the pick and answers from it instead.
+    const model = await buildSessionEvals(scope, (order) => focusNodes(order, node, scenario))
     if (!model) return null
     const sourceNode = model.nodes.find((candidate) => candidate.id === node)
     return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
       scope,
       summary: model.summary,
       evalRevision: model.evalRevision,
+      ...(model.order ? { sequence: measuredSequence(model.order) } : {}),
     })
   }
   await getBoard()
@@ -335,13 +379,13 @@ export async function evalsReview(query: string | undefined, requestedPage: unkn
     const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
     return {
       scope,
-      gates: model.gates,
+      gates: model.gates ?? [],
       unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
       summary: model.summary,
       evalRevision: model.evalRevision,
       impact: model.impact,
       ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-        domain: 'evals', scope, items, gates: model.gates, summary: model.summary,
+        domain: 'evals', scope, items, gates: model.gates ?? [], summary: model.summary,
         evalRevision: model.evalRevision, impact: model.impact, sessions: sessions.map((session) => session.id),
       }),
     }

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

@@ -4,10 +4,13 @@ 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.
+// dir: `follows` holds one entry per followed session, including the reader's own id when it watches its own
+// log. A position is an event INDEX into timeline.ndjson (lines already consumed), so it is also the index of
+// the next unread event. A position is NOT a work list: what a session still owes its agent is a debt, and it
+// lives in its own queue ([[delivery-queue]]). Binding both to one counter is what made a session's own status
+// lines get consumed as though they were mail, and made "anything outstanding?" a scan of all history.
 
-export type Cursors = { version: 1; inbox: number; follows: Record<string, number> }
+export type Cursors = { version: 1; 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)
@@ -16,7 +19,7 @@ const at = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v)
 // 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
+  let raw: { 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
@@ -26,11 +29,11 @@ export function readCursors(id: string): Cursors {
       follows[target] = at(pos)
     }
   }
-  return { version: 1, inbox: at(raw?.inbox), follows }
+  return { version: 1, 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.
+// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
+// readable by an exact whole-line match where a value regex would not be.
 function writeCursors(id: string, cursors: Cursors): void {
   const dir = sessionStoreDir(id)
   mkdirSync(dir, { recursive: true })
@@ -39,22 +42,13 @@ function writeCursors(id: string, cursors: Cursors): void {
   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.
+// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
 export function advanceFollow(id: string, target: string, to: number): void {
   const cursors = readCursors(id)
   const stored = cursors.follows[target]

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

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { sessionStoreDir } from './layout.js'
-import { advanceFollow, followCursor, inboxCursor, unreadSince } from './session-cursors.js'
+import { advanceFollow, followCursor, unreadSince } from './session-cursors.js'
 import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js'
 import { sessionLabel, type DisplayStatus, type Session } from './sessions.js'
 
@@ -158,12 +158,12 @@ export async function followSessions(emit: (line: string) => void, opts: FollowO
       state.delete(id)
       emit(`${tag}[spex] closed · removed  [id ${id}]`)
     }
-    // THE INBOX — the follower's own log, read past the cursor `cursors.json` already holds and NEVER advanced
-    // here: the turn-boundary mark-active hook is the inbox's one reader ([[session-timeline]]), and advancing
-    // behind its back would wake this process on a message the agent is then never shown. Re-read every tick, so
-    // a line that hook has since injected stops counting as unread and cannot wake a later wait twice.
+    // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own entry in `cursors.json`. It is
+    // a WATCH, not a delivery: a message reaches the agent as a prompt through the adapter ([[delivery-queue]]),
+    // so this position only decides what THIS process has already reported and can never make an agent miss
+    // mail. Never advanced here in take mode — the waiter stops on the event and the next wait resumes on it.
     if (self && existsSync(sessionStoreDir(self))) {
-      const mine = unreadSince(timelineEvents(self), inboxCursor(self))
+      const mine = unreadSince(timelineEvents(self), followCursor(self, self) ?? 0)
       for (let k = 0; k < mine.events.length; k++) {
         const e = mine.events[k]
         if (e.kind !== 'sent') continue

package/spec-cli/src/sessions.ts

@@ -12,6 +12,7 @@ import { adapterLoadedReferenceState, defaultHarness, HARNESSES, sessionIdentity
 import { materialize } from './materialize.js'
 import { mainBranch, mainRoot, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, rawLaunchReadinessOriginal, readAliasedRawRecord, readRecordEntry, readAliasedRecordEntry, readPublicRecordEntry, envSessionId, isSessionLifecycle, isSessionProposal, type PublicRecordEntry, type RawRecord, type SessionLifecycle, type SessionProposal } from './layout.js'
 import { appendSent, recordStatus, lastHumanSendVia } from './session-timeline.js'
+import { drain, enqueue, owesDelivery } from './delivery-queue.js'
 import { stripRefSigil } from './mentions.js'
 import { shQuote } from './sh.js'
 import { assertSessionStopSafe, ResourceConflict } from './host-resources.js'
@@ -20,6 +21,7 @@ import { bindCodexGeneration, codexGenerationBindingForSession, commitCodexGener
 
 const pexec = promisify(execFile)
 export const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
+const DEFER_FOOTPRINT_REFRESH = { SPEXCODE_DEFER_FOOTPRINT_REFRESH: 'session-create' }
 const HARNESS = defaultHarness
 const COLS = 120, ROWS = 32
 const DEFAULT_MAX_ACTIVE = 8
@@ -71,7 +73,7 @@ const PROPOSAL_STATUS: Record<Proposal, DisplayStatus> = { merge: 'review', noth
 
 export type Session = {
   id: string; node: string | null; branch: string | null; path: string
-  label: string; headline: string   // the DERIVED display strings ([[session-label]]) — the only names surfaces read
+  label: string; title: string   // `label` remains the stable search handle; `title` is the one visible session name
   raw: { name: string | null; title: string | null }   // the bare parts, for explicit consumers only (rename prefill)
   parent: string | null   // the SPAWNING session's id ([[session-nesting]]) — set once at creation when `spex session new` ran inside another session, else null; the frontend folds a child under it at read time
   harness: string   // which harness (claude|codex) runs this session — carried so liveness/occupancy route through its adapter
@@ -110,18 +112,26 @@ function removeLaunchFile(id: string): void {
 
 // One line, bounded — the launch prompt's shape when it enters a compact headline.
 export const HEADLINE_PREVIEW_COLUMNS = 60
+function isBareUrl(text: string): boolean {
+  return /^(?:https?|git|ssh):\/\/\S+$/i.test(text)
+}
 function oneLinePreview(text: string, n = HEADLINE_PREVIEW_COLUMNS): string {
-  const first = text.split('\n').map((l) => l.trim()).find(Boolean) || ''
+  const lines = text.split('\n').map((l) => l.trim()).filter(Boolean)
+  const first = lines.find((line) => !isBareUrl(line)) || lines[0] || ''
   return first.length > n ? first.slice(0, n - 1) + '…' : first
 }
 
 export const deriveLabel = (r: { name?: string | null; node?: string | null; title?: string | null; branch?: string | null; id: string }): string =>
   r.name || r.node || r.title || r.branch || r.id
-export const deriveHeadline = (r: { name?: string | null; activity?: string | null; promptPreview?: string | null; node?: string | null; title?: string | null; branch?: string | null; id: string }): string =>
-  r.name || r.activity || r.promptPreview || r.node || r.title || r.branch || r.id
+export const deriveTitle = (r: { name?: string | null; activity?: string | null; note?: string | null; promptPreview?: string | null; node?: string | null; title?: string | null; branch?: string | null; id: string }): string =>
+  r.name || r.activity || (r.note ? oneLinePreview(r.note) : '') || (r.promptPreview ? oneLinePreview(r.promptPreview) : '') || r.node || r.title || r.branch || r.id
+// Compatibility for package consumers that still import the old name.
+export const deriveHeadline = deriveTitle
 
 export const sessionLabel = (s: Session): string => s.label
-export const sessionHeadline = (s: Session): string => s.headline
+export const sessionTitle = (s: Session): string => s.title
+// Compatibility for older callers; all visible surfaces now resolve through `title`.
+export const sessionHeadline = sessionTitle
 
 // @@@ tmux probe timeout - under load (the incident: load ~30 + swap thrash) a bare `tmux list-sessions` can
 // HANG, and with no bound the whole board assembly hung behind it — the dashboard froze / dropped rows, which
@@ -448,7 +458,113 @@ function writeRecord(rec: SessRec): void {
   if (rec.governed && previousPublic && (previousPublic.status !== nextPublic.status
     || previousPublic.proposal !== nextPublic.proposal || previousPublic.note !== nextPublic.note)) {
     recordStatus(rec.session, nextPublic.status, nextPublic.proposal, nextPublic.note)
+    scheduleWatchNotifications(rec)
+  }
+}
+
+type WatchEntry = { watcher: string; createdAt: string }
+export type SessionWatch = { target: string; createdAt: string }
+const watchPath = (target: string) => sessionArtifactPath(target, 'watchers.json')
+
+function readWatchEntries(target: string): WatchEntry[] {
+  try {
+    const raw = JSON.parse(readFileSync(watchPath(target), 'utf8')) as unknown
+    if (!Array.isArray(raw)) return []
+    const seen = new Set<string>()
+    return raw.flatMap((entry): WatchEntry[] => {
+      if (!entry || typeof entry !== 'object') return []
+      const watcher = (entry as WatchEntry).watcher
+      const createdAt = (entry as WatchEntry).createdAt
+      if (!watcher || typeof watcher !== 'string' || typeof createdAt !== 'string' || seen.has(watcher)) return []
+      seen.add(watcher)
+      return [{ watcher, createdAt }]
+    })
+  } catch { return [] }
+}
+
+function writeWatchEntries(target: string, entries: WatchEntry[]): void {
+  const path = watchPath(target)
+  if (!entries.length) { try { unlinkSync(path) } catch { /* already absent */ }; return }
+  const dir = sessionStoreDir(target)
+  mkdirSync(dir, { recursive: true })
+  const tmp = join(dir, `.watchers.json.${process.pid}.tmp`)
+  writeFileSync(tmp, JSON.stringify(entries, null, 2) + '\n')
+  renameSync(tmp, path)
+}
+
+function managedWatchRecord(id: string): SessRec {
+  const rec = readRecord(id)
+  if (!rec?.governed) throw new ResourceConflict(`session ${id} is not a governed session and cannot participate in a durable watch`)
+  return rec
+}
+
+function watchMessage(target: SessRec): string {
+  const status = target.status === 'awaiting'
+    ? PROPOSAL_STATUS[target.proposal ?? 'nothing']
+    : target.status === 'active' ? 'working' : target.status
+  const note = target.note ? ` — ${target.note}` : ''
+  return `[spex watch] ${target.session} is ${status}${note}`
+}
+
+function scheduleWatchNotifications(target: SessRec): void {
+  const watchers = readWatchEntries(target.session).map((entry) => entry.watcher)
+  if (!watchers.length) return
+  queueMicrotask(() => {
+    for (const watcher of watchers) {
+      void sendText(watcher, watchMessage(target), target.session).then((result) => {
+        if (!result.ok) console.error(`spex session watch: could not deliver ${target.session} state to ${watcher}: ${result.error}`)
+      })
+    }
+  })
+}
+
+export async function subscribeSessionWatch(watcher: string, targets: string[]): Promise<{ watched: string[] }> {
+  managedWatchRecord(watcher)
+  const watched: string[] = []
+  for (const target of [...new Set(targets)]) {
+    if (target === watcher) throw new ResourceConflict('a session cannot watch itself')
+    const targetRecord = managedWatchRecord(target)
+    withRecordLockSync(target, () => {
+      const entries = readWatchEntries(target)
+      if (!entries.some((entry) => entry.watcher === watcher)) {
+        writeWatchEntries(target, [...entries, { watcher, createdAt: new Date().toISOString() }])
+      }
+    })
+    const delivered = await sendText(watcher, watchMessage(targetRecord), target)
+    if (!delivered.ok) throw new ResourceConflict(`watch established but could not queue ${target}'s current state for ${watcher}: ${delivered.error}`)
+    watched.push(target)
+  }
+  return { watched }
+}
+
+export function listSessionWatches(watcher: string): SessionWatch[] {
+  managedWatchRecord(watcher)
+  const watches: SessionWatch[] = []
+  for (const target of listSessionIds()) {
+    const entries = readWatchEntries(target)
+    const active = entries.filter((entry) => {
+      try { return !!readRecord(entry.watcher)?.governed } catch { return false }
+    })
+    if (active.length !== entries.length) writeWatchEntries(target, active)
+    for (const entry of active) if (entry.watcher === watcher) watches.push({ target, createdAt: entry.createdAt })
+  }
+  return watches.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.target.localeCompare(b.target))
+}
+
+export function cancelSessionWatch(watcher: string, targets: string[]): number {
+  managedWatchRecord(watcher)
+  let cancelled = 0
+  for (const target of [...new Set(targets)]) {
+    withRecordLockSync(target, () => {
+      const entries = readWatchEntries(target)
+      const kept = entries.filter((entry) => entry.watcher !== watcher)
+      if (kept.length !== entries.length) {
+        writeWatchEntries(target, kept)
+        cancelled++
+      }
+    })
   }
+  return cancelled
 }
 
 // Share one liveness snapshot rather than spawning tmux for every displayed session.
@@ -662,10 +778,26 @@ async function findWorktree(id: string): Promise<{ path: string; branch: string
   return { path: rec.worktreePath, branch: rec.branch, rec }
 }
 
+// @@@ identity WITHOUT the gates - reviewPayload answers two different questions at once: who is this
+// session (a store read, free) and how does its branch stand against main (ahead count, dirty scan, a
+// merge-tree conflict probe — 646 ms and 8 git children on a far-diverged branch). A consumer that renders
+// no gates strip should not buy the second one. The record already holds the identity half.
+export type ReviewIdentity = { id: string; node: string | null; branch: string | null; label: string }
+export function reviewIdentity(id: string): ReviewIdentity | null {
+  const rec = readRecord(id)
+  if (!rec) return null
+  return {
+    id,
+    node: rec.node,
+    branch: rec.branch,
+    label: deriveLabel({ id, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch }),
+  }
+}
+
 function corruptSession(id: string, entry: { path: string; error: 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 },
+    id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
     parent: null, harness: defaultHarness.id, capabilities: { headless: false }, launcher: null,
     lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
     note: corruptReason(entry), archived: false, prompt: null, promptPreview: null, created: 0,
@@ -680,9 +812,9 @@ export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, act
   const showActivity = lv === 'online'
   const act = showActivity ? activity : null
   const pp = prompt ? oneLinePreview(prompt) : null
-  const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, promptPreview: pp }
+  const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, note: rec.note, promptPreview: pp }
   const harness = harnessById(rec.harness || defaultHarness.id)
-  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: harness.id, capabilities: { headless: harness.headless }, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, archived: rec.archived, archiveHazard: null, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
+  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), title: deriveTitle(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: harness.id, capabilities: { headless: harness.headless }, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, archived: rec.archived, archiveHazard: null, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
 }
 
 export async function renameSession(id: string, name: string): Promise<boolean> {
@@ -1223,6 +1355,28 @@ export function superviseQueue(intervalMs = 3000): void {
   void tick()
 }
 
+let supervisingDelivery = false
+// @@@ superviseDelivery - the RETRY half of [[delivery-queue]]. `sendText` hands over in its own process, which
+// covers the live case; this covers everything that could not be handed over then — a harness mid-restart, a
+// pane in the one state that swallows prompts, a session that was offline when the message arrived. Owned by
+// the serve that serves this project root, so a message owed to a worker is delivered when the worker can take
+// it rather than when it happens to run a tool. A tick with nothing owed is one existsSync per session, and
+// concurrent serves are harmless: the queue's lock, not the process, is what makes a handover exactly-once.
+export function superviseDelivery(intervalMs = 2000): void {
+  if (supervisingDelivery) return
+  supervisingDelivery = true
+  const tick = async () => {
+    try {
+      for (const id of listSessionIds()) {
+        if (!owesDelivery(id)) continue
+        try { await drainSession(id) } catch { /* an adapter that refused stays owed; next tick retries */ }
+      }
+    } catch { /* transient store read; next tick retries */ }
+    setTimeout(tick, intervalMs).unref()
+  }
+  void tick()
+}
+
 type TurnFailureObserverState = {
   fingerprint: string
   subscription: FailureSubscription | null
@@ -1646,6 +1800,23 @@ type SessionCandidateReceiptRead =
 const sessionCandidateReceiptDir = () => join(runtimeRoot(), '.session-create-candidates')
 const sessionCandidateReceiptPath = (id: string) => join(sessionCandidateReceiptDir(), `${id}.json`)
 const sessionCandidateLockId = (path: string, branch: string) => `create-resource-${digest(`${path}\0${branch}`)}`
+// The graph watcher uses this private fence to avoid rebuilding the full board while Git is still
+// registering a session candidate. The receipt is written before `git worktree add` and retired only
+// after publication or bounded cleanup, so the path names exactly the transaction-owned worktree.
+export function pendingSessionCreateWorktreePaths(): Set<string> {
+  const paths = new Set<string>()
+  let entries: import('node:fs').Dirent[]
+  try { entries = readdirSync(sessionCandidateReceiptDir(), { withFileTypes: true }) }
+  catch { return paths }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue
+    try {
+      const value = JSON.parse(readFileSync(join(sessionCandidateReceiptDir(), entry.name), 'utf8')) as Partial<SessionCandidateReceipt>
+      if (typeof value.path === 'string' && value.path && typeof value.stage === 'string') paths.add(resolve(value.path))
+    } catch { /* an in-flight atomic replace is not a candidate path */ }
+  }
+  return paths
+}
 function readSessionCandidateReceipt(id: string): SessionCandidateReceiptRead {
   const path = sessionCandidateReceiptPath(id)
   if (!existsSync(path)) return { kind: 'absent' }
@@ -1834,7 +2005,9 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
       const resourceLock = sessionCandidateLockId(path, branch)
       return await withRecordLock(resourceLock, async () => {
         throwIfCreateAborted(signal, phase)
+        traceSessionCreate(id, requestDigest, phase, 'start', 'candidate-state')
         let before = await sessionCandidateState(root, path, branch, signal)
+        traceSessionCreate(id, requestDigest, phase, 'finish', 'candidate-state')
         let storePresent = existsSync(sessionStoreDir(id))
         const durable = readSessionCandidateReceipt(id)
         if (durable.kind === 'invalid') throw new SessionCreateError('session_create_failed', phase, durable.error, 409)
@@ -1866,7 +2039,12 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
         let published = false
         try {
           gitMutationStarted = true
-          const added = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'worktree', 'add', '-b', branch, path, mainBranch()]))
+          traceSessionCreate(id, requestDigest, phase, 'start', 'worktree-add')
+          const added = await withGitAbortSignal(signal, () => gitTry(
+            ['-C', root, 'worktree', 'add', '-b', branch, path, mainBranch()],
+            { extraEnv: DEFER_FOOTPRINT_REFRESH },
+          ))
+          traceSessionCreate(id, requestDigest, phase, 'finish', 'worktree-add')
           if (added.ok) Object.assign(owned, { path: true, worktree: true, branch: true })
           if (!added.ok || !existsSync(path)) {
             throw new SessionCreateError('session_create_failed', phase, `git worktree add failed: ${added.stderr.trim() || added.failure || 'worktree missing after success'}`, 500)
@@ -1874,7 +2052,9 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
           candidateReceipt = { ...candidateReceipt, stage: 'git-created' }
           writeSessionCandidateReceipt(id, candidateReceipt)
           traceSessionCreate(id, requestDigest, phase, 'finish')
+          traceSessionCreate(id, requestDigest, phase, 'start', 'seed-worktree-host-state')
           seedWorktreeHostState(root, path)
+          traceSessionCreate(id, requestDigest, phase, 'finish', 'seed-worktree-host-state')
 
           let rec: SessRec = {
             session: id, governed: true, worktreePath: path, branch,
@@ -3092,12 +3272,11 @@ export function formatTable(sessions: Session[], color = true): string {
   return [c('1', `SpexCode sessions (${sessions.length})`), header, ...rows, statusLegend(color)].join('\n')
 }
 
-// @@@ sendText - THE APPEND IS THE DELIVERY ([[dispatch]]). The message lands in the target's durable log
-// under its record lock, and success is decided there; only then is the harness adapter poked with the same
-// text, so a live agent sees it in its current turn instead of at its next turn boundary. The poke is
-// best-effort — losing it, having it refused, or replaying it costs nothing, because the line is already the
-// message's copy and the turn-boundary reader picks up whatever the poke did not show. What stays LOUD is only
-// what genuinely cannot be recorded: an unknown session id, or a log that refuses the write.
+// @@@ sendText - THE APPEND ACCEPTS, THE QUEUE OWES ([[dispatch]]). One hold of the record lock records the
+// message in the durable log AND enqueues it ([[delivery-queue]]); success is decided by that write, so a
+// sender learns whether the message was accepted and never whether a socket was reachable. The handover is a
+// separate act: drain the queue into the harness adapter as an ordinary prompt. What stays LOUD is only what
+// genuinely cannot be recorded: an unknown session id, or a log that refuses the write.
 // A RETIRED session (worktree gone) still receives: the record gate governs the lifecycle axis, and a message
 // that cannot reach an agent must at least leave a trace ([[session-timeline]]).
 // (The separate RAW nav-key channel keeps its own `tmux send-keys` path — see rawKey.)
@@ -3105,37 +3284,44 @@ export async function sendText(id: string, text: string, from?: string, opts: {
   if (!text) return { ok: false, error: 'empty prompt — nothing to dispatch' }
   const rec = readRecord(id)
   if (!rec) return { ok: false, error: `no session record for ${id} — prompt NOT delivered` }
+  // Composed at ACCEPT time, once: the log keeps the raw conversational text plus the effective reply channel,
+  // the queue keeps the transport form. Composing again at handover would let a later send change the hints on
+  // a message that was already accepted.
   const prompt = await composeSessionPrompt(text, rec, { from, replyVia: opts.replyVia })
-  let sent: { mid: string }
   try {
-    // The lock covers the append alone. Codex's native turn can synchronously run hooks that write this same
-    // record, so holding it across the adapter poke below would deadlock the app-server's confirmation.
-    sent = await withRecordLock(id, async () => appendSent(id, text, from ?? null, prompt.replyVia))
+    await withRecordLock(id, async () => {
+      const appended = appendSent(id, text, from ?? null, prompt.replyVia)
+      enqueue(id, { mid: appended.mid, text: prompt.text, from: from ?? null })
+    })
   } catch (error) {
     return { ok: false, error: `could not append the message to session ${id}'s log: ${error instanceof Error ? error.message : String(error)} — prompt NOT delivered` }
   }
-  const h = harnessById(rec.harness || defaultHarness.id)
-  // Awaited, not fire-and-forget: `spex session send` is a short-lived process that would exit before an
-  // unawaited poke ever reached the socket, costing every CLI send its same-turn arrival. Its result never
-  // advances the inbox: a write cannot prove the target parsed it, so only the target's reader consumes the
-  // durable line.
-  await pokeAdapter(h, rec, prompt.text, sent.mid)
+  // Awaited, not fire-and-forget: an unawaited insert can lose its race with a short-lived caller's exit,
+  // costing that send its same-turn arrival. Draining HERE rather than leaving it to the sweep is what puts
+  // the text in a live agent's current turn instead of up to one tick later.
+  await drainSession(id)
   return { ok: true }
 }
 
-// The courtesy kick. Carries `mid` as the adapter's native message marker, so an adapter that replays or
-// duplicates it stays harmless. Never throws and never reports: a poke has no outcome the caller can act on.
-async function pokeAdapter(h: Harness, rec: SessRec, text: string, mid: string): Promise<void> {
-  // the pane guard ([[harness-adapter]] deliveryBlockedBy): the ONE pane state where the harness swallows a
-  // prompt its channel confirms (claude's sessions panel), checkable only from the pane. It no longer refuses
-  // the send — the message is already delivered — it only skips a kick known to be swallowed.
-  if (h.deliveryBlockedBy) {
-    try {
-      if (h.deliveryBlockedBy(await tmux(['capture-pane', '-p', '-t', rec.session], TMUX_PROBE_TIMEOUT_MS))) return
-    } catch { /* no pane to consult — let the poke itself decide */ }
-  }
-  try { await h.deliver({ ...rec, runtimeDir: runtimeRoot(), mid }, text) }
-  catch { /* the unread timeline line remains the delivery */ }
+// @@@ drainSession - hand over what this session is owed, as ordinary prompts. Safe to call from anywhere and
+// at any time: the queue's own lock serializes concurrent passes, and an empty queue costs one existsSync.
+// The retry sweep in `serve` calls this for the sessions whose queues an earlier pass could not empty.
+export async function drainSession(id: string): Promise<void> {
+  if (!owesDelivery(id)) return
+  const rec = readRecord(id)
+  if (!rec) return
+  const h = harnessById(rec.harness || defaultHarness.id)
+  await drain(id, async (msg) => {
+    // the pane guard ([[harness-adapter]] deliveryBlockedBy): the ONE pane state where the harness swallows a
+    // prompt its channel confirms (claude's sessions panel), checkable only from the pane. Treated as a REFUSAL
+    // rather than a skip — the message stays owed and the sweep hands it over once the pane leaves that state.
+    if (h.deliveryBlockedBy) {
+      try {
+        if (h.deliveryBlockedBy(await tmux(['capture-pane', '-p', '-t', rec.session], TMUX_PROBE_TIMEOUT_MS))) return false
+      } catch { /* no pane to consult — let the insert itself decide */ }
+    }
+    return (await h.deliver({ ...rec, runtimeDir: runtimeRoot(), mid: msg.mid }, msg.text)).ok
+  })
 }
 
 // Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness without a

package/spec-cli/src/uninstall.ts

@@ -7,6 +7,7 @@ import { runtimeRoot, readConfig, mainCheckout } from './layout.js'
 import { resolveHarnessTargets } from './harness-select.js'
 import { loadSkillConfig, loadAgentConfig } from './specs.js'
 import { dematerialize } from './materialize.js'
+import { gitBinary } from './git.js'
 
 // the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
 const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex', '.zcode'] as const
@@ -71,7 +72,7 @@ function pluginLedgerHosts(store: string): string[] {
 // resolve the repo's shared git hooks dir (the common dir's hooks/), or null when <dir> isn't a git repo.
 function hooksDir(proj: string): string | null {
   try {
-    const common = execFileSync('git', ['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    const common = execFileSync(gitBinary(process.env), ['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim()