spexcode 0.6.0 → 0.6.2

package/spec-cli/src/client.ts

@@ -2,26 +2,113 @@ import { existsSync } from 'node:fs'
 import { platform } from 'node:os'
 import { repoRoot } from './git.js'
 import { resourceBudgets, type ResourceReport } from './host-resources.js'
-import { listSessionIds, readPublicRecordEntry } from './layout.js'
+import { envSessionId, listSessionIds, readPublicRecordEntry } from './layout.js'
 import { cockpitReview, type CockpitReview } from './cockpit.js'
-import { apiBase, apiBaseInfo, assertProjectMatch, fromRaw, resolveSession, toSession, type DisplayStatus, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
+import { apiBaseInfo, assertProjectMatch, fromRaw, optionArgv, resolveSession, toSession, type DisplayStatus, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
 
 export class BackendError extends Error {
-  constructor(message: string, readonly status?: number) {
+  constructor(message: string, readonly status?: number, readonly transport?: unknown) {
     super(message)
     this.name = 'BackendError'   // cli.ts's top-level handler matches on the NAME, so it needs no import of this class
   }
 }
 
+const usageError = (message: string): Error => {
+  const error = new Error(message)
+  error.name = 'UsageError'
+  return error
+}
+
+const hasFlag = (name: string): boolean => optionArgv().includes(`--${name}`)
+function flagValue(name: string): string | null {
+  const argv = optionArgv()
+  const index = argv.indexOf(`--${name}`)
+  if (index < 0) return null
+  const value = argv[index + 1]
+  if (value === undefined || value.startsWith('--')) throw usageError(`--${name} expects a value`)
+  return value
+}
+
+let gatewayCookie: { base: string; value: string } | null = null
+
+function prepareTls(base: string): void {
+  if (!hasFlag('insecure')) return
+  if (new URL(base).protocol !== 'https:') throw usageError('--insecure requires an https --api endpoint')
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
+}
+
+function passwordFor(target: Awaited<ReturnType<typeof apiBaseInfo>>): string | null {
+  const password = flagValue('password') ?? process.env.SPEXCODE_PASSWORD ?? null
+  if (!password) return null
+  if (target.source !== 'flag') throw usageError('--password and SPEXCODE_PASSWORD require explicit --api routing')
+  return password
+}
+
+function withCookie(init: RequestInit | undefined, cookie: string): RequestInit {
+  const headers = new Headers(init?.headers)
+  headers.set('cookie', cookie)
+  return { ...init, headers }
+}
+
+async function loginGateway(base: string, password: string): Promise<string> {
+  let response: Response
+  try {
+    response = await fetch(`${base}/login`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ password }).toString(),
+      redirect: 'manual',
+    })
+  } catch (error) {
+    throw new BackendError(`gateway login could not reach ${base}: ${(error as Error).message}`, undefined, error)
+  }
+  if (response.status < 200 || response.status >= 400) throw new BackendError(`gateway login rejected credentials at ${base}`, response.status)
+  const headers = response.headers as Headers & { getSetCookie?: () => string[] }
+  const cookies = headers.getSetCookie?.() ?? [response.headers.get('set-cookie') ?? '']
+  const cookie = cookies.map((value) => value.split(';', 1)[0]).find(Boolean)
+  if (!cookie) throw new BackendError(`gateway login at ${base} did not return an authorization cookie`, response.status)
+  return cookie
+}
+
 // the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
 // is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
 async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
-  const base = await apiBase()
-  try {
-    return await fetch(`${base}${path}`, init)
-  } catch (e) {
-    throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${(e as Error).message})`)
+  const target = await apiBaseInfo()
+  const base = target.url
+  prepareTls(base)
+  const request = async (cookie?: string): Promise<Response> => {
+    try {
+      return await fetch(`${base}${path}`, cookie ? withCookie(init, cookie) : init)
+    } catch (error) {
+      throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${(error as Error).message})`, undefined, error)
+    }
   }
+  const existing = gatewayCookie?.base === base ? gatewayCookie.value : undefined
+  const response = await request(existing)
+  if (response.status !== 401) return response
+  if (existing) throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401)
+  const password = passwordFor(target)
+  if (!password) throw new BackendError(`authentication required at ${base} — pass --password <pw> or set SPEXCODE_PASSWORD`, 401)
+  const cookie = await loginGateway(base, password)
+  gatewayCookie = { base, value: cookie }
+  const retried = await request(cookie)
+  if (retried.status === 401) throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401)
+  return retried
+}
+
+export function backendConnectionRefused(error: unknown): boolean {
+  if (!(error instanceof BackendError)) return false
+  let current = error.transport
+  let sawRefusal = false
+  const seen = new Set<unknown>()
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current)
+    const code = (current as NodeJS.ErrnoException).code
+    if (code && code !== 'ECONNREFUSED') return false
+    if (code === 'ECONNREFUSED') sawRefusal = true
+    current = (current as { cause?: unknown }).cause
+  }
+  return sawRefusal
 }
 // every MUTATING verb is project-bound ([[remote-client]]'s write guard): resolve the backend, compare its
 // served root to the cwd project, refuse loudly on a same-host mismatch — an explicit --api/--port skips it.
@@ -41,7 +128,7 @@ function cachedStatus(rec: ReturnType<typeof fromRaw>): DisplayStatus {
 function corruptCachedSession(id: string, reason: string): Session {
   const label = `${id.slice(0, 8)} (unreadable record)`
   return {
-    id, node: null, branch: null, path: '', label, headline: label, raw: { name: null, title: null },
+    id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
     parent: null, harness: 'unknown', capabilities: { headless: false }, launcher: null,
     lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
     note: `session record is unreadable: ${reason}`, archived: false, archiveHazard: null,
@@ -211,10 +298,14 @@ export async function clientEvals(id: string): Promise<EvalsResult> {
   throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`)
 }
 
-// POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
-export async function clientMerge(id: string): Promise<{ dispatched: boolean; reason?: string }> {
+// POST /api/sessions/:id/merge — the cockpit's merge DISPATCH. The caller returns the exact pair it just
+// reviewed and one durable request key; the backend accepts that decision once before ensuring the agent live.
+export async function clientMerge(id: string, options: { expectedBranchHead: string; expectedBaseHead: string; requestKey: string }): Promise<{ dispatched: boolean; replayed?: boolean; expectedBranchHead?: string; expectedBaseHead?: string; reason?: string; code?: string }> {
   await guarded('merge')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, post({}))
+  const headers: Record<string, string> = { 'content-type': 'application/json', 'Idempotency-Key': options.requestKey }
+  const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, {
+    method: 'POST', headers, body: JSON.stringify({ expectedBranchHead: options.expectedBranchHead, expectedBaseHead: options.expectedBaseHead }),
+  })
   return await r.json().catch(() => ({ dispatched: false, reason: `bad backend response (${r.status})` }))
 }
 
@@ -245,10 +336,11 @@ export async function clientInterrupt(id: string): Promise<DispatchResult> {
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` })) as DispatchResult
 }
 
-// POST /api/sessions/:id/close — the human-only worktree removal. {ok:false} = no such session.
+// POST /api/sessions/:id/close — terminal worktree removal. A client-side session id is only an unverified claim.
 export async function clientClose(id: string): Promise<boolean> {
   await guarded('session close')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({}))
+  const source = envSessionId()
+  const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({ source: source ? { kind: 'unverified-session-claim', id: source } : { kind: 'user' } }))
   if (!r.ok) throw new BackendError(`backend refused to close ${id}: ${await r.text()}`, r.status)
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
@@ -291,6 +383,13 @@ export async function clientRename(id: string, name: string): Promise<boolean> {
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
+export async function clientReparent(children: string[], parent: string): Promise<import('./sessions.js').SessionReparentResult> {
+  await guarded('session reparent')
+  const r = await apiFetch('/api/sessions/reparent', post({ children, parent }))
+  if (!r.ok) throw new BackendError(`backend refused to reparent sessions: ${await r.text()}`, r.status)
+  return await r.json() as import('./sessions.js').SessionReparentResult
+}
+
 // POST /api/sessions/:id/input {kind:"keys"} — the LAST-RESORT raw nav-key face of send (tmux send-keys,
 // NEVER the prompt socket): an ordered token batch drives an interactive TUI menu
 // ([[nav-mode-key-ordering]]). {ok:false} = unknown session, no live pane, or no valid token delivered.

package/spec-cli/src/codex-runtime-generations.ts

@@ -3,7 +3,7 @@ import { createConnection, type Socket } from 'node:net'
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { processStartToken, verifyDetachedRuntime } from './process-identity.js'
+import { detachedRuntimeIsGone, processStartToken, verifyDetachedRuntime } from './process-identity.js'
 
 export type CodexGenerationEndpoint = Readonly<{
   id: string
@@ -271,6 +271,32 @@ function hasLegacyResidue(root: string): boolean {
   return [endpoint.pidFile, endpoint.receiptFile, endpoint.socketPath].some(existsSync)
 }
 
+// A generation whose recorded process is provably gone — the host restarted, the OOM killer fired, a /tmp sweep
+// took the socket with it. Death is a POSITIVE fact, not the absence of proof: such a root holds no threads, no
+// peers, and no protective references, so nothing it once carried can be lost by retiring it. Everything else
+// that fails `endpointIdentity` is AMBIGUOUS — a live process we can no longer address — and keeps its root.
+function goneGeneration(endpoint: CodexGenerationEndpoint): boolean {
+  if (endpointIdentity(endpoint)) return false
+  let pid: number
+  try { pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim()) }
+  catch { return false }
+  return Number.isInteger(pid) && pid > 0 && detachedRuntimeIsGone(pid, endpoint.receiptFile)
+}
+
+// Retire a gone generation inside the caller's ledger lock, returning the published ledger (null when the
+// generation is still there to serve or merely unaddressable). Its bindings deliberately survive: a session's
+// conversation lives in Codex's on-disk rollout, so those rows are stale pointers to re-pin, not lost threads.
+function retireGoneGenerationLocked(root: string, previous: CodexGenerationLedger, id: string): CodexGenerationLedger | null {
+  const generation = previous.generations[id]
+  if (!generation || generation.state === 'reclaimed' || !goneGeneration(generation.endpoint)) return null
+  return writeLedger(root, previous, {
+    current: previous.current === id ? null : previous.current,
+    pending: previous.pending === id ? null : previous.pending,
+    generations: { ...previous.generations, [id]: { state: 'reclaimed', endpoint: generation.endpoint } },
+    bindings: previous.bindings,
+  })
+}
+
 function bootstrapBindings(root: string, generationId: string): Record<string, CodexGenerationBinding> {
   const result: Record<string, CodexGenerationBinding> = {}
   const sessions = join(root, 'sessions')
@@ -305,13 +331,18 @@ function bindingProtectsGeneration(root: string, sessionId: string, binding: Cod
 function bootstrapLedger(root: string): CodexGenerationLedger {
   const legacy = legacyCodexGenerationEndpoint(root)
   if (!hasLegacyResidue(root)) return emptyLedger()
-  if (!endpointIdentity(legacy)) throw new Error('legacy Codex root is present but its exact detached PID/start/receipt/socket identity is unproven')
+  // Residue left by a legacy root that has since died enters the ledger already reclaimed rather than blocking
+  // the bootstrap: it has nothing to drain. Its governed bindings are still recorded so those sessions resolve
+  // to a stale pointer they can re-pin, instead of losing the thread they own.
+  const gone = goneGeneration(legacy)
+  if (!gone && !endpointIdentity(legacy))
+    throw new Error('legacy Codex root is present but its exact detached PID/start/receipt/socket identity is unproven')
   return {
     version: 3,
     revision: 0,
     current: null,
     pending: null,
-    generations: { [legacy.id]: { state: 'draining', endpoint: legacy } },
+    generations: { [legacy.id]: { state: gone ? 'reclaimed' : 'draining', endpoint: legacy } },
     bindings: bootstrapBindings(root, legacy.id),
   }
 }
@@ -373,9 +404,13 @@ export async function ensureCodexCurrentGeneration(root: string, start: (endpoin
       }
       if (previous.current) {
         const generation = previous.generations[previous.current]
-        if (!generation || generation.state !== 'current' || !endpointIdentity(generation.endpoint))
-          throw new Error('canonical Codex generation is missing, replaced, or unproven; refusing to route new traffic')
-        return { kind: 'current', endpoint: generation.endpoint }
+        if (generation && generation.state === 'current' && endpointIdentity(generation.endpoint))
+          return { kind: 'current', endpoint: generation.endpoint }
+        // A canonical root that is provably gone is retired here and replaced by the rest of this same call:
+        // refusing forever would make one host restart permanently un-routable. Anything else stays a refusal.
+        const healed = retireGoneGenerationLocked(root, previous, previous.current)
+        if (!healed) throw new Error('canonical Codex generation is missing, replaced, or unproven; refusing to route new traffic')
+        previous = healed
       }
       if (previous.pending) {
         const pending = previous.generations[previous.pending]
@@ -491,12 +526,67 @@ export function prepareCodexGenerationClose(root: string, sessionId: string, thr
     if (!binding || binding.threadId !== threadId) throw new Error(`Codex session ${sessionId} has no exact generation binding to close`)
     if (binding.phase === 'record-removing') return
     const generation = previous.generations[binding.generationId]
-    if (!generation || generation.state === 'reclaimed') throw new Error(`Codex session ${sessionId} binding names an absent or reclaimed generation`)
+    // A retired root can neither route this thread nor be pinned by it, so there is nothing for the removal
+    // marker to protect: drop the binding outright and let close proceed. An ABSENT generation is corruption.
+    if (!generation) throw new Error(`Codex session ${sessionId} binding names an absent generation`)
+    if (generation.state === 'reclaimed') {
+      const remaining = { ...previous.bindings }
+      delete remaining[sessionId]
+      writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings: remaining })
+      return
+    }
     const bindings = { ...previous.bindings, [sessionId]: { ...binding, phase: 'record-removing' as const } }
     writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings })
   })
 }
 
+// Re-pin an existing exact binding onto another live generation. The transaction phase is carried over, so a
+// registration or close that is mid-flight keeps its crash boundary while its route is corrected.
+export function repinCodexGeneration(root: string, sessionId: string, threadId: string, generationId: string): void {
+  withLedgerLockSync(root, () => {
+    const previous = readCodexGenerationLedger(root)
+    const binding = previous.bindings[sessionId]
+    if (!binding || binding.threadId !== threadId) throw new Error(`Codex session ${sessionId} has no exact binding to re-pin`)
+    const generation = previous.generations[generationId]
+    if (!generation || generation.state === 'reclaimed') throw new Error(`Codex generation ${generationId} is absent or reclaimed`)
+    if (binding.generationId === generationId) return
+    const bindings = { ...previous.bindings, [sessionId]: { ...binding, generationId } }
+    writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings })
+  })
+}
+
+// The resume boundary. A binding to a LIVE generation still routes only there — an existing conversation is
+// never moved out from under the client that holds it. But a binding whose root is gone names a process, not a
+// conversation: the thread's durable home is its on-disk rollout, which any generation can load. So the gone
+// root is retired and the session is re-pinned to the canonical one, which loads that same rollout. Missing,
+// mismatched, ambiguous, or unprotected bindings remain refusals — resume never invents a route.
+export async function resolveCodexGenerationForResume(
+  root: string,
+  sessionId: string,
+  threadId: string,
+  start: (endpoint: CodexGenerationEndpoint) => Promise<void>,
+): Promise<CodexGenerationEndpoint | null> {
+  const ledger = readCodexGenerationLedger(root)
+  const binding = ledger.bindings[sessionId]
+  if (!binding || binding.threadId !== threadId || !bindingProtectsGeneration(root, sessionId, binding)) return null
+  const generation = ledger.generations[binding.generationId]
+  if (!generation) return null
+  if (generation.state !== 'reclaimed') {
+    if (endpointIdentity(generation.endpoint)) return generation.endpoint
+    const retired = await withLedgerLock(root, async () => {
+      const previous = readCodexGenerationLedger(root)
+      if (previous.bindings[sessionId]?.generationId !== binding.generationId) return false
+      const observed = previous.generations[binding.generationId]
+      if (!observed) return false
+      return observed.state === 'reclaimed' || !!retireGoneGenerationLocked(root, previous, binding.generationId)
+    })
+    if (!retired) return null
+  }
+  const current = await ensureCodexCurrentGeneration(root, start)
+  repinCodexGeneration(root, sessionId, threadId, current.id)
+  return current
+}
+
 export function resolveCodexGenerationForSession(root: string, sessionId: string, threadId: string): CodexGenerationEndpoint | null {
   const ledger = readCodexGenerationLedger(root)
   const binding = ledger.bindings[sessionId]

package/spec-cli/src/commit-surgery.ts

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process'
 import { relative } from 'node:path'
 import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js'
 import { HARNESSES } from './harness.js'
+import { gitBinary } from './git.js'
 
 // GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
 // GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
@@ -9,7 +10,7 @@ import { HARNESSES } from './harness.js'
 // operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
 // index surgery is the one place the env is the point.
 const raw = (args: string[], input?: string): string =>
-  execFileSync('git', args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+  execFileSync(gitBinary(process.env), args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
 
 function inHead(p: string): boolean {
   try { raw(['cat-file', '-e', `HEAD:${p}`]); return true } catch { return false }

package/spec-cli/src/contract-filter.ts

@@ -1,9 +1,10 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync, existsSync } from 'node:fs'
+import { mkdirSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { execFileSync } from 'node:child_process'
-import { git } from './git.js'
+import { git, gitBinary } from './git.js'
 import { writeManagedBlock, removeManagedBlock } from './harness.js'
 import { encodeProject, runtimeRoot, treeSlotDir } from './layout.js'
+import { writeFileIfChanged } from './file-write.js'
 
 // the three field-sharpened edges this module owes ([[content-filter]]):
 //   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
@@ -20,20 +21,13 @@ function commonDirOf(proj: string): string {
 }
 const filterDir = (common: string) => join(common, 'spexcode')
 const shimPath = (common: string) => join(filterDir(common), 'contract-filter.sh')
-const blockPath = (common: string) => join(filterDir(common), 'contract-block.md')
 const rootPath = (common: string) => join(filterDir(common), 'contract-filter-root')
 const bindingsPath = (common: string) => join(filterDir(common), 'contract-filter-bindings')
 const treeFilterDir = (proj: string) => join(treeSlotDir(proj), 'contract-filter')
 const attributesPath = (common: string) => join(common, 'info', 'attributes')
 
-const registeredSlots = (proj: string) => git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0')
-  .filter((row) => row.startsWith('worktree ')).map((row) =>
-    join(runtimeRoot(proj), 'trees', encodeProject(row.slice('worktree '.length))))
-const legacyFilterTree = (proj: string) => registeredSlots(proj)
-  .some((slot) => existsSync(join(slot, 'content-hash')) && !existsSync(join(slot, 'contract-filter-v2')))
-
 export type ContractFilterPayload = { file: string; content: string }
-export type ContractFilterBinding = { file: string; start: string; end: string; legacy?: boolean }
+export type ContractFilterBinding = { file: string; start: string; end: string }
 
 // The common shim both filter directions run through. Pure shell/awk (no node boot on git's hot path), it
 // resolves the invoking checkout to that tree's payload before mirroring managed-block normalization:
@@ -48,19 +42,15 @@ set -u
 mode="\${1:?usage: contract-filter.sh smudge|clean <path>}"
 path="\${2:?usage: contract-filter.sh smudge|clean <path>}"
 here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3 "\t" $4; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
+binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
 [ -n "$binding" ] || { cat; exit 0; }
 start="\${binding%%$'\t'*}"; rest="\${binding#*$'\t'}"
-end="\${rest%%$'\t'*}"; legacy="\${rest#*$'\t'}"
+end="$rest"
 top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 root="$(cat "$here/contract-filter-root" 2>/dev/null || true)"
 key="$(printf '%s' "$top" | sed 's#[/.]#-#g')"
 manifest="$root/trees/$key/contract-filter/manifest"
 payload="$(awk -F '\t' -v p="$path" '$1 == p { print $2; exit }' "$manifest" 2>/dev/null)"
-# A pre-v2 tree has only the old common payload. Once that tree materializes, its marker makes a missing
-# per-file payload mean identity (for example, AGENTS.md in a Claude-only tree), never global fallback.
-marker="$root/trees/$key/contract-filter-v2"
-if [ ! -r "$payload" ] && [ ! -f "$marker" ] && [ "$legacy" = 1 ] && [ -r "$here/contract-block.md" ]; then payload="$here/contract-block.md"; fi
 strip() {
   awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
     { lines[n++] = $0 }
@@ -105,33 +95,54 @@ const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
 
 // plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
 // pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
-// binding each file to the filter. Idempotent — every write is a full replace. `contract` is the assembled
-// block body (guide + surface:system). settleIndexStat skips untracked entries (no index blob) by design.
-export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[]): void {
+// binding each file to the filter. `contract` is the assembled block body (guide + surface:system).
+// settleIndexStat skips untracked entries (no index blob) by design and only runs after a real filter change.
+export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[], changedFiles: readonly string[] = []): boolean {
   const common = commonDirOf(proj)
   mkdirSync(filterDir(common), { recursive: true })
-  writeFileSync(shimPath(common), SHIM)
-  chmodSync(shimPath(common), 0o755)
-  git(['-C', proj, 'config', 'filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')])
-  git(['-C', proj, 'config', 'filter.spexcode.clean', filterCmd(shimPath(common), 'clean')])
-  writeFileSync(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}\t${b.legacy ? 1 : 0}`).join('\n') + '\n')
+  let changed = writeFileIfChanged(shimPath(common), SHIM)
+  if (changed || (statSync(shimPath(common)).mode & 0o777) !== 0o755) chmodSync(shimPath(common), 0o755)
+  const commands = new Map([
+    ['filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')],
+    ['filter.spexcode.clean', filterCmd(shimPath(common), 'clean')],
+  ])
+  const configured = new Map<string, string>()
+  try {
+    for (const row of git(['-C', proj, 'config', '--get-regexp', '^filter\\.spexcode\\.(smudge|clean)$']).trimEnd().split('\n')) {
+      const at = row.indexOf(' ')
+      if (at > 0) configured.set(row.slice(0, at), row.slice(at + 1))
+    }
+  } catch {}
+  for (const [key, command] of commands) {
+    if (configured.get(key) === command) continue
+    git(['-C', proj, 'config', key, command])
+    changed = true
+  }
+  changed = writeFileIfChanged(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}`).join('\n') + '\n') || changed
   const dir = treeFilterDir(proj)
-  rmSync(dir, { recursive: true, force: true }); mkdirSync(dir, { recursive: true })
+  mkdirSync(dir, { recursive: true })
   const manifest: string[] = []
+  const wanted = new Set(['manifest'])
   for (const [i, payload] of payloads.entries()) {
     const target = join(dir, String(i))
-    writeFileSync(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`)
+    wanted.add(String(i))
+    changed = writeFileIfChanged(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`) || changed
     manifest.push(`${payload.file}\t${target}`)
   }
+  for (const entry of readdirSync(dir)) {
+    if (!wanted.has(entry)) { rmSync(join(dir, entry), { recursive: true, force: true }); changed = true }
+  }
   const manifestPath = join(dir, 'manifest')
-  writeFileSync(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : ''))
-  writeFileSync(rootPath(common), `${runtimeRoot(proj)}\n`)
+  changed = writeFileIfChanged(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : '')) || changed
+  changed = writeFileIfChanged(rootPath(common), `${runtimeRoot(proj)}\n`) || changed
   // Attribute patterns are checkout-relative; the stable binding set is safe in the common git dir because
   // the driver selects a payload from the invoking checkout's tree slot.
   const entries = bindings.map((b) => `/${b.file} filter=spexcode`).sort().join('\n')
   mkdirSync(join(common, 'info'), { recursive: true })
-  writeManagedBlock(attributesPath(common), entries, ['# ', ''])
-  settleIndexStat(proj, payloads.map((p) => join(proj, p.file)))
+  changed = writeManagedBlock(attributesPath(common), entries, ['# ', '']) || changed
+  const settle = changed ? payloads.map((p) => join(proj, p.file)) : changedFiles
+  if (settle.length) settleIndexStat(proj, [...new Set(settle)])
+  return changed
 }
 
 // settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
@@ -150,7 +161,7 @@ export function settleIndexStat(proj: string, files: string[]): void {
     const rel = relative(proj, f)
     try {
       const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim()
-      const filtered = execFileSync('git', ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
+      const filtered = execFileSync(gitBinary(env), ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
         { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
       if (indexBlob === filtered) git(['-C', proj, 'add', '--renormalize', '--', rel])
     } catch { /* best-effort */ }
@@ -160,24 +171,29 @@ export function settleIndexStat(proj: string, files: string[]): void {
 // the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
 // config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
 // (evidence blobs), so only OUR two files go, never the dir.
+export function clearContractFilterPayload(proj: string, files: string[] = []): void {
+  try { rmSync(treeFilterDir(proj), { recursive: true, force: true }) } catch { /* inaccessible tree */ }
+  settleIndexStat(proj, files)
+}
+
 export function removeContractFilter(proj: string, files: string[] = [], final = false): void {
   let common: string
   try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted
-  try { rmSync(treeFilterDir(proj), { recursive: true, force: true }) } catch { /* inaccessible tree */ }
-  settleIndexStat(proj, files)
-  const anotherPayload = registeredSlots(proj).some((slot) => existsSync(join(slot, 'contract-filter', 'manifest')))
-  const legacyTree = legacyFilterTree(proj)
-  if (!legacyTree) rmSync(blockPath(common), { force: true })
-  if (!final && (anotherPayload || legacyTree)) return
+  clearContractFilterPayload(proj, files)
+  const anotherPayload = final ? false : (() => {
+    const rows = git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0')
+    const root = runtimeRoot(proj)
+    return rows
+      .filter((row) => row.startsWith('worktree '))
+      .map((row) => row.slice('worktree '.length))
+      .some((tree) => existsSync(join(root, 'trees', encodeProject(tree), 'contract-filter', 'manifest')))
+  })()
+  if (!final && anotherPayload) return
   removeManagedBlock(attributesPath(common), ['# ', ''], true)
   for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
     try { git(['-C', proj, 'config', '--unset-all', key]) } catch { /* not set — already clean */ }
   }
-  for (const path of [shimPath(common), blockPath(common), rootPath(common), bindingsPath(common)]) rmSync(path, { force: true })
-}
-
-export function retireLegacyContractBlock(proj: string): void {
-  if (!legacyFilterTree(proj)) rmSync(blockPath(commonDirOf(proj)), { force: true })
+  for (const path of [shimPath(common), rootPath(common), bindingsPath(common)]) rmSync(path, { force: true })
 }
 
 // is the filter currently planted? (the assert-side probe tests use; cheap: one config read)

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

@@ -8,9 +8,16 @@ import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
 // 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 }
+export type PendingMessage = {
+  mid: string
+  text: string
+  from: string | null
+  dispatch?: { operation: 'merge'; requestDigest: string }
+}
 
 const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
+const revokedSenderRoot = (): string => join(runtimeRoot(), '.revoked-senders')
+const revokedSenderPath = (id: string): string => join(revokedSenderRoot(), id)
 
 // @@@ 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
@@ -53,7 +60,10 @@ function read(id: string): PendingMessage[] {
     return raw.filter((m): m is PendingMessage =>
       !!m && typeof m === 'object'
       && typeof (m as PendingMessage).mid === 'string'
-      && typeof (m as PendingMessage).text === 'string')
+      && typeof (m as PendingMessage).text === 'string'
+      && ((m as PendingMessage).dispatch === undefined
+        || ((m as PendingMessage).dispatch?.operation === 'merge'
+          && typeof (m as PendingMessage).dispatch?.requestDigest === 'string')))
   } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
 }
 
@@ -68,17 +78,59 @@ function write(id: string, msgs: PendingMessage[]): void {
   renameSync(tmp, path)
 }
 
+// A closed sender may have left debt in many other sessions' queues. The marker is deliberately outside its
+// own store (which close removes) and is checked under the sender's record lock by dispatch: a close cannot
+// return while an old process can still append, and a later sweep cannot hand over what it sees here.
+export function revokeSenderDelivery(id: string): void {
+  mkdirSync(revokedSenderRoot(), { recursive: true })
+  writeFileSync(revokedSenderPath(id), `${id}\n`)
+}
+
+export const senderDeliveryRevoked = (id: string): boolean => existsSync(revokedSenderPath(id))
+
+export function pendingSnapshot(id: string): PendingMessage[] { return read(id) }
+
+// These two writes require the target's delivery lock. They are the queue half of a larger transaction
+// (currently reparent), which must be able to restore the exact previous debt if a later record write fails.
+export function replacePendingWhileLocked(id: string, msgs: PendingMessage[]): void { write(id, msgs) }
+export function revokePendingFromWhileLocked(id: string, sender: string): number {
+  const current = read(id)
+  const next = current.filter((msg) => msg.from !== sender)
+  write(id, next)
+  return current.length - next.length
+}
+
 // 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.
+// both, and the record is written first, so delivery is never unrecorded. A keyed dispatch also carries its
+// exact delivery bytes in the timeline receipt, letting its retry restore a queue write lost to a crash.
 export function enqueue(id: string, msg: PendingMessage): void {
   write(id, [...read(id), msg])
 }
 
+// Caller holds this target's delivery lock. A retry may reach this after either side of the receipt->queue
+// crash boundary; exact mid identity makes reconstruction idempotent without inspecting message text.
+export function ensurePendingWhileLocked(id: string, msg: PendingMessage): boolean {
+  const current = read(id)
+  if (current.some((pending) => pending.mid === msg.mid)) return false
+  write(id, [...current, msg])
+  return true
+}
+
 export const pendingMessages = (id: string): PendingMessage[] => read(id)
 
 export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
 
+// Record transitions and queue mutations take locks in the same direction: record locks first, then these
+// target queue locks. A batch reparent needs all child queues held at once so its pointer/watch/debt change
+// either commits together or restores together.
+export async function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index = 0, ids = [...new Set(rawIds)].sort()): Promise<T> {
+  if (index >= ids.length) return body()
+  const release = await acquire(ids[index], 30_000)
+  if (!release) throw new Error(`delivery queue ${ids[index]}: timed out waiting for transaction lock`)
+  try { return await withDeliveryLocks(ids, body, index + 1, ids) }
+  finally { release() }
+}
+
 // 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
@@ -95,6 +147,12 @@ export async function drain(
     for (;;) {
       const queued = read(id)
       if (!queued.length) return { delivered, remaining: 0 }
+      if (queued[0].from && senderDeliveryRevoked(queued[0].from)) {
+        // Closing a sender voids its undelivered output, not the recipient's immutable conversation history.
+        // Drop a revoked head and continue so it cannot permanently block the messages behind it.
+        write(id, read(id).filter((m) => m.mid !== queued[0].mid))
+        continue
+      }
       let ok = false
       try { ok = await insert(queued[0]) } catch { ok = false }
       if (!ok) return { delivered, remaining: queued.length }