spexcode 0.6.1 → 0.6.2

package/spec-cli/src/sessions.ts

@@ -6,16 +6,18 @@ import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mk
 import { join, dirname, relative, isAbsolute, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { seedWorktreeHostState } from './worktree-sources.js'
-import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, withGitAbortSignal, type ReviewDiffFile } from './git.js'
+import { git, gitA, gitTry, isGitObjectId, repoRoot, mergeBaseDiff, mergeConflicts, withGitAbortSignal, type ReviewDiffFile } from './git.js'
 import { loadConfig, loadSpecs, loadSpecsLite, type ConfigPreset, type SpecLite } from './specs.js'
 import { adapterLoadedReferenceState, defaultHarness, HARNESSES, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock, type Harness, type HarnessLaunchReadinessFence, type TurnFailure, type FailureSubscription, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 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 { readSessionFiles } from './session-files.js'
+import { readSessionWebs, type SessionWeb } from './session-web.js'
+import { appendSent, recordStatus, lastHumanSendVia, sentDispatchReceipt, settleSentDispatch, type SentDispatchReceipt, type SentDispatchState } from './session-timeline.js'
+import { drain, enqueue, ensurePendingWhileLocked, owesDelivery, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, type PendingMessage } from './delivery-queue.js'
 import { stripRefSigil } from './mentions.js'
 import { shQuote } from './sh.js'
-import { assertSessionStopSafe, ResourceConflict } from './host-resources.js'
+import { assertSessionOwnerSafe, assertSessionStopSafe, ResourceConflict } from './host-resources.js'
 import { processStartToken } from './process-identity.js'
 import { bindCodexGeneration, codexGenerationBindingForSession, commitCodexGenerationRegistration, prepareCodexGenerationClose, prepareCodexGenerationRegistration, readCodexGenerationLedger } from './codex-runtime-generations.js'
 
@@ -84,6 +86,40 @@ export type Session = {
   archiveHazard?: string | null // explicit legacy/invariant violation; never hidden as a clean archive
   prompt: string | null; promptPreview: string | null; created: number; activity: string | null
   sortKey: number | null   // manual drag-reorder override ([[session-reorder]]); null = sort by `created`
+  files?: string[]         // live posted paths ([[files]]), read from the session store with the rest of the projection
+  web?: SessionWeb[]       // live posted loopback services ([[web]]), read from the session store with the rest of the projection
+}
+
+// HTTP carries no authenticated session identity. A CLI may report its environment id, but that remains
+// evidence supplied by the caller rather than authority over the target or a fact about who performed close.
+export type CloseSource = { kind: 'unverified-session-claim'; id: string } | { kind: 'user' }
+
+function normalizeCloseSource(raw: unknown): CloseSource {
+  if (raw == null) return { kind: 'user' }
+  if (!raw || typeof raw !== 'object') throw new ResourceConflict('refusing session close: source must be user or an unverified session claim')
+  const source = raw as { kind?: unknown; id?: unknown }
+  if (source.kind === 'user') return { kind: 'user' }
+  if (source.kind === 'unverified-session-claim' && typeof source.id === 'string' && source.id.trim())
+    return { kind: 'unverified-session-claim', id: source.id.trim() }
+  throw new ResourceConflict('refusing session close: source must be user or an unverified session claim')
+}
+
+function appendCloseLedger(id: string, rec: SessRec, source: CloseSource): void {
+  const path = join(runtimeRoot(), 'session-close-ledger.ndjson')
+  const event = {
+    version: 1,
+    action: 'close-authorized',
+    at: new Date().toISOString(),
+    source,
+    target: {
+      id,
+      harness: rec.harness,
+      thread: rec.harnessSessionId,
+      worktree: rec.worktreePath,
+      branch: rec.branch,
+    },
+  }
+  appendFileSync(path, `${JSON.stringify(event)}\n`)
 }
 
 function storeDir(id: string): string { const d = sessionStoreDir(id); mkdirSync(d, { recursive: true }); return d }
@@ -139,6 +175,9 @@ export const sessionHeadline = sessionTitle
 // execFile SIGKILLs the child and rejects with `killed:true`, which liveSnapshot tells apart from a clean
 // "no server" exit (see probeTimedOut) so a timeout renders `unknown`, not a false `offline`.
 const TMUX_PROBE_TIMEOUT_MS = 4000
+// A destructive close already names one target, so it can afford the longer bounded probe without making
+// every dashboard refresh wait behind an overloaded tmux server.
+const TARGET_PROBE_TIMEOUT_MS = 15000
 async function tmux(args: string[], timeoutMs?: number): Promise<string> {
   const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args], { encoding: 'utf8', ...(timeoutMs ? { timeout: timeoutMs, killSignal: 'SIGKILL' as const } : {}) })
   return stdout
@@ -172,6 +211,7 @@ export type SessRec = {
   launchOwner: string | null // stable public-backend authority while queued; null for active/legacy records
   createRequestId?: string | null // digest of the public Idempotency-Key; binds retry without storing the bearer
   createPayloadHash?: string | null // exact normalized create payload bound to createRequestId
+  base?: string | null   // explicit fork point the creator pinned; absent/null = the auto-detected source-of-truth branch
   launchReadinessPending?: LaunchReadinessPending | null // internal resume candidate; every public reader projects `original` until one final publish
 }
 type LaunchReadinessOriginal = Pick<SessRec, 'status' | 'proposal' | 'note' | 'stopped' | 'archived' | 'coldProof' | 'adapterRecovery'>
@@ -299,10 +339,11 @@ async function withRecordLock<T>(id: string, body: () => Promise<T>, signal?: Ab
   const release = await acquireRecordLock(id, 30_000, signal)
   try { return await body() } finally { release() }
 }
-function withRecordLockSync<T>(id: string, body: () => T): T {
+export function withSessionRecordLockSync<T>(id: string, body: () => T): T {
   const release = acquireRecordLockSync(id)
   try { return body() } finally { release() }
 }
+const withRecordLockSync = withSessionRecordLockSync
 function tryRecordLockSync(id: string): (() => void) | null {
   mkdirSync(recordLockRoot(), { recursive: true })
   const path = recordLockPath(id)
@@ -366,6 +407,7 @@ export function fromRaw(raw: RawRecord & { launch_owner?: string }): SessRec {
     launchOwner: launchOwner || null,
     createRequestId: raw.create_request_id || null,
     createPayloadHash: raw.create_payload_hash || null,
+    base: raw.base || null,             // records written before pinned bases → null → the source-of-truth branch
     launchReadinessPending: pendingRaw ? {
       version: 1,
       startedAt: (raw.launch_readiness_pending as { startedAt: number }).startedAt,
@@ -433,6 +475,9 @@ function writeRecord(rec: SessRec): void {
     launch_owner: rec.status === 'queued' ? rec.launchOwner ?? '' : '',
     create_request_id: rec.createRequestId ?? '',
     create_payload_hash: rec.createPayloadHash ?? '',
+    // Written only when the creator pinned one: an unpinned record keeps its exact legacy bytes, so a
+    // restore-the-frozen-record path stays byte-identical instead of silently gaining a key.
+    ...(rec.base ? { base: rec.base } : {}),
     launch_readiness_pending: rec.launchReadinessPending ? {
       version: 1,
       startedAt: rec.launchReadinessPending.startedAt,
@@ -567,22 +612,107 @@ export function cancelSessionWatch(watcher: string, targets: string[]): number {
   return cancelled
 }
 
+export type SessionReparentResult = { children: string[]; parent: string; notified: string[] }
+
+async function withRecordLocks<T>(ids: string[], body: () => Promise<T>, index = 0): Promise<T> {
+  if (index >= ids.length) return body()
+  return withRecordLock(ids[index], () => withRecordLocks(ids, body, index + 1))
+}
+
+function assertReparentable(children: string[], parent: string, records: Map<string, SessRec>): void {
+  if (!children.length) throw new ResourceConflict('reparent needs at least one child session')
+  managedWatchRecord(parent)
+  for (const id of children) {
+    const child = records.get(id)
+    if (!child?.governed) throw new ResourceConflict(`session ${id} is not a governed child session`)
+    if (id === parent) throw new ResourceConflict('a session cannot be its own parent')
+  }
+  const childIds = new Set(children)
+  const seen = new Set<string>()
+  for (let current: string | null = parent; current; ) {
+    if (childIds.has(current)) throw new ResourceConflict(`reparent would create a parent cycle through ${current}`)
+    if (seen.has(current)) throw new ResourceConflict(`cannot reparent through malformed parent cycle at ${current}`)
+    seen.add(current)
+    current = readRecord(current)?.parent ?? null
+  }
+}
+
+export async function reparentSessionRecords(rawChildren: string[], parent: string): Promise<SessionReparentResult> {
+  const children = [...new Set(rawChildren)].sort()
+  if (!parent) throw new ResourceConflict('reparent needs a destination parent session')
+  const notify: SessRec[] = []
+  await withRecordLock('session-reparent-transaction', async () => {
+    // Read former supervisors only after the transaction fence: a concurrent reparent may change exactly
+    // this relation, and its real sender lock is part of the next transaction's outgoing-message boundary.
+    const before = new Map(children.map((id) => [id, managedWatchRecord(id)]))
+    assertReparentable(children, parent, before)
+    const formerParents = [...new Set([...before.values()].flatMap((record) => record.parent ? [record.parent] : []))]
+    await withRecordLocks([...children, ...formerParents].sort(), () => withDeliveryLocks(children, async () => {
+      const current = new Map(children.map((id) => [id, managedWatchRecord(id)]))
+      assertReparentable(children, parent, current)
+      const snapshots = children.map((id) => ({ id, record: current.get(id)!, watchers: readWatchEntries(id), pending: pendingSnapshot(id) }))
+      try {
+        for (const snapshot of snapshots) {
+          const { record, watchers } = snapshot
+          const hadNewParent = watchers.some((entry) => entry.watcher === parent)
+          const retainedNewParent = watchers.find((entry) => entry.watcher === parent)
+          const nextWatchers = watchers.filter((entry) => entry.watcher !== record.parent && entry.watcher !== parent)
+          nextWatchers.push(retainedNewParent ?? { watcher: parent, createdAt: new Date().toISOString() })
+          writeWatchEntries(snapshot.id, nextWatchers)
+          if (record.parent !== parent) writeRecord({ ...record, parent })
+          if (record.parent !== parent || !hadNewParent) notify.push({ ...record, parent })
+        }
+        for (const snapshot of snapshots) {
+          if (snapshot.record.parent && snapshot.record.parent !== parent)
+            revokePendingFromWhileLocked(snapshot.id, snapshot.record.parent)
+        }
+      } catch (error) {
+        let rollbackFailure: unknown = null
+        for (const snapshot of [...snapshots].reverse()) {
+          try {
+            replacePendingWhileLocked(snapshot.id, snapshot.pending)
+            writeWatchEntries(snapshot.id, snapshot.watchers)
+            writeRecord(snapshot.record)
+          } catch (rollback) { rollbackFailure ??= rollback }
+        }
+        const detail = error instanceof Error ? error.message : String(error)
+        const rollbackDetail = rollbackFailure instanceof Error ? `; rollback also failed: ${rollbackFailure.message}` : ''
+        throw new ResourceConflict(`reparent did not commit: ${detail}${rollbackDetail}`)
+      }
+    }))
+  })
+  for (const child of notify) {
+    const delivered = await sendText(parent, watchMessage(child), child.session)
+    if (!delivered.ok) throw new ResourceConflict(`reparent committed but could not queue ${child.session}'s current state for ${parent}: ${delivered.error}`)
+  }
+  return { children, parent, notified: notify.map((child) => child.session) }
+}
+
 // Share one liveness snapshot rather than spawning tmux for every displayed session.
 export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; titles: Map<string, string>; sockets: Set<string>; unproven: Set<string> }
 
-// First pane per session wins; split only twice so titles may contain tabs.
+// tmux rewrites CONTROL characters in a format string before printing them — 3.6a turns both a tab and a raw
+// 0x1f into `_`, while 3.4 turns a raw 0x1f into the printable escape `\037`. So the field separator is ASKED
+// FOR as that printable text, which every supported version passes through untouched, and the format is built
+// from the same constant the parser splits on: the two can no longer disagree about what tmux actually emits.
+const TMUX_PANE_SEPARATOR = '\\037'
+export const TMUX_PANE_FORMAT = `#{session_name}${TMUX_PANE_SEPARATOR}#{pane_pid}${TMUX_PANE_SEPARATOR}#{pane_title}`
+
+// First pane per session wins; split only twice so titles may contain the field separator.
 export function parseLivePanes(out: string): Map<string, { panePid?: number; title?: string }> {
   const m = new Map<string, { panePid?: number; title?: string }>()
   for (const line of out.split('\n')) {
     if (!line) continue
-    const t1 = line.indexOf('\t')
+    // Accept the former tab shape for callers replaying old snapshots; tmux itself emits TMUX_PANE_SEPARATOR.
+    const separator = line.includes(TMUX_PANE_SEPARATOR) ? TMUX_PANE_SEPARATOR : '\t'
+    const t1 = line.indexOf(separator)
     const name = (t1 < 0 ? line : line.slice(0, t1)).trim()
     if (!name || m.has(name)) continue   // first pane per session wins
     if (t1 < 0) { m.set(name, {}); continue }
-    const rest = line.slice(t1 + 1)
-    const t2 = rest.indexOf('\t')
+    const rest = line.slice(t1 + separator.length)
+    const t2 = rest.indexOf(separator)
     const pid = Number((t2 < 0 ? rest : rest.slice(0, t2)).trim())
-    const title = t2 < 0 ? '' : rest.slice(t2 + 1)
+    const title = t2 < 0 ? '' : rest.slice(t2 + separator.length)
     m.set(name, { panePid: Number.isFinite(pid) && pid > 0 ? pid : undefined, title: title || undefined })
   }
   return m
@@ -613,13 +743,17 @@ export function needsCodexProcScan(windowed: { harness: string; hasPid: boolean
   return windowed.some((w) => (w.harness || 'claude') === 'codex' && !w.hasPid)
 }
 
-async function liveSnapshot(): Promise<LiveSnap> {
+async function liveSnapshot(targetId?: string): Promise<LiveSnap> {
   const windows = new Map<string, PaneProbe>()
   const titles = new Map<string, string>()
   let out: string
   try {
     // ONE merged spawn replaces the old two (list-sessions + list-panes): window presence + pane pid + title.
-    out = await tmux(['list-panes', '-a', '-F', '#{session_name}\t#{pane_pid}\t#{pane_title}'], TMUX_PROBE_TIMEOUT_MS)
+    // A target-scoped close probe avoids unrelated panes turning a safe close into a global timeout.
+    const args = targetId
+      ? ['list-panes', '-t', targetId, '-F', TMUX_PANE_FORMAT]
+      : ['list-panes', '-a', '-F', TMUX_PANE_FORMAT]
+    out = await tmux(args, targetId ? TARGET_PROBE_TIMEOUT_MS : TMUX_PROBE_TIMEOUT_MS)
   } catch (e) {
     // a TIMEOUT/kill is a probe FAILURE (we can't tell who's alive → unknown, never a false graveyard). A clean
     // non-zero exit ("no server running" — genuinely zero sessions) is authoritative → the empty map = offline.
@@ -647,7 +781,12 @@ async function liveSnapshot(): Promise<LiveSnap> {
   // The tri-state matters: 'unproven' (timeout/EAGAIN — a wedged or thrashed but possibly-alive listener) lands
   // in `unproven`, never silently not-live, so liveness() renders `unknown` not a false `offline` (issue #40).
   const ids = [...windows.keys()]
-  const listening = await Promise.all(ids.map((id) => rendezvousListening(id)))
+  // A burst of simultaneous Unix-socket connects can fill a Claude listener's accept backlog on macOS and
+  // turn every healthy socket into `unproven`. Keep the probe bounded while preserving the tri-state result.
+  const listening: Awaited<ReturnType<typeof rendezvousListening>>[] = []
+  for (let start = 0; start < ids.length; start += 2) {
+    listening.push(...await Promise.all(ids.slice(start, start + 2).map((id) => rendezvousListening(id))))
+  }
   const sockets = new Set<string>()
   const unproven = new Set<string>()
   ids.forEach((id, i) => {
@@ -801,7 +940,7 @@ function corruptSession(id: string, entry: { path: string; error: string }): Ses
     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,
-    activity: null, sortKey: null, archiveHazard: null,
+    activity: null, sortKey: null, archiveHazard: null, files: [], web: [],
   }
 }
 
@@ -814,7 +953,7 @@ export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, act
   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, 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), 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 }
+  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, files: readSessionFiles(rec.session), web: readSessionWebs(rec.session) }
 }
 
 export async function renameSession(id: string, name: string): Promise<boolean> {
@@ -846,6 +985,14 @@ export async function sessionPrompt(id: string): Promise<string | null> {
 // Preserve rows through a transient record-read failure; prune after the store entry disappears.
 const lastKnownSession = new Map<string, Session>()
 
+// A BOARD row carries the launch ask only as its one-line preview. The full text is served by the
+// id-addressed record detail, which reads the stored prompt itself and overrides this field — so the list
+// never had a reader for it. Shipping it made the body grow with total ask LENGTH instead of session count
+// (measured on the adopter-a board: 2192 KB of a 2218 KB default body, 27 KB of which was actual board data)
+// and pinned the same bytes in `lastKnownSession` for the life of the process. The CREATE response keeps the
+// full text: it is a receipt for one ask the caller just made, not a row in a list of many.
+const boardRow = (s: Session): Session => { s.prompt = null; return s }
+
 export async function listSessions(includeArchived = false): Promise<Session[]> {
   // ONE store enumeration + ONE tmux snapshot (windows + pane pids + titles, merged) for the whole list, then
   // every session reconciles by a pure set lookup + one existsSync — no per-session tmux spawn.
@@ -893,7 +1040,7 @@ export async function listSessions(includeArchived = false): Promise<Session[]>
     // A forced public liveness comes only from the shared record projection. Do not let live process/thread
     // evidence punch through it (including archive hazard repair).
     if (entry.kind === 'ok' && entry.liveness === 'offline') {
-      const pending = toSession(rec, 'offline', 'offline')
+      const pending = boardRow(toSession(rec, 'offline', 'offline'))
       lastKnownSession.set(id, pending)
       return pending
     }
@@ -917,7 +1064,7 @@ export async function listSessions(includeArchived = false): Promise<Session[]>
     const cleanCold = rec.archived && !changedDuringCensus.has(id) && hasValidColdProof(rec) && physical === 'offline' && (!residentRequired || resident?.healthy === true)
     const projected = rec.archived && !cleanCold ? { ...rec, archived: false, stopped: false } : rec
     const projectedLv = projected === rec ? liveness(rec, snap) : physical!
-    const s = toSession(projected, reconcile(projected, snap), projectedLv, activity)
+    const s = boardRow(toSession(projected, reconcile(projected, snap), projectedLv, activity))
     if (projected !== rec) s.archiveHazard = changedDuringCensus.has(id)
       ? 'archived runtime hazard: record changed while adapter residency was being reconciled; retry exact archive'
       : hasValidColdProof(rec)
@@ -956,10 +1103,16 @@ function guardSession(id: string, primary: () => Session | null, degraded: () =>
 export type ApiBaseSource = 'flag' | 'worker-env' | 'record' | 'env-fallback' | 'default'
 export type ApiBaseInfo = { url: string; source: ApiBaseSource }
 const usageError = (msg: string): Error => { const e = new Error(msg); e.name = 'UsageError'; return e }
+
+export function optionArgv(argv: readonly string[] = process.argv): readonly string[] {
+  const delimiter = argv.indexOf('--')
+  return delimiter < 0 ? argv : argv.slice(0, delimiter)
+}
+
 // the explicit routing flag, read from THIS process's argv (never the environment — that's the point).
 // `--port` doubles as a BIND port for serve/dashboard, so the sugar is skipped for those verbs.
 function explicitApiFlag(): string | null {
-  const argv = process.argv
+  const argv = optionArgv()
   const ai = argv.indexOf('--api')
   if (ai >= 0) {
     const v = argv[ai + 1]
@@ -1536,7 +1689,7 @@ export class SessionCreateError extends Error {
     this.name = 'SessionCreateError'
   }
 }
-type SessionCreateContext = { id: string; requestDigest: string; payloadHash: string; signal: AbortSignal }
+type SessionCreateContext = { id: string; requestDigest: string; payloadHash: string; signal: AbortSignal; base?: string | null }
 type SessionCreateRequestOptions = {
   requestKey?: string
   signal?: AbortSignal
@@ -1585,12 +1738,16 @@ function throwIfCreateAborted(signal: AbortSignal, phase: SessionCreatePhase): v
 export async function sessionCreateRequest(body: unknown, options: SessionCreateRequestOptions = {}): Promise<SessionCreateRequestResult> {
   if (!body || typeof body !== 'object' || Array.isArray(body)) return { status: 400, error: 'body must be a JSON object' }
   const input = body as Record<string, unknown>
-  const unknown = Object.keys(input).filter((key) => !['prompt', 'parent', 'launcher'].includes(key)).sort()
+  const unknown = Object.keys(input).filter((key) => !['prompt', 'parent', 'launcher', 'name', 'base'].includes(key)).sort()
   if (unknown.length) return { status: 400, error: `unknown session-create field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}` }
   const prompt = typeof input.prompt === 'string' ? input.prompt : ''
   if (!prompt.trim()) return { status: 400, error: 'empty prompt' }
   const launcher = typeof input.launcher === 'string' && input.launcher.trim() ? input.launcher.trim() : undefined
   const parent = typeof input.parent === 'string' && input.parent.trim() ? input.parent.trim() : null
+  if (input.name !== undefined && typeof input.name !== 'string') return { status: 400, error: 'session-create name must be a string' }
+  const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : null
+  if (input.base !== undefined && typeof input.base !== 'string') return { status: 400, error: 'session-create base must be a string' }
+  const base = typeof input.base === 'string' && input.base.trim() ? input.base.trim() : null
   let key: string
   try { key = normalizeCreateKey(options.requestKey) }
   catch (error) {
@@ -1599,7 +1756,10 @@ export async function sessionCreateRequest(body: unknown, options: SessionCreate
   }
   const requestDigest = digest(key)
   const id = sessionIdForCreateKey(key)
-  const payloadHash = digest(JSON.stringify({ prompt, parent, launcher: launcher ?? null }))
+  // Keep no-name retries byte-compatible with pre-name receipts; an explicit non-empty name is one more
+  // immutable creation input because it publishes the record's existing display override. `base` joins them
+  // for the same reason and with the same shape: absent, it must not perturb an existing receipt's bytes.
+  const payloadHash = digest(JSON.stringify({ prompt, parent, launcher: launcher ?? null, ...(name ? { name } : {}), ...(base ? { base } : {}) }))
   const controller = new AbortController()
   const cancel = () => controller.abort(new SessionCreateError('session_create_cancelled', 'request', 'session creation caller disconnected', 408))
   if (options.signal?.aborted) cancel()
@@ -1609,7 +1769,7 @@ export async function sessionCreateRequest(body: unknown, options: SessionCreate
   traceSessionCreate(id, requestDigest, 'request', 'start')
   try {
     try {
-      const session = await prepareSession(prompt, parent, launcher, { id, requestDigest, payloadHash, signal: controller.signal })
+      const session = await prepareSession(prompt, parent, launcher, name, { id, requestDigest, payloadHash, base, signal: controller.signal })
       traceSessionCreate(id, requestDigest, 'request', 'finish')
       return { status: 201, session }
     } catch (error) {
@@ -1658,15 +1818,16 @@ async function probeSessionCreateAuthority(target: ApiBaseInfo): Promise<boolean
     return false
   } finally { clearTimeout(timer) }
 }
-export async function createSession(prompt: string, launcher?: string): Promise<Session> {
+export async function createSession(prompt: string, launcher?: string, name?: string, base?: string): Promise<Session> {
   const parent = ownSessionId()
   const requestKey = randomUUID()
+  const body = { prompt, parent, launcher, ...(name !== undefined ? { name } : {}), ...(base !== undefined ? { base } : {}) }
   const target = await apiBaseInfo()
-  const base = target.url
+  const apiUrl = target.url
   const refused = await probeSessionCreateAuthority(target)
   if (refused) {
     console.error('spex: no backend reachable — launching in-process (caller env owns auth, no concurrency cap)')
-    const fallback = await sessionCreateRequest({ prompt, parent, launcher }, { requestKey })
+    const fallback = await sessionCreateRequest(body, { requestKey })
     if (fallback.status === 201) return fallback.session
     const error = new Error(`${fallback.code || 'session_create_failed'}: ${fallback.error}`)
     error.name = 'BackendError'
@@ -1677,10 +1838,10 @@ export async function createSession(prompt: string, launcher?: string): Promise<
   timer.unref?.()
   let res: Response
   try {
-    res = await fetch(`${base}/api/sessions`, {
+    res = await fetch(`${apiUrl}/api/sessions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json', 'Idempotency-Key': requestKey },
-      body: JSON.stringify({ prompt, parent, launcher }),
+      body: JSON.stringify(body),
       signal: controller.signal,
     })
   } catch (error) {
@@ -1944,8 +2105,8 @@ async function proveSessionCandidate(path: string, branch: string, signal: Abort
   return null
 }
 
-async function prepareSession(prompt: string, parent: string | null, launcher: string | undefined, context: SessionCreateContext): Promise<Session> {
-  const { id, requestDigest, payloadHash, signal } = context
+async function prepareSession(prompt: string, parent: string | null, launcher: string | undefined, name: string | null, context: SessionCreateContext): Promise<Session> {
+  const { id, requestDigest, payloadHash, base, signal } = context
   let phase: SessionCreatePhase = 'creation-lock'
   let shouldDrain = false
   traceSessionCreate(id, requestDigest, phase, 'start')
@@ -1984,6 +2145,16 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
       const title = ref ? null : titleFromPrompt(rawPrompt)
       const slug = `${slugify(ref || title)}-${id.slice(0, 4)}`
       const root = mainRoot()
+      // An explicit base pins the fork point so a run is reproducible against a frozen commit instead of
+      // whatever the source-of-truth branch has drifted to. Resolve it here, before any git mutation: an
+      // unknown ref must fail the create request outright, never leave a half-made worktree behind.
+      const startPoint = base ?? mainBranch()
+      if (base) {
+        const resolved = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`]))
+        if (!resolved.ok || !resolved.stdout.trim()) {
+          throw new SessionCreateError('session_create_failed', phase, `session-create base does not name a commit: ${base}`, 400)
+        }
+      }
       const branch = `${readConfig(dirname(gitCommonDir())).branchPrefix ?? 'node/'}${slug}`
       const path = join(root, '.worktrees', slug)
       const spec = ref ? launchSpecs?.find((node) => node.id === ref) : undefined
@@ -2041,7 +2212,7 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
           gitMutationStarted = true
           traceSessionCreate(id, requestDigest, phase, 'start', 'worktree-add')
           const added = await withGitAbortSignal(signal, () => gitTry(
-            ['-C', root, 'worktree', 'add', '-b', branch, path, mainBranch()],
+            ['-C', root, 'worktree', 'add', '-b', branch, path, startPoint],
             { extraEnv: DEFER_FOOTPRINT_REFRESH },
           ))
           traceSessionCreate(id, requestDigest, phase, 'finish', 'worktree-add')
@@ -2058,10 +2229,11 @@ async function prepareSession(prompt: string, parent: string | null, launcher: s
 
           let rec: SessRec = {
             session: id, governed: true, worktreePath: path, branch,
-            node: ref || null, title, name: null, parent: parent && parent !== id ? parent : null,
+            node: ref || null, title, name, parent: parent && parent !== id ? parent : null,
             status: 'queued', proposal: null, merges: 0, note: null, sortKey: null, createdAt: Date.now(),
             harness: h.id, harnessSessionId: null, stopped: false, archived: false, coldProof: null, adapterRecovery: null, launcher: chosen.name,
             launchCmd: pinned, launchOwner: backendLaunchAuthority(), createRequestId: requestDigest, createPayloadHash: payloadHash,
+            ...(base ? { base } : {}),
           }
           owned.store = true
           const dir = storeDir(id)
@@ -2411,6 +2583,8 @@ export type ReviewGates = {
 }
 export type ReviewPayload = {
   id: string; node: string | null; branch: string | null
+  branchHead: string         // immutable session-branch object whose committed review facts describe
+  baseHead: string           // immutable canonical-base object from the same ref snapshot
   label: string              // the session's identity, derived ONCE via deriveLabel — the review surface renders THIS, never its own node||branch||id chain
   ahead: number              // commits the node branch is ahead of main
   dirtyNonRuntime: number    // uncommitted files excluding SpexCode's own runtime files
@@ -2419,6 +2593,23 @@ export type ReviewPayload = {
   proposal: { kind: Proposal | null; note: string | null }   // the session's standing proposal + its note
 }
 
+type ReviewHeadPair = { branchHead: string; baseHead: string }
+
+async function reviewHeadPair(root: string, branch: string, base: string): Promise<ReviewHeadPair> {
+  const branchRef = `refs/heads/${branch}`, baseRef = `refs/heads/${base}`
+  const output = await gitA(['-C', root, 'for-each-ref', '--sort=refname', '--format=%(refname)%00%(objectname)', branchRef, baseRef])
+  const refs = new Map<string, string>()
+  for (const line of output.split('\n')) {
+    const at = line.indexOf('\0')
+    if (at > 0) refs.set(line.slice(0, at), line.slice(at + 1).trim())
+  }
+  const branchHead = refs.get(branchRef), baseHead = refs.get(baseRef)
+  if (!branchHead || !baseHead || !isGitObjectId(root, branchHead) || !isGitObjectId(root, baseHead)) {
+    throw new ResourceConflict(`review head pair is unproven: ${branchRef} or ${baseRef} is missing or not a native Git object id`)
+  }
+  return { branchHead, baseHead }
+}
+
 // @@@ lintGate - the spec↔code graph lint is a LOCATION gate: a function of the backend checkout's tree ALONE
 // (its .spec graph + governed files), not of which session is reviewed, and it costs a few seconds. Re-running
 // it on every reviewPayload — i.e. on every [[session-eval]] Proof-tab open, and once per session — is
@@ -2465,19 +2656,28 @@ async function lintGate(): Promise<ReviewGates['lint']> {
 export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
   const wt = await findWorktree(id)
   if (!wt) return null
+  if (!wt.rec.governed || !wt.branch) throw new ResourceConflict(`session ${id} has no governed branch to review`)
   const base = mainBranch()
+  const { branchHead, baseHead } = await reviewHeadPair(wt.path, wt.branch, base)
   const [aheadOut, statusOut, diff, conflictsWithMain, lint] = await Promise.all([
-    gitA(['-C', wt.path, 'rev-list', '--count', `${base}..HEAD`]),
+    gitA(['-C', wt.path, 'rev-list', '--count', `${baseHead}..${branchHead}`]),
     gitA(['-C', wt.path, 'status', '--porcelain', '--untracked-files=all']),
-    mergeBaseDiff(wt.path, base),
-    mergeConflicts(wt.path, base),
+    mergeBaseDiff(wt.path, baseHead, branchHead),
+    mergeConflicts(wt.path, baseHead, branchHead),
     lintGate(),   // lint — memoized on the checkout fingerprint, not re-run per session/open
   ])
+  const settledPair = await reviewHeadPair(wt.path, wt.branch, base)
+  if (settledPair.branchHead !== branchHead || settledPair.baseHead !== baseHead) {
+    throw new ResourceConflict(
+      `review head pair changed while assembling: started branch ${branchHead} / base ${baseHead}, ended branch ${settledPair.branchHead} / base ${settledPair.baseHead}`,
+      'session_review_head_changed',
+    )
+  }
   // the worktree carries no SpexCode runtime files any more (the store lives in ~/.spexcode), so every dirty
   // path is genuine work — this is just the total uncommitted count.
   const dirtyNonRuntime = statusOut.split('\n').filter(Boolean).map(porcelainPath).length
   return {
-    id, node: wt.rec.node, branch: wt.branch,
+    id, node: wt.rec.node, branch: wt.branch, branchHead, baseHead,
     label: deriveLabel({ id, name: wt.rec.name, node: wt.rec.node, title: wt.rec.title, branch: wt.branch }),
     ahead: Number(aheadOut.trim()) || 0,
     dirtyNonRuntime, diff,
@@ -2486,32 +2686,204 @@ export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
   }
 }
 
-function mergePrompt(mainPath: string, branch: string, reason: string): string {
-  const base = mainBranch()
+// @@@ shAscii - a 7-bit ASCII shell word yielding EXACTLY these bytes. A dispatched prompt crosses a control
+// channel, the agent's own tool call, and a terminal before a shell parses it, and a byte above 0x7F can be
+// dropped, replaced by U+FFFD, or truncate the line at any of those hops — the measured field failure. Bytes
+// that are already safe ASCII stay literal (an ASCII repo's prompt is byte-identical to before); anything
+// else is rebuilt from POSIX `printf %b` octal escapes, taken from the RAW bytes with no normalization.
+function shAscii(value: string | Buffer): string {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8')
+  const safe = (b: number) => b >= 0x20 && b <= 0x7e
+  if (bytes.every(safe)) return shQuote(bytes.toString('latin1'))
+  let escaped = ''
+  for (const b of bytes) escaped += safe(b) && b !== 0x27 && b !== 0x5c ? String.fromCharCode(b) : `\\0${b.toString(8).padStart(3, '0')}`
+  return `"$(printf '%b' '${escaped}')"`
+}
+const hexBytes = (value: string | Buffer): string => (Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8')).toString('hex')
+
+// @@@ mergePrompt - every gate states its own verdict, in ASCII. Two things were wrong with a bare `&&` chain
+// of `test`s. It is silent on BOTH outcomes, so an agent shown "no output" cannot tell a held gate from a
+// broken one and conservatively refuses to land forever; and it compared unicode ref/path bytes as shell
+// strings, which only works if every hop to the executor carried them intact. So each item now reports its
+// own actual-vs-expected value, only the whole conjunction emits the success token, and every value that can
+// carry a byte above 0x7F travels as hex (compared straight off the pipe, before any shell string layer) or
+// as a printf-escaped literal. The conjunction itself is unchanged: all five, resp. three, checks together.
+function mergePrompt(mainPath: string, worktreePath: string, worktreeTop: Buffer, branch: string, base: string, expectedBranchHead: string, expectedBaseHead: string, reason: string): string {
+  const mainQ = shQuote(mainPath)
+  const mainA = shAscii(mainPath), worktreeA = shAscii(worktreePath)
+  const refA = shAscii(`refs/heads/${branch}`), baseRefA = shAscii(`refs/heads/${base}`), baseA = shAscii(base)
+  const topHexQ = shQuote(hexBytes(worktreeTop)), refHexQ = shQuote(hexBytes(`refs/heads/${branch}`))
+  const reviewedQ = shQuote(expectedBranchHead), baseHeadQ = shQuote(expectedBaseHead)
+  const messageA = shAscii(`merge ${branch}: ${reason}`)
+  const hexPipe = `| tr -d '\\n' | od -An -tx1 | tr -d ' \\n'`
   return `Merge your branch \`${branch}\` into \`${base}\`, then propose close. You know this work, so resolve any conflicts yourself — in YOUR OWN worktree, never in the shared ${base} checkout.\n\n` +
+    `0. Re-prove the REVIEWED generation BEFORE changing anything. All five checks must hold together, and the block SAYS SO: reading \`REVIEWED_GENERATION_OK\` is the ONLY pass. A \`REVIEWED_GENERATION_FAIL <n>/<item>\` line — or no output at all — is a FAIL: STOP, report the stale review naming that item, and do not sync or land. (Detached HEAD, another checked-out branch, a moved/missing branch/base ref, or any OID outside the reviewed pair each surface as one of the five items.) Run the block AS WRITTEN — it is pure ASCII on purpose, and items 1 and 2 compare hex so a retyped or re-encoded copy cannot change what they mean:\n` +
+    `   wt=${worktreeA}; main_ck=${mainA}; ref=${refA}; base_ref=${baseRefA}\n` +
+    `   want_top=${topHexQ}; want_ref=${refHexQ}; want_reviewed=${reviewedQ}; want_base=${baseHeadQ}\n` +
+    `   g1=$(git -C "$wt" rev-parse --show-toplevel ${hexPipe}); test "$g1" = "$want_top" || echo "REVIEWED_GENERATION_FAIL 1/toplevel: hex [$g1] != [$want_top]"\n` +
+    `   g2=$(git -C "$wt" symbolic-ref --quiet HEAD ${hexPipe}); test "$g2" = "$want_ref" || echo "REVIEWED_GENERATION_FAIL 2/symbolic: hex [$g2] != [$want_ref]"\n` +
+    `   g3=$(git -C "$wt" rev-parse HEAD); test "$g3" = "$want_reviewed" || echo "REVIEWED_GENERATION_FAIL 3/wtHEAD: [$g3] != [$want_reviewed]"\n` +
+    `   g4=$(git -C "$main_ck" show-ref --verify --hash "$ref"); test "$g4" = "$want_reviewed" || echo "REVIEWED_GENERATION_FAIL 4/mainref: [$g4] != [$want_reviewed]"\n` +
+    `   g5=$(git -C "$main_ck" show-ref --verify --hash "$base_ref"); test "$g5" = "$want_base" || echo "REVIEWED_GENERATION_FAIL 5/baseref: [$g5] != [$want_base]"\n` +
+    `   test "$g1" = "$want_top" && test "$g2" = "$want_ref" && test "$g3" = "$want_reviewed" && test "$g4" = "$want_reviewed" && test "$g5" = "$want_base" && echo REVIEWED_GENERATION_OK\n` +
     `1. Sync first, where you work: \`git merge ${base}\` INTO your branch, resolve every conflict here, and re-run what proves your work. The ${base} checkout is the fleet's ONE landing door — a merge that stops to ask about conflicts holds it for everyone.\n` +
-    `2. Land only a TRIVIAL merge: \`git -C ${mainPath} merge-base --is-ancestor ${base} ${branch}\` must exit 0 (your branch already contains ${base}) — then\n   git -C ${mainPath} merge --no-ff -m "merge ${branch}: ${reason}" ${branch}\n   If that check fails, ${base} moved while you tested: go back to step 1 instead of landing.\n` +
+    `2. Freeze the TESTED result immediately before landing and merge that exact object, never a moving branch name. Same rules as step 0 — run it as written, and \`LANDING_MERGED <oid>\` is the ONLY proof it landed; it prints only after all three guards held AND the merge itself succeeded:\n` +
+    `   wt=${worktreeA}; main_ck=${mainA}; ref=${refA}; base_br=${baseA}; msg=${messageA}; want_ref=${refHexQ}\n` +
+    `   candidate=$(git -C "$wt" rev-parse HEAD)\n` +
+    `   c1=$(git -C "$wt" symbolic-ref --quiet HEAD ${hexPipe}); test "$c1" = "$want_ref" || echo "LANDING_FAIL 1/symbolic: hex [$c1] != [$want_ref]"\n` +
+    `   c2=$(git -C "$main_ck" show-ref --verify --hash "$ref"); test "$c2" = "$candidate" || echo "LANDING_FAIL 2/mainref: [$c2] != [$candidate]"\n` +
+    `   c3=0; git -C "$main_ck" merge-base --is-ancestor "$base_br" "$candidate" || { c3=1; echo "LANDING_FAIL 3/ancestor: [$candidate] does not contain the base branch; go back to step 1"; }\n` +
+    `   test "$c1" = "$want_ref" && test "$c2" = "$candidate" && test "$c3" = 0 && git -C "$main_ck" merge --no-ff -m "$msg" "$candidate" && echo "LANDING_MERGED $candidate"\n` +
+    `   No \`LANDING_MERGED\` line means nothing landed: a \`LANDING_FAIL\` names which guard, and its absence after the guards held means the merge itself failed. Either way ${base} or the branch moved while you tested — go back to step 0/review instead of landing.\n` +
     `3. A busy door is a wait, not a race: if the ${base} checkout is already mid-merge (an unresolved index), retry with a bounded wait — never abort or resolve someone else's in-progress merge. ` +
-    `4. Verify it landed: \`${base}\`'s HEAD must now be the new merge commit and no merge may be left in progress — if YOUR merge went half-merged, run \`git -C ${mainPath} merge --abort\` and report it rather than leaving \`${base}\` mid-state. ` +
+    `4. Verify it landed: \`${base}\`'s HEAD must now be the new merge commit and no merge may be left in progress — if YOUR merge went half-merged, run \`git -C ${mainQ} merge --abort\` and report it rather than leaving \`${base}\` mid-state. ` +
     `5. Once you've verified \`${base}\` advanced cleanly, propose close for the human — do NOT close it yourself.`
 }
 
-async function mergeSessionUnlocked(id: string): Promise<{ dispatched: boolean; reason?: string }> {
+export type MergeSessionResult =
+  | { dispatched: true; replayed?: boolean; expectedBranchHead: string; expectedBaseHead: string }
+  | { dispatched: false; reason: string; code?: 'session_merge_invalid_request' | 'session_merge_key_reused' | 'session_merge_head_changed' | 'session_merge_branch_unproven' | 'session_merge_not_proposed'; status?: 400 | 409 }
+export type MergeSessionOptions = { requestKey?: string; expectedBranchHead?: string; expectedBaseHead?: string }
+
+function normalizeMergeKey(raw: string | undefined): string | null {
+  if (raw === undefined) return null
+  const key = raw.trim()
+  if (!key || key.length > 128 || !/^[\x21-\x7e]+$/.test(key)) return null
+  return key
+}
+
+async function proveMergeBranchIdentity(worktreePath: string, branch: string, base: string): Promise<{ ok: true; branchHead: string; baseHead: string; top: string } | { ok: false; reason: string }> {
+  const [top, symbolic, head, pair] = await Promise.all([
+    gitTry(['-C', worktreePath, 'rev-parse', '--show-toplevel']),
+    gitTry(['-C', worktreePath, 'symbolic-ref', '--quiet', '--short', 'HEAD']),
+    gitTry(['-C', worktreePath, 'rev-parse', 'HEAD']),
+    reviewHeadPair(worktreePath, branch, base).then((value) => ({ ok: true as const, value }), (error) => ({ ok: false as const, error })),
+  ])
+  if (!top.ok || !symbolic.ok || !head.ok || !pair.ok) {
+    return { ok: false, reason: `branch identity is unreadable${!symbolic.ok ? ' (worktree HEAD is detached or not symbolic)' : ''}` }
+  }
+  let actualTop = top.stdout.trim(), expectedTop = worktreePath
+  try { actualTop = realpathSync(actualTop) } catch { /* comparison reports the missing/moved root */ }
+  try { expectedTop = realpathSync(expectedTop) } catch { /* comparison reports the missing/moved root */ }
+  if (actualTop !== expectedTop) return { ok: false, reason: `worktree top-level is ${actualTop}, expected ${expectedTop}` }
+  if (symbolic.stdout.trim() !== branch) return { ok: false, reason: `worktree checked out ${symbolic.stdout.trim() || '(detached)'}, expected ${branch}` }
+  const worktreeHead = head.stdout.trim()
+  if (worktreeHead !== pair.value.branchHead) return { ok: false, reason: `worktree HEAD ${worktreeHead} does not match stored branch ${branch} at ${pair.value.branchHead}` }
+  return { ok: true, ...pair.value, top: actualTop }
+}
+
+type DispatchDelivery = NonNullable<SentDispatchReceipt['delivery']>
+function keyedPendingMessage(receipt: SentDispatchReceipt, mid: string, delivery: DispatchDelivery): PendingMessage {
+  return {
+    mid,
+    text: delivery.text,
+    from: delivery.from,
+    dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
+  }
+}
+
+async function acceptedMergeDispatch(id: string, idempotency: SentDispatchReceipt): Promise<SentDispatchState | null> {
+  return withRecordLock(id, async () => withDeliveryLocks([id], async () => {
+    const prior = sentDispatchReceipt(id, idempotency.operation, idempotency.requestDigest)
+    if (prior?.payloadHash === idempotency.payloadHash && prior.delivery && !prior.delivered) {
+      ensurePendingWhileLocked(id, keyedPendingMessage(idempotency, prior.mid, prior.delivery))
+    }
+    return prior
+  }))
+}
+
+async function replayAcceptedMerge(id: string, idempotency: SentDispatchReceipt, prior: SentDispatchState): Promise<void> {
+  // Old receipts predate recoverable delivery bytes and are already accepted history. Settled receipts are
+  // likewise response-only: replay must not reopen or otherwise mutate a session after its later lifecycle.
+  if (!prior.delivery || prior.delivered) return
+  await drainSession(id)
+  const current = sentDispatchReceipt(id, idempotency.operation, idempotency.requestDigest)
+  if (current?.delivered) return
+  await resumeSession(id, { guard: false })
+  await drainSession(id)
+}
+
+async function mergeSessionUnlocked(id: string, options: MergeSessionOptions = {}): Promise<MergeSessionResult> {
+  const requestKey = normalizeMergeKey(options.requestKey)
+  if (!requestKey) {
+    return { dispatched: false, reason: 'Idempotency-Key must be 1-128 visible ASCII characters', code: 'session_merge_invalid_request', status: 400 }
+  }
+  const expectedBranchHead = options.expectedBranchHead, expectedBaseHead = options.expectedBaseHead
+  if (expectedBranchHead === undefined || expectedBaseHead === undefined) {
+    return { dispatched: false, reason: 'expectedBranchHead and expectedBaseHead are required with Idempotency-Key', code: 'session_merge_invalid_request', status: 400 }
+  }
+  const main = mainRoot()
+  if (!isGitObjectId(main, expectedBranchHead) || !isGitObjectId(main, expectedBaseHead)) {
+    return { dispatched: false, reason: 'expectedBranchHead and expectedBaseHead must be full lowercase native Git object ids', code: 'session_merge_invalid_request', status: 400 }
+  }
+  const idempotency = {
+    operation: 'merge' as const,
+    requestDigest: digest(`spexcode-session-merge\0${requestKey}`),
+    payloadHash: digest(JSON.stringify({ expectedBranchHead, expectedBaseHead })),
+  }
+  const prior = await acceptedMergeDispatch(id, idempotency)
+  if (prior) {
+    if (prior.payloadHash !== idempotency.payloadHash) {
+      return { dispatched: false, reason: 'Idempotency-Key is already bound to another session-merge payload', code: 'session_merge_key_reused', status: 409 }
+    }
+    await replayAcceptedMerge(id, idempotency, prior)
+    return { dispatched: true, replayed: true, expectedBranchHead, expectedBaseHead }
+  }
+  const [branchObject, baseObject] = await Promise.all([
+    gitTry(['-C', main, 'cat-file', '-e', `${expectedBranchHead}^{commit}`]),
+    gitTry(['-C', main, 'cat-file', '-e', `${expectedBaseHead}^{commit}`]),
+  ])
+  if (!branchObject.ok || !baseObject.ok) {
+    return {
+      dispatched: false,
+      reason: `reviewed heads are missing or are not commits: branch ${expectedBranchHead} / base ${expectedBaseHead}`,
+      code: 'session_merge_head_changed',
+      status: 409,
+    }
+  }
   const wt = await findWorktree(id)
   if (!wt || !wt.branch) return { dispatched: false, reason: 'no such session' }
-  const branch = wt.branch, main = mainRoot()
-  // ensure-live, NOT the guarded human relaunch: an already-online agent is reused (the merge prompt just needs
-  // a live socket), and only a confirmed-offline one is relaunched — so merge never refuses on a live agent.
-  const re = await resumeSession(id, { guard: false })
-  if (!re.ok) return { dispatched: false, reason: re.error || 'could not resume session' }
-  const subject = (await gitA(['-C', main, 'log', '-1', '--format=%s', branch])).trim()
+  const branch = wt.branch, base = mainBranch()
+  // Raw bytes, not a decoded-then-re-encoded string: the gate's expected hex must be what the filesystem
+  // holds, so no normalization can slip between what we promise and what git will print.
+  let worktreeTop = Buffer.from(wt.path, 'utf8')
+  try { worktreeTop = realpathSync(wt.path, { encoding: 'buffer' }) } catch { /* the locked proof reports the vanished worktree */ }
+  const subject = (await gitA(['-C', main, 'log', '-1', '--format=%s', expectedBranchHead])).trim()
   const reason = subject.replace(/^spec:\s+/, '') || branch
-  const r = await sendText(id, mergePrompt(main, branch, reason))
-  if (!r.ok) return { dispatched: false, reason: r.error }
-  return { dispatched: true }
+  const r = await sendText(id, mergePrompt(main, wt.path, worktreeTop, branch, base, expectedBranchHead, expectedBaseHead, reason), undefined, {
+    idempotency,
+    deferDrain: true,
+    acceptGuard: async (rec) => {
+      const conflict = (message: string, code: NonNullable<Extract<MergeSessionResult, { dispatched: false }>['code']>) =>
+        Object.assign(new ResourceConflict(message), { code })
+      if (!rec.governed || rec.status !== 'awaiting' || rec.proposal !== 'merge') {
+        throw conflict(`session ${id} is not a governed awaiting merge proposal`, 'session_merge_not_proposed')
+      }
+      if (rec.worktreePath !== wt.path || rec.branch !== branch) {
+        throw conflict(`session branch identity changed before merge acceptance`, 'session_merge_branch_unproven')
+      }
+      const proof = await proveMergeBranchIdentity(rec.worktreePath, branch, base)
+      if (!proof.ok) throw conflict(`session branch identity is unproven: ${proof.reason}`, 'session_merge_branch_unproven')
+      if (proof.branchHead !== expectedBranchHead || proof.baseHead !== expectedBaseHead) {
+        throw conflict(`reviewed heads changed: expected branch ${expectedBranchHead} / base ${expectedBaseHead}, found branch ${proof.branchHead} / base ${proof.baseHead}`, 'session_merge_head_changed')
+      }
+    },
+  })
+  if (r.code === 'dispatch_key_reused') {
+    return { dispatched: false, reason: 'Idempotency-Key is already bound to another session-merge payload', code: 'session_merge_key_reused', status: 409 }
+  }
+  if (r.code === 'session_merge_not_proposed' || r.code === 'session_merge_branch_unproven' || r.code === 'session_merge_head_changed') {
+    return { dispatched: false, reason: r.error || 'merge authority refused', code: r.code, status: 409 }
+  }
+  if (!r.ok) return { dispatched: false, reason: r.error || 'could not dispatch merge prompt' }
+  // Acceptance is already durable. Ensure-live follows it so no relaunch/state mutation can happen before the
+  // reviewed CAS; a failed relaunch leaves the one queued debt for the ordinary delivery supervisor.
+  await resumeSession(id, { guard: false })
+  await drainSession(id)
+  return { dispatched: true, replayed: r.replayed === true, expectedBranchHead, expectedBaseHead }
 }
-export const mergeSession = (id: string): Promise<{ dispatched: boolean; reason?: string }> =>
-  mergeSessionUnlocked(id)
+export const mergeSession = (id: string, options: MergeSessionOptions = {}): Promise<MergeSessionResult> =>
+  mergeSessionUnlocked(id, options)
 
 // @@@ killAgentProcess - the pane is the agent's HOME, not its LEASH. `kill-session` SIGHUPs the pane's
 // process group, and an idle agent goes with it (measured: ~0.8s) — but one mid-turn can outlive the whole
@@ -2525,6 +2897,12 @@ export const mergeSession = (id: string): Promise<{ dispatched: boolean; reason?
 // adapter's proof-of-death rule leave the transport alone; never a blind kill on a stale number.
 const AGENT_EXIT_GRACE_MS = 3000
 type LeafIdentity = { pid: number; startToken: string; ownerNeedle: string }
+type LeafIdentityObservation =
+  | { state: 'missing' }
+  | { state: 'dead'; pid: number }
+  | { state: 'owned'; identity: LeafIdentity }
+  | { state: 'unrelated'; pid: number; startToken: string }
+  | { state: 'unknown'; pid?: number; reason: string }
 async function killAgentProcess(id: string, beforeSignal: () => Promise<void>, leaf: LeafIdentity): Promise<void> {
   const pid = readAgentPid(sessionArtifactPath(id, 'agent.pid'))
   if (pid !== leaf.pid)
@@ -2579,28 +2957,48 @@ const leafAlive = (pid: number): boolean => {
   catch (error) { return (error as NodeJS.ErrnoException)?.code !== 'ESRCH' }
 }
 
+// One identity seam serves both signal teardown and cold retirement. A PID is only a locator: a live process
+// becomes target-owned when its immutable start identity is readable AND its argv carries the harness-owned
+// native identity. A live PID with a proven different argv is a stale artifact, while malformed/unreadable
+// evidence remains unknown and therefore blocks every destructive path.
+async function inspectSessionLeafIdentity(id: string, rec: SessRec): Promise<LeafIdentityObservation> {
+  if (harnessById(rec.harness || defaultHarness.id).runtimeOwnership === 'adapter') return { state: 'missing' }
+  const path = sessionArtifactPath(id, 'agent.pid')
+  let raw: string
+  try { raw = readFileSync(path, 'utf8') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return { state: 'missing' }
+    return { state: 'unknown', reason: `leaf PID artifact is unreadable (${error instanceof Error ? error.message : String(error)})` }
+  }
+  const pid = Number(raw.trim())
+  if (!Number.isSafeInteger(pid) || pid <= 0) return { state: 'unknown', reason: 'leaf PID artifact is malformed' }
+  const startToken = processStartToken(pid)
+  if (!startToken) return leafAlive(pid) ? { state: 'unknown', pid, reason: `leaf PID ${pid} is alive but its process-start identity is unreadable` } : { state: 'dead', pid }
+  const ownerNeedle = harnessById(rec.harness || defaultHarness.id).leafOwnerNeedle?.(rec)
+  if (!ownerNeedle) return { state: 'unknown', pid, reason: `no exact harness identity is registered for leaf PID ${pid}` }
+  let argv: string
+  try { argv = (await pexec('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8' })).stdout.trim() }
+  catch { return { state: 'unknown', pid, reason: `leaf PID ${pid} argv identity is unreadable` } }
+  if (!argv) return { state: 'unknown', pid, reason: `leaf PID ${pid} argv identity is empty` }
+  const endToken = processStartToken(pid)
+  if (!endToken || endToken !== startToken)
+    return { state: 'unknown', pid, reason: `leaf PID ${pid} process-start identity changed during ownership read` }
+  if (argv.includes(ownerNeedle)) return { state: 'owned', identity: { pid, startToken, ownerNeedle } }
+  return { state: 'unrelated', pid, startToken }
+}
+
 async function assertSessionLeafOwned(id: string, rec: SessRec): Promise<LeafIdentity | null> {
-  const harness = harnessById(rec.harness || defaultHarness.id)
-  if (harness.runtimeOwnership === 'adapter') return null
-  // Prove the exact per-session leaf before the first tmux signal. Missing identity is acceptable only for a
-  // record-only/queued runtime; a live leaf without a matching pid/start/argv stays visible.
-  const pid = readAgentPid(sessionArtifactPath(id, 'agent.pid'))
-  if (!Number.isFinite(pid) || pid <= 0) {
+  if (harnessById(rec.harness || defaultHarness.id).runtimeOwnership === 'adapter') return null
+  const observed = await inspectSessionLeafIdentity(id, rec)
+  if (observed.state === 'missing') {
     if (rec.stopped || rec.status === 'queued') return null
     throw new ResourceConflict(`refusing to stop ${id}: no readable session-owned leaf PID`)
   }
-  const startToken = processStartToken(pid)
-  if (!startToken) {
-    if (rec.stopped || !leafAlive(pid)) return null
-    throw new ResourceConflict(`refusing to stop ${id}: session-owned leaf PID ${pid} is alive but will not prove its start identity`)
-  }
-  const argv = await pexec('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8' }).then((r) => r.stdout).catch(() => '')
-  const ownerNeedle = harness.leafOwnerNeedle?.(rec)
-  if (!ownerNeedle)
-    throw new ResourceConflict(`refusing to stop ${id}: no exact harness identity is registered for leaf PID ${pid}`)
-  if (!argv.includes(ownerNeedle) || processStartToken(pid) !== startToken)
-    throw new ResourceConflict(`refusing to stop ${id}: leaf PID ${pid}@${startToken} does not prove argv ownership`)
-  return { pid, startToken, ownerNeedle }
+  if (observed.state === 'dead') return null
+  if (observed.state === 'owned') return observed.identity
+  if (observed.state === 'unrelated')
+    throw new ResourceConflict(`refusing to stop ${id}: leaf PID ${observed.pid}@${observed.startToken} does not prove argv ownership`)
+  throw new ResourceConflict(`refusing to stop ${id}: ${observed.reason}`)
 }
 
 async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = false, coldReceipt?: unknown): Promise<void> {
@@ -2665,7 +3063,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
   // A proven cold record is already archived; never clear it and issue a second thread/archive RPC. Verify the
   // adapter's exact resident reference first so an externally respawned thread is repaired rather than hidden.
   if (wt.rec.archived && hasValidColdProof(wt.rec)) {
-    const proofSnap = await liveSnapshot()
+    const proofSnap = await liveSnapshot(id)
     if (proofSnap.probeFailed) throw new ResourceConflict(`refusing to re-archive ${id}: liveness probe failed; the exact leaf may have respawned`)
     const proofLv = h.runtimeOwnership === 'adapter'
       ? (proofSnap.windows.has(id) ? 'online' : 'offline')
@@ -2702,7 +3100,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     if (!wt) return false
   }
 
-  const snap = await liveSnapshot()
+  const snap = await liveSnapshot(id)
   if (snap.probeFailed) throw new ResourceConflict(`refusing to archive ${id}: liveness probe failed; the leaf may still be live`)
   const lv = h.runtimeOwnership === 'adapter'
     ? 'offline'
@@ -2711,6 +3109,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     throw new ResourceConflict(`refusing to archive ${id}: session liveness is ${lv}; exact leaf ownership is unproven`)
   // The adapter guard runs BEFORE any tmux/process signal. Active/unknown native turns and ambiguous descendant
   // ownership refuse here; a verified adapter receipt carries an exact subtree through to coldRuntime's commit.
+  assertSessionOwnerSafe(id, h.id)
   const preflight = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: lv === 'offline' })
   if (preflight && !preflight.ok) throw new ResourceConflict(`refusing to archive ${id}: ${preflight.reason}`)
   // Even a proven-offline leaf can leave a stale rendezvous/socket or adapter artifact. Reuse the same exact
@@ -2725,7 +3124,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     coldCommitted = true
     const latest = readRecord(id)
     if (!latest) throw new ResourceConflict(`refusing to archive ${id}: session record disappeared before filing`)
-    const finalSnap = await liveSnapshot()
+    const finalSnap = await liveSnapshot(id)
     if (finalSnap.probeFailed) throw new ResourceConflict(`refusing to archive ${id}: final liveness probe failed; the leaf may still be live`)
     const finalLv = h.runtimeOwnership === 'adapter'
       ? (finalSnap.windows.has(id) ? 'online' : 'offline')
@@ -2774,14 +3173,16 @@ async function assertColdRetirementSafe(id: string, rec: SessRec): Promise<void>
   if (rec.adapterRecovery)
     throw new ResourceConflict(`refusing to close archived session ${id}: adapter recovery is pending (${rec.adapterRecovery})`)
 
-  const [snap, socket] = await Promise.all([liveSnapshot(), rendezvousListening(id)])
+  const [snap, socket] = await Promise.all([liveSnapshot(id), rendezvousListening(id)])
   if (snap.probeFailed) throw new ResourceConflict(`refusing to close archived session ${id}: liveness probe failed; target runtime absence is unproven`)
   if (snap.windows.has(id)) throw new ResourceConflict(`refusing to close archived session ${id}: target tmux window has reappeared`)
   if (socket === 'live') throw new ResourceConflict(`refusing to close archived session ${id}: target rendezvous transport has reappeared`)
   if (socket === 'unproven') throw new ResourceConflict(`refusing to close archived session ${id}: target rendezvous state is ambiguous`)
-  const pid = readAgentPid(sessionArtifactPath(id, 'agent.pid'))
-  if (Number.isFinite(pid) && pid > 0 && processStartToken(pid))
-    throw new ResourceConflict(`refusing to close archived session ${id}: target leaf PID ${pid} is live or recycled; ownership is ambiguous`)
+  const leaf = await inspectSessionLeafIdentity(id, rec)
+  if (leaf.state === 'owned')
+    throw new ResourceConflict(`refusing to close archived session ${id}: target leaf PID ${leaf.identity.pid} is live or recycled; ownership is ambiguous`)
+  if (leaf.state === 'unknown')
+    throw new ResourceConflict(`refusing to close archived session ${id}: ${leaf.reason}; ownership is ambiguous`)
 
   const harness = harnessById(rec.harness || defaultHarness.id)
   if (harness.coldRetirementPreflight) {
@@ -2818,7 +3219,7 @@ async function assertQueuedRetirementSafe(id: string, rec: SessRec, path: string
   if (rec.adapterRecovery || launching.has(id))
     throw new ResourceConflict(`refusing to close queued session ${id}: target launch/recovery is already in progress`)
 
-  const [snap, socket] = await Promise.all([liveSnapshot(), rendezvousListening(id)])
+  const [snap, socket] = await Promise.all([liveSnapshot(id), rendezvousListening(id)])
   if (snap.probeFailed) throw new ResourceConflict(`refusing to close queued session ${id}: liveness probe failed; target runtime absence is unproven`)
   if (snap.windows.has(id)) throw new ResourceConflict(`refusing to close queued session ${id}: target tmux window already exists`)
   if (socket === 'live') throw new ResourceConflict(`refusing to close queued session ${id}: target rendezvous transport already exists`)
@@ -2850,15 +3251,21 @@ async function assertQueuedRetirementSafe(id: string, rec: SessRec, path: string
   }
 }
 
-async function closeOwnedSessionUnlocked(id: string, wt: { path: string; branch: string | null; rec: SessRec }): Promise<boolean> {
+async function closeOwnedSessionUnlocked(id: string, wt: { path: string; branch: string | null; rec: SessRec }, source: CloseSource): Promise<boolean> {
   const root = mainRoot()
   const receiptFailure = publishedSessionCandidateReceiptRetirementFailure(wt.rec, root)
   if (receiptFailure) throw new ResourceConflict(`refusing destructive close for ${id}: ${receiptFailure}; public record and resources remain the authority fence`)
   const closesCodexBinding = (wt.rec.harness === 'codex' || wt.rec.harness === 'codex-headless') && !!wt.rec.harnessSessionId
+  const retired = !wt.rec.archived && !!retirementReason(wt.rec)
+  // A retired row has already lost its worktree; close is its explicit record-only terminal cleanup.
+  if (!retired) {
+    if (wt.rec.archived) await assertColdRetirementSafe(id, wt.rec)
+    else if (wt.rec.status === 'queued') await assertQueuedRetirementSafe(id, wt.rec, wt.path, wt.branch)
+    else throw new ResourceConflict(`refusing to close ${id}: target runtime was not cold-retired first`)
+  }
+  // The marker protects only the destructive half. A failed cold proof must leave a normal, resumable binding.
   if (closesCodexBinding) prepareCodexGenerationClose(runtimeRoot(), id, wt.rec.harnessSessionId!)
-  if (wt.rec.archived) await assertColdRetirementSafe(id, wt.rec)
-  else if (wt.rec.status === 'queued') await assertQueuedRetirementSafe(id, wt.rec, wt.path, wt.branch)
-  else await stopAgentProcess(id, wt.rec)
+  appendCloseLedger(id, wt.rec, source)
   let slot: string | null = null
   try { slot = treeSlotDir(wt.path) } catch { /* tree already unresolvable — nothing to key the slot by */ }
   // a retired session's worktree/branch are already gone; removing them is a no-op to skip, not a failure.
@@ -2883,13 +3290,16 @@ async function closeOwnedSessionUnlocked(id: string, wt: { path: string; branch:
   try { rmSync(sessionStoreDir(id), { recursive: true, force: true }) }
   catch (error) { throw new ResourceConflict(`refusing to finish close for ${id}: session record/prompt removal failed (${error instanceof Error ? error.message : String(error)})`) }
   if (existsSync(sessionStoreDir(id))) throw new ResourceConflict(`refusing to finish close for ${id}: session record removal failed`)
+  // The close still owns this sender's record lock. Marking after its store is gone lets any send already
+  // admitted finish before close returns, while every later send and every retry sweep sees terminal output.
+  revokeSenderDelivery(id)
   if (closesCodexBinding && wt.rec.harnessSessionId) {
     bindCodexGeneration(runtimeRoot(), id, wt.rec.harnessSessionId, null)
   }
   requestQueueDrain()   // a close frees a slot — start the next queued session if any
   return true
 }
-async function closeSessionUnlocked(id: string): Promise<boolean> {
+async function closeSessionUnlocked(id: string, source: CloseSource): Promise<boolean> {
   let wt: { path: string; branch: string | null; rec: SessRec } | null = null
   try { wt = await findWorktree(id) }
   catch (e) {
@@ -2906,13 +3316,30 @@ async function closeSessionUnlocked(id: string): Promise<boolean> {
       `refusing destructive close for ${id}: the unreadable record proves no adapter, leaf, worktree, or branch owner (${guard}). ${evidence}. Runtime remains at ${runtime}; worktree and branch ownership is unknown and was not touched; no process signal or deletion was attempted.`)
   }
   if (!wt) return false
+  if (!retirementReason(wt.rec) && !wt.rec.archived && wt.rec.status !== 'queued') {
+    // A confirmed terminal close may end an exact native turn before cold proof. Ordinary archive deliberately
+    // remains non-destructive while a turn is active; close already means discard this session's work.
+    const harness = harnessById(wt.rec.harness || defaultHarness.id)
+    assertSessionOwnerSafe(id, harness.id)
+    const interrupt = harness.interrupt
+    if (interrupt) {
+      const result = await interrupt({ ...wt.rec, runtimeDir: runtimeRoot() })
+      if (!result.ok) throw new ResourceConflict(`refusing to close ${id}: native interrupt failed (${result.error || 'unknown error'})`)
+    }
+    const archived = await archiveSessionUnlocked(id)
+    if (!archived) return false
+    wt = await findWorktree(id)
+    if (!wt) return false
+  }
   const target = wt
   return target.branch
-    ? withRecordLock(sessionCandidateLockId(target.path, target.branch), () => closeOwnedSessionUnlocked(id, target))
-    : closeOwnedSessionUnlocked(id, target)
+    ? withRecordLock(sessionCandidateLockId(target.path, target.branch), () => closeOwnedSessionUnlocked(id, target, source))
+    : closeOwnedSessionUnlocked(id, target, source)
+}
+export const closeSession = (id: string, rawSource?: unknown): Promise<boolean> => {
+  const source = normalizeCloseSource(rawSource)
+  return withSessionTransition(id, () => withRecordLock(id, () => closeSessionUnlocked(id, source)))
 }
-export const closeSession = (id: string): Promise<boolean> =>
-  withSessionTransition(id, () => withRecordLock(id, () => closeSessionUnlocked(id)))
 
 export type CorruptRecordQuarantineWitness = {
   adapter: string
@@ -3253,21 +3680,21 @@ export function statusLegend(color = true): string {
   return c('90', '  key: ') + parts.join('  ')
 }
 
-// human-friendly aligned table: header + (glyph + colour + status + name + id + merges + note) rows +
+// human-friendly aligned table: header + (glyph + colour + status + title + id + merges + note) rows +
 // a status legend, so the table tells the whole story (incl. each agent's note) at a glance.
 export function formatTable(sessions: Session[], color = true): string {
   const c = (code: string, t: string) => (color ? `\x1b[${code}m${t}\x1b[0m` : t)
   if (!sessions.length) return c('90', '  no living sessions')
-  const header = c('90', `    ${'STATUS'.padEnd(13)} ${'NODE'.padEnd(22)} ${'ID'.padEnd(8)} ${'\u00d7'.padEnd(4)}${'PROMPT'.padEnd(42)}NOTE`)
+  const header = c('90', `    ${'STATUS'.padEnd(13)} ${'TITLE'.padEnd(22)} ${'ID'.padEnd(8)} ${'\u00d7'.padEnd(4)}${'PROMPT'.padEnd(42)}NOTE`)
   const rows = sessions.map((s) => {
     const g = STATUS_GLYPH[s.status] ?? '\u00b7'
     const code = ANSI[s.status] ?? '0'
-    const name = padWidth(truncWidth(sessionLabel(s), 22), 22)
+    const title = padWidth(truncWidth(sessionTitle(s), 22), 22)
     const st = s.status.padEnd(13)
     const merges = (s.merges ? `\u00d7${s.merges}` : '').padEnd(4)
     const prompt = c('90', padWidth(s.promptPreview ? trunc(s.promptPreview, 40) : '', 42))   // what it was asked to do
     const note = s.note ? c('90', trunc(s.note, NOTE_BOARD_LIMIT)) : ''
-    return `  ${c(code, g)} ${c(code, st)} ${name} ${c('90', s.id.slice(0, 8))} ${merges}${prompt}${note}`
+    return `  ${c(code, g)} ${c(code, st)} ${title} ${c('90', s.id.slice(0, 8))} ${merges}${prompt}${note}`
   })
   return [c('1', `SpexCode sessions (${sessions.length})`), header, ...rows, statusLegend(color)].join('\n')
 }
@@ -3280,27 +3707,72 @@ export function formatTable(sessions: Session[], color = true): string {
 // 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.)
-export async function sendText(id: string, text: string, from?: string, opts: { replyVia?: 'note' } = {}): Promise<DispatchResult> {
+type DispatchIdempotency = SentDispatchReceipt
+type DispatchAcceptCode = 'dispatch_key_reused' | 'session_merge_not_proposed' | 'session_merge_branch_unproven' | 'session_merge_head_changed'
+type AcceptedDispatch = DispatchResult & { replayed?: boolean; code?: DispatchAcceptCode }
+type SendTextOptions = {
+  replyVia?: 'note'
+  idempotency?: DispatchIdempotency
+  acceptGuard?: (record: SessRec) => Promise<void>
+  deferDrain?: boolean
+}
+export async function sendText(id: string, text: string, from?: string, opts: SendTextOptions = {}): Promise<AcceptedDispatch> {
   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 replayed = false
   try {
-    await withRecordLock(id, async () => {
-      const appended = appendSent(id, text, from ?? null, prompt.replyVia)
-      enqueue(id, { mid: appended.mid, text: prompt.text, from: from ?? null })
+    // Taking a declared sender's record lock makes close a real outgoing fence even across backend processes:
+    // a send either appends before close obtains the fence (and close's revocation voids its debt), or sees
+    // the terminal marker before it records anything. Arbitrary legacy `from` values keep working; they just
+    // name an otherwise-unused lock until a matching session is closed.
+    await withRecordLocks([id, ...(from ? [from] : [])].sort(), async () => {
+      if (from && senderDeliveryRevoked(from)) throw new ResourceConflict(`sender session ${from} is closed; prompt NOT delivered`)
+      const rec = readRecord(id)
+      if (!rec) throw new ResourceConflict(`no session record for ${id} — prompt NOT delivered`)
+      const accept = async () => {
+        if (opts.idempotency) {
+          const prior = sentDispatchReceipt(id, opts.idempotency.operation, opts.idempotency.requestDigest)
+          if (prior) {
+            if (prior.payloadHash !== opts.idempotency.payloadHash) {
+              const conflict = new ResourceConflict(`idempotency key is already bound to another ${opts.idempotency.operation} payload`)
+              Object.assign(conflict, { code: 'dispatch_key_reused' })
+              throw conflict
+            }
+            if (prior.delivery && !prior.delivered) {
+              ensurePendingWhileLocked(id, keyedPendingMessage(opts.idempotency, prior.mid, prior.delivery))
+            }
+            replayed = true
+            return
+          }
+        }
+        await opts.acceptGuard?.(rec)
+        // 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 })
+        const dispatchReceipt = opts.idempotency
+          ? { ...opts.idempotency, delivery: { text: prompt.text, from: from ?? null } }
+          : undefined
+        const appended = appendSent(id, text, from ?? null, prompt.replyVia, dispatchReceipt)
+        enqueue(id, opts.idempotency
+          ? keyedPendingMessage(opts.idempotency, appended.mid, dispatchReceipt!.delivery!)
+          : { mid: appended.mid, text: prompt.text, from: from ?? null })
+      }
+      if (opts.idempotency) await withDeliveryLocks([id], accept)
+      else await accept()
     })
   } 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 code = (error as { code?: DispatchAcceptCode })?.code
+    return {
+      ok: false,
+      error: `could not append the message to session ${id}'s log: ${error instanceof Error ? error.message : String(error)} — prompt NOT delivered`,
+      ...(code ? { code } : {}),
+    }
   }
   // 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 }
+  if (!opts.deferDrain) await drainSession(id)
+  return { ok: true, ...(opts.idempotency ? { replayed } : {}) }
 }
 
 // @@@ drainSession - hand over what this session is owed, as ordinary prompts. Safe to call from anywhere and
@@ -3312,6 +3784,12 @@ export async function drainSession(id: string): Promise<void> {
   if (!rec) return
   const h = harnessById(rec.harness || defaultHarness.id)
   await drain(id, async (msg) => {
+    if (msg.dispatch) {
+      const receipt = sentDispatchReceipt(id, msg.dispatch.operation, msg.dispatch.requestDigest)
+      if (!receipt || receipt.mid !== msg.mid || !receipt.delivery
+        || receipt.delivery.text !== msg.text || receipt.delivery.from !== msg.from) return false
+      if (receipt.delivered) return true
+    }
     // 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.
@@ -3320,7 +3798,9 @@ export async function drainSession(id: string): Promise<void> {
         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
+    const delivered = await h.deliver({ ...rec, runtimeDir: runtimeRoot(), mid: msg.mid }, msg.text)
+    if (delivered.ok && msg.dispatch) settleSentDispatch(id, msg.mid)
+    return delivered.ok
   })
 }