spexcode 0.5.9 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/cli.ts

@@ -660,7 +660,7 @@ if (cmd === 'serve') {
   } else if (sub === 'wait') {
     const selectors = positionals(4)
     const kit = await followKit(selectors, 'spex session wait')
-    const named = selectors.join(' ') || 'your inbox'
+    const named = selectors.join(' ') || 'your own log'
     // point-of-use turn-freeze warning ([[session-follow]]): a managed agent that runs this wait in the FOREGROUND
     // freezes its whole turn until the target produces an edge — a warning that used to live only in help
     // prose, now said where it matters. Foreground vs background is invisible from here, so the hint prints
@@ -1043,28 +1043,6 @@ if (cmd === 'serve') {
     const st = process.argv[4] as any
     const ok = mark(() => s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess }))
     console.log(ok.ok ? `state -> ${st}${noteEcho(flag('note'))}` : ok.reason ?? noRecord())
-  } else if (sub === 'session-cursor') {
-    // the turn-boundary mail reader advances its own inbox cursor here ([[session-cursors]]) — the same
-    // one-writer discipline as session-state: shell reads the file, it never rewrites it, so a follower's
-    // entries in the same file cannot be clobbered by a partial shell write.
-    const to = Number(flag('to'))
-    const sess = flag('session')
-    if (process.argv[4] !== 'inbox' || !sess || !Number.isFinite(to)) {
-      console.error('usage: spex internal session-cursor inbox --session <id> --to <event-index>')
-      process.exit(2)
-    }
-    const { advanceInbox, inboxCursor } = await import('./session-cursors.js')
-    const { readAliasedRawRecord } = await import('./layout.js')
-    // the hook may address a codex THREAD id; the cursor file is keyed by the record id, so resolve the alias
-    // through the one seam that owns that rule.
-    const record = readAliasedRawRecord(sess)
-    if (!record) console.log('noop (no session record)')
-    else {
-      advanceInbox(record.session_id, to)
-      // report where the cursor ACTUALLY is: advancing is monotonic, so a lower offer is ignored, and
-      // echoing the request back would confirm a move that did not happen.
-      console.log(`inbox -> ${inboxCursor(record.session_id)}`)
-    }
   } else if (sub === 'session-fail') {
     // StopFailure is one native source for the shared active-only turn-failure CAS. A declaration or explicit
     // stop that landed first is authoritative, just as it is for Codex notifications and headless exits.

package/spec-cli/src/delivery-queue.ts

@@ -0,0 +1,107 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
+
+// @@@ delivery-queue - what a session still OWES its agent. The log ([[session-timeline]]) is the record and
+// grows forever; this is the debt and is consumed, so it lives in its own small file whose resting state is
+// EMPTY. Nothing here reads the log: an entry carries the text it will hand over, so history could be trimmed
+// or archived without changing what is owed. A session that predates this mechanism owes nothing, because a
+// queue is only ever filled by an enqueue — which is why no backlog migration exists.
+
+export type PendingMessage = { mid: string; text: string; from: string | null }
+
+const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
+
+// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
+// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
+// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
+// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
+// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
+const lockRoot = (): string => join(runtimeRoot(), '.delivery-locks')
+const lockPath = (id: string): string => join(lockRoot(), `${id}.lock`)
+
+const pause = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+async function acquire(id: string, timeoutMs: number): Promise<(() => void) | null> {
+  mkdirSync(lockRoot(), { recursive: true })
+  const path = lockPath(id), deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      const fd = openSync(path, 'wx')
+      writeSync(fd, String(process.pid))
+      closeSync(fd)
+      return () => { try { unlinkSync(path) } catch { /* a liveness reclaim already removed it */ } }
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      let owner = 0
+      try { owner = Number(readFileSync(path, 'utf8').trim()) || 0 } catch { /* race with creator/releaser */ }
+      if (owner && owner !== process.pid) {
+        try { process.kill(owner, 0) } catch { try { unlinkSync(path) } catch { /* race */ }; continue }
+      }
+      // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
+      // and the retry sweep will come back. Declining is not a lost message.
+      if (Date.now() >= deadline) return null
+      await pause(25)
+    }
+  }
+}
+
+function read(id: string): PendingMessage[] {
+  try {
+    const raw = JSON.parse(readFileSync(queuePath(id), 'utf8')) as unknown
+    if (!Array.isArray(raw)) return []
+    return raw.filter((m): m is PendingMessage =>
+      !!m && typeof m === 'object'
+      && typeof (m as PendingMessage).mid === 'string'
+      && typeof (m as PendingMessage).text === 'string')
+  } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
+}
+
+// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
+// one existsSync on the sweep's hot path.
+function write(id: string, msgs: PendingMessage[]): void {
+  const path = queuePath(id)
+  if (!msgs.length) { try { unlinkSync(path) } catch { /* already gone */ } ; return }
+  mkdirSync(sessionStoreDir(id), { recursive: true })
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n')
+  renameSync(tmp, path)
+}
+
+// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
+// both, and the record is written first, so a crash between them leaves a message visible but undelivered —
+// never delivered but unrecorded.
+export function enqueue(id: string, msg: PendingMessage): void {
+  write(id, [...read(id), msg])
+}
+
+export const pendingMessages = (id: string): PendingMessage[] => read(id)
+
+export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
+
+// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
+// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
+// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
+// one. Returns how many were handed over and how many are still owed.
+export async function drain(
+  id: string,
+  insert: (msg: PendingMessage) => Promise<boolean>,
+  timeoutMs = 5_000,
+): Promise<{ delivered: number; remaining: number }> {
+  const release = await acquire(id, timeoutMs)
+  if (!release) return { delivered: 0, remaining: read(id).length }
+  let delivered = 0
+  try {
+    for (;;) {
+      const queued = read(id)
+      if (!queued.length) return { delivered, remaining: 0 }
+      let ok = false
+      try { ok = await insert(queued[0]) } catch { ok = false }
+      if (!ok) return { delivered, remaining: queued.length }
+      // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
+      // stale snapshot minus the head would silently drop it.
+      write(id, read(id).filter((m) => m.mid !== queued[0].mid))
+      delivered++
+    }
+  } finally { release() }
+}

package/spec-cli/src/harness.ts

@@ -282,7 +282,7 @@ export interface Harness {
   // write one idempotent rendezvous reply; Codex uses JSON-RPC on the same app-server WebSocket the
   // visible TUI uses — it reads the thread live and either `turn/steer`s the message INTO an in-progress turn
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
-  // `ok=false` leaves the durable timeline line for the turn-boundary reader.
+  // `ok=false` leaves the message OWED on the session's delivery queue, for a later pass to hand over.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
   // Observe native turn failures that this harness does not expose as a lifecycle hook. The adapter owns the
   // transport subscription; sessions owns observer reconciliation and the active-only lifecycle CAS.

package/spec-cli/src/help.ts

@@ -47,7 +47,7 @@ session to that node. --prompt-file <path>|- carries a long prompt without shell
     watch: ['spex session watch [SEL…] [--as NAME] [--idle] [--interval N=1]',
       'Streams lifecycle transitions and blocks until killed; `session wait` is the one-shot alternative.', ['selector']],
     wait: ['spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]',
-      `EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own inbox, and exits 0 on
+      `EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
 the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
 status into an actionable one (stdout = the observed path, e.g. working→review; read the LAST
 token as the status reached), or a message arriving for you (stdout = message). The arrival

package/spec-cli/src/index.ts

@@ -18,7 +18,7 @@ import { getBoardJson } from './graphCache.js'
 import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
 import { cockpitReview } from './cockpit.js'
-import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, captureSessionResult, sessionPrompt, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
+import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, captureSessionResult, sessionPrompt, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, superviseDelivery, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
 import { readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
@@ -700,6 +700,7 @@ injectWebSocket(server)
 superviseBridges()   // restore visible helpers after failure; their viewer subscriptions survive replacement
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
 superviseTurnFailures() // reconcile adapter-owned native failure subscriptions across backend replacement
+superviseDelivery()  // hand over messages an earlier pass could not ([[delivery-queue]]): the retry half of dispatch
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 
 let graphWatchersClosed = false

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'
@@ -1223,6 +1224,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
@@ -3092,12 +3115,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 +3127,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/templates/spec/project/.plugins/core/mark-active/mark-active.sh

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# @@@ mark-active - the SINGLE turn-boundary hook, wired to BOTH UserPromptSubmit and PreToolUse. It does two
-# jobs, both keyed off the session's global record dir: it keeps the declared FRESHNESS state honest, and it
-# delivers the session's unread MAIL.
+# @@@ mark-active - the SINGLE turn-boundary hook, wired to BOTH UserPromptSubmit and PreToolUse. It has ONE
+# job, keyed off the session's global record dir: keep the declared FRESHNESS state honest. It carries no
+# conversation — a message reaches this agent as an ordinary prompt through the harness adapter
+# ([[delivery-queue]]), which is the only way anything enters a turn. A hook that also injected mail handed
+# every message over twice and made the agent's context depend on which of two paths won a race.
 # Freshness branches on ONE structured signal read straight from the hook payload (stdin JSON), so the state is
 # HARD — never text-sniffed from the TUI:
 #   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
@@ -36,44 +38,6 @@ rec="$sdir/session.json"
 # board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
 grep -q '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
 
-# @@@ the mail read - this hook is the ONE reader of the session's inbox ([[session-timeline]]): a message is
-# delivered by being appended to timeline.ndjson, and the agent finds it here, by mechanism, at a turn
-# boundary — never by remembering to run a command. `cursors.json` names how far this session has been shown
-# ([[session-cursors]]); everything past it is unread, the `sent` lines among it are printed as context, and
-# the cursor advances past ALL of it (a session's own status lines are not mail, but they are consumed, so
-# they can never come back as one).
-# Pure bash builtins, no forks: the common case is "no new lines", and the fast path must not cost a spawn.
-# The read is generous where it cannot be exact — an unparseable cursor reads as 0, which re-shows a message
-# rather than skipping one.
-mail() {
-  local tl="$sdir/timeline.ndjson" cur="$sdir/cursors.json" pos=0 i=0 line body unread=""
-  [ -f "$tl" ] || return 0
-  if [ -f "$cur" ]; then
-    while IFS= read -r line; do
-      case "$line" in
-        *'"inbox":'*) line="${line#*\"inbox\":}"; line="${line%%,*}"; line="${line// /}"; line="${line//$'\t'/}"
-                      case "$line" in ''|*[!0-9]*) ;; *) pos=$line ;; esac; break ;;
-      esac
-    done < "$cur"
-  fi
-  while IFS= read -r line; do
-    if [ "$i" -ge "$pos" ]; then
-      case "$line" in
-        *'"kind":"sent"'*) body=$(hp_field "$line" text)
-                           [ -n "$body" ] && unread="$unread$body"$'\n\n' ;;
-      esac
-    fi
-    i=$((i + 1))
-  done < "$tl"
-  # No mail → no cursor write. Unread STATUS lines alone leave the cursor where it is: they print nothing, so
-  # advancing past them would buy nothing and cost a spawn on almost every turn. The next scan re-reads them
-  # and still prints nothing.
-  [ -n "$unread" ] || return 0
-  printf 'Messages addressed to you (delivered to your session log while you were working):\n\n%s' "$unread"
-  ${SPEX:-spex} internal session-cursor inbox --session "$sid" --to "$i" >/dev/null 2>&1
-}
-mail
-
 # does FIELD's line hold exactly VALUE? The record is written one-field-per-line by the single writer
 # (sessions.ts writeRecord), so a whole-line match is exact — and, unlike a value regex, it cannot be fooled
 # by an escaped quote inside a neighbouring note.

package/spec-cli/templates/spec/project/.plugins/core/mark-active/spec.md

@@ -17,6 +17,6 @@ The one activity that does NOT count as the session acting is an IN-PROCESS SUBA
 
 It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), but it never edits that file itself: it READS it in pure shell (whole-line matches, the hot path stays jq-free) and hands every write to `spex internal session-state`, the one structured writer the CLI declarations use — an asking note is arbitrary prose, and a shell that substitutes prose into existing JSON eventually writes a record nothing can parse.
 
-This hook is also the session's MAIL READER, and that is the same job seen from the other side: a message is delivered by being appended to the session's log (session-timeline), and a turn boundary is exactly when the agent can be shown one. It reads the lines past its own inbox cursor (session-cursors), prints the message bodies so the harness injects them as context, and advances the cursor through `spex internal session-cursor`. So an agent finds its unread mail by mechanism, never by remembering to run a command — identical for a dashboard-launched and a self-launched agent. The scan is pure builtins and writes nothing when there is no mail, so the every-tool-call case still costs no spawn.
+This hook carries no conversation. A message addressed to the session reaches its agent as an ordinary prompt through the harness adapter (delivery-queue), which is the only way anything enters a turn, so an inter-agent message is indistinguishable from a human one at the point of arrival. A hook that also injected mail delivered every message a second time and made the agent's context depend on which of two paths won a race; a freshness signal reports a fact about the session and hands nothing over.
 
 This is the freshness half of the [[core]] discipline: it keeps the board honest about whether a session is working, waiting, or asking, so the gates and the dashboard read a true present state rather than a stale one.