spexcode 0.5.3 → 0.5.4

package/package.json

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

package/spec-cli/src/cli.ts

@@ -1006,10 +1006,10 @@ if (cmd === 'serve') {
     if (!owner) { console.error('maintenance_identity_unknown: hook dispatcher owner identity is not exact'); process.exit(2) }
     sessionMaintenance().finishExternalOperation(ticket, owner)
   } else if (sub === 'shared-runtime-spawn') {
-    const [cwd, logFile, pidFile, isolationFile, command] = process.argv.slice(4, 9)
+    const [cwd, logFile, pidFile, receiptFile, command] = process.argv.slice(4, 9)
     const args = process.argv.slice(9)
-    if (!cwd || !logFile || !pidFile || !isolationFile || !command) {
-      console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <isolation-file> <command> [args...]')
+    if (!cwd || !logFile || !pidFile || !receiptFile || !command) {
+      console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <receipt-file> <command> [args...]')
       process.exit(2)
     }
     const { readFileSync } = await import('node:fs')
@@ -1029,7 +1029,7 @@ if (cmd === 'serve') {
     delete env.SPEXCODE_MAINTENANCE_SESSION_ID
     delete env.SPEXCODE_SESSION_ID
     const runtime = await runSessionOperation({ op: 'shared-spawn', sessionId, ...(delegateChannelPresent ? { delegate } : {}) }, () =>
-      spawnDetachedRuntime({ cwd, logFile, pidFile, isolationFile, command, args, env }))
+      spawnDetachedRuntime({ cwd, logFile, pidFile, receiptFile, command, args, env }))
     console.log(runtime.pid)
   } else if (sub === 'codex-launch') {
     // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }

package/spec-cli/src/guide.ts

@@ -282,7 +282,8 @@ see LAUNCHERS.
 
 ── LAYOUT (spexcode.json — portable; set only for a NON-DEFAULT repo layout) ──
   main          path to the source-of-truth checkout. Default: the \`main\` worktree.
-  mainBranch    the source-of-truth BRANCH worktrees fork from. Default: auto-detected.
+  mainBranch    the stable source-of-truth BRANCH worktrees fork from. spex init stamps the root checkout's
+                branch at adoption; an older omitted value uses the conventional main.
   branchPrefix  how a node branch is named. Default "node/".
 Example — a repo whose trunk is \`staging\`, not \`main\`:
   { "mainBranch": "staging" }

package/spec-cli/src/harness.ts

@@ -16,7 +16,7 @@ import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from '.
 import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from './layout.js'
 import { git } from './git.js'
 import { shQuote } from './sh.js'
-import { processStartToken, processTopology } from './process-identity.js'
+import { detachedRuntimeGenerationToken, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -53,13 +53,13 @@ export type SharedRuntimeDescriptor = {
   key: string
   label: string
   pidFile: string
-  isolationFile: string
+  receiptFile: string
   // Lightweight project-wide resident census used by read projections. It must return exact loaded IDs without
   // per-thread reads; the full probe remains the resource/lifecycle surface that also reads turn state.
   residency?: () => Promise<{ healthy: boolean; referenceIds: string[]; error?: string; rootAbsent?: boolean }>
   // Lifecycle mutation guard is deliberately narrower than the full resource projection: census every loaded
   // ID, but read only the exact governed target when it is loaded, plus both target descendant collections.
-  mutationGuard?: (targetReferenceId: string) => Promise<SharedRuntimeMutationGuard>
+  mutationGuard?: (targetReferenceId: string, opts?: { coldReceipt?: unknown }) => Promise<SharedRuntimeMutationGuard>
   probe(): Promise<SharedRuntimeProbe>
 }
 export type SharedRuntimeMutationGuard = {
@@ -67,6 +67,7 @@ export type SharedRuntimeMutationGuard = {
   referenceIds: string[]
   targetTurnPresence: 'none' | 'idle' | 'active' | 'unknown'
   descendantIds: string[]
+  coldTeardownAuthorized?: boolean
   error?: string
 }
 export type SharedRuntimeProbe = {
@@ -79,6 +80,10 @@ export type SharedRuntimeProbe = {
   error?: string
 }
 
+export type HarnessColdPreflight =
+  | { ok: true; alreadyCold?: boolean; receipt?: unknown }
+  | { ok: false; reason: string }
+
 export type AdapterLoadedReferenceState = {
   healthy: boolean
   loaded: boolean
@@ -273,14 +278,16 @@ export interface Harness {
   cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>
   // Archive preflight runs BEFORE any leaf signal. It may inspect shared references to refuse an active or
   // unknown target turn, but it must not mutate the shared runtime; coldRuntime is the sole commit primitive.
-  coldPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true; alreadyCold?: boolean } | { ok: false; reason: string }>
+  // Its optional receipt is opaque adapter authority: product code may only pass the same object back to the
+  // stop guard and coldRuntime, never inspect it or synthesize a recursive/archive mode.
+  coldPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<HarnessColdPreflight>
   // A record that is already archived needs a target-only continuing-cold proof. Unlike mutation preflight,
   // this must not thread/read unrelated loaded siblings merely to retire a target whose runtime is absent.
   coldRetirementPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true; alreadyCold: true } | { ok: false; reason: string }>
   // Optional cold-storage proof/cleanup. A harness with a per-session loaded reference must remove exactly that
   // reference or return a loud reason; adapters without such a resident reference return {ok:true}.
-  coldRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true } | { ok: false; reason: string }>
-  restoreRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true } | { ok: false; reason: string }>
+  coldRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }, receipt?: unknown): Promise<{ ok: true } | { ok: false; reason: string }>
+  restoreRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }, receipt?: unknown): Promise<{ ok: true } | { ok: false; reason: string }>
   // Project-scoped runtimes are adapter facts. Resource governance consumes these descriptors to report
   // references and protect a sibling-owned control plane without learning harness command names.
   sharedRuntimes?(runtimeDir: string): readonly SharedRuntimeDescriptor[]
@@ -422,37 +429,26 @@ export const codexAppServerSock = (dir = runtimeRoot()) => {
   return join(base, `spexcode-cx-${createHash('sha1').update(dir).digest('hex').slice(0, 16)}.sock`)
 }
 export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid')
-export const codexAppServerIsolation = (dir = runtimeRoot()) => join(dir, 'codex-app-server.scope')
+export const codexAppServerReceipt = (dir = runtimeRoot()) => join(dir, 'codex-app-server.detached.json')
 type CodexRuntimeGenerationProof = Readonly<{
-  pid: number
-  startToken: string
-  processGroupId: number
-  sessionId: number
-  isolation: string
+  identity: VerifiedDetachedRuntime
   socket: Readonly<{ path: string; dev: number; ino: number }>
 }>
 function codexRuntimeGenerationProof(dir = runtimeRoot()): CodexRuntimeGenerationProof | null {
   try {
     const pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim())
-    const start = processStartToken(pid)
-    const scope = readFileSync(codexAppServerIsolation(dir), 'utf8').trim()
-    const topology = processTopology(pid)
+    const detached = verifyDetachedRuntime(pid, codexAppServerReceipt(dir))
     const socketPath = codexAppServerSock(dir)
     const socket = statSync(socketPath)
-    if (!(pid > 0) || !start || !topology || topology.startToken !== start || topology.processGroupId !== pid || topology.sessionId !== pid ||
-      scope !== `detached-v3 ${pid} ${start} ${pid} ${pid}` || !socket.isSocket()) return null
+    if (!(pid > 0) || !detached.ok || !socket.isSocket()) return null
     return Object.freeze({
-      pid,
-      startToken: start,
-      processGroupId: topology.processGroupId,
-      sessionId: topology.sessionId,
-      isolation: scope,
+      identity: detached.identity,
       socket: Object.freeze({ path: socketPath, dev: socket.dev, ino: socket.ino }),
     })
   } catch { return null }
 }
 const codexRuntimeGenerationToken = (proof: CodexRuntimeGenerationProof) =>
-  `${proof.pid}|${proof.startToken}|${proof.processGroupId}|${proof.sessionId}|${proof.isolation}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`
+  `${detachedRuntimeGenerationToken(proof.identity)}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`
 function codexRuntimeGeneration(dir = runtimeRoot()): string | null {
   const proof = codexRuntimeGenerationProof(dir)
   return proof ? codexRuntimeGenerationToken(proof) : null
@@ -673,14 +669,14 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
   const tuiBypass = !codexCmd.includes('--dangerously-bypass-hook-trust') && codexSupportsBypassHookTrust(codexBinary(codexCmd)) ? ' --dangerously-bypass-hook-trust' : ''
   const sock = codexAppServerSock(dir)         // short sun_path-safe path in the owned tmp subdir/override — NOT under "$dir"
   const pid = codexAppServerPid(dir)
-  const isolation = codexAppServerIsolation(dir)
+  const receipt = codexAppServerReceipt(dir)
   const log = join(dir, 'codex-app-server.log')
   const lock = join(dir, 'codex-app-server.lock')
   const script = [
     `dir=${shQuote(dir)}`,
     `sock=${shQuote(sock)}`,
     `pid=${shQuote(pid)}`,
-    `isolation=${shQuote(isolation)}`,
+    `receipt=${shQuote(receipt)}`,
     `log=${shQuote(log)}`,
     `lock=${shQuote(lock)}`,
     // codex-launch's bypass-trust gate (and writeTrust's) resolves the codex binary from SPEXCODE_CODEX_CMD;
@@ -724,10 +720,10 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
     // mis-attributes; the id it needs — the ACTING thread's — codex injects per command, so stripping the
     // inherited ones removes a wrong answer without removing a right one ([[harness-adapter]]).
     // The adapter launches its shared control plane in a new OS process group + session. `nohup` alone was not
-    // a boundary: the Codex Node launcher reset signal handling and died with the tmux pane despite a matching
-    // stamp. The internal helper uses child_process detached=true, records PID/start plus the observed pgrp/sid,
-    // and refuses unless the live process is its own session leader. The stop guard re-reads that topology.
-    `  ( unset ${sessionIdentityEnvVars().join(' ')}; ${SPEX} internal shared-runtime-spawn "$dir" "$log" "$pid" "$isolation" ${server} app-server --listen "unix://$sock" ) || { rmdir "$lockd" 2>/dev/null; exit 1; }`,
+    // a boundary: the Codex Node launcher reset signal handling and died with the tmux pane. The internal helper
+    // uses child_process detached=true, then the process adapter publishes a private receipt only after proving
+    // exact PID/start + PGID (and Linux SID). Every consumer re-verifies that same receipt.
+    `  ( unset ${sessionIdentityEnvVars().join(' ')}; ${SPEX} internal shared-runtime-spawn "$dir" "$log" "$pid" "$receipt" ${server} app-server --listen "unix://$sock" ) || { rmdir "$lockd" 2>/dev/null; exit 1; }`,
     '  for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
     'fi',
     'rmdir "$lockd" 2>/dev/null',
@@ -890,7 +886,14 @@ export const CODEX_THREAD_SOURCE_KINDS = [
   'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview', 'subAgentCompact',
   'subAgentThreadSpawn', 'subAgentOther', 'unknown',
 ] as const
-function codexPagedIds(sock: string, method: 'thread/list' | 'thread/loaded/list', params: Record<string, unknown>, extractId: (item: unknown) => string | null, label: string): Promise<CodexPagedIdsResult> {
+function codexPagedIds(
+  sock: string,
+  method: 'thread/list' | 'thread/loaded/list',
+  params: Record<string, unknown>,
+  extractId: (item: unknown) => string | null,
+  label: string,
+  onItem?: (item: unknown) => void,
+): Promise<CodexPagedIdsResult> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
@@ -914,6 +917,7 @@ function codexPagedIds(sock: string, method: 'thread/list' | 'thread/loaded/list
       if (message.id !== requestId || !message.result) return
       const page = message.result as { data?: unknown; nextCursor?: unknown }
       if (Array.isArray(page.data)) for (const item of page.data) {
+        onItem?.(item)
         const id = extractId(item)
         if (typeof id === 'string') ids.add(id)
       }
@@ -992,14 +996,35 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
 // The app-server's loaded/list is cursor-paginated. Archive proof must scan every page; a first page that omits
 // a sibling/descendant is not a cold proof. This helper is also used by the descendant guard below.
 export function codexThreadList(sock: string, params: Record<string, unknown>): Promise<{ ok: true; ids: string[] } | { ok: false; error: string }> {
+  return codexThreadCollection(sock, params).then((result) => result.ok ? { ok: true, ids: result.ids } : result)
+}
+
+type CodexThreadCollectionResult =
+  | { ok: true; ids: string[]; parentById: Map<string, string | null> }
+  | { ok: false; error: string }
+
+function codexThreadCollection(sock: string, params: Record<string, unknown>): Promise<CodexThreadCollectionResult> {
   const sourceKinds = Array.isArray(params.sourceKinds) && params.sourceKinds.length
     ? params.sourceKinds
     : [...CODEX_THREAD_SOURCE_KINDS]
+  const parentById = new Map<string, string | null>()
+  const conflictingParents = new Set<string>()
   return codexPagedIds(sock, 'thread/list', { ...params, sourceKinds, useStateDbOnly: true }, (item) => {
     if (typeof item === 'string') return item
     const id = (item as { id?: unknown } | null)?.id
     return typeof id === 'string' ? id : null
-  }, 'thread/list')
+  }, 'thread/list', (item) => {
+    if (!item || typeof item !== 'object') return
+    const row = item as { id?: unknown; parentThreadId?: unknown }
+    if (typeof row.id !== 'string') return
+    const parent = typeof row.parentThreadId === 'string' ? row.parentThreadId : null
+    if (parentById.has(row.id) && parentById.get(row.id) !== parent) conflictingParents.add(row.id)
+    parentById.set(row.id, parent)
+  }).then((result) => {
+    if (!result.ok) return result
+    if (conflictingParents.size) return { ok: false as const, error: `Codex thread/list returned conflicting parent ownership for ${[...conflictingParents].join(', ')}` }
+    return { ...result, parentById }
+  })
 }
 
 async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()): Promise<SharedRuntimeMutationGuard> {
@@ -1029,28 +1054,194 @@ async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()):
   return { healthy: true, referenceIds, targetTurnPresence, descendantIds }
 }
 
-type CodexColdPreflight = { ok: true; alreadyCold?: boolean; guard: SharedRuntimeMutationGuard } | { ok: false; reason: string }
-async function codexColdPreflight(threadId: string, dir = runtimeRoot()): Promise<CodexColdPreflight> {
+const CODEX_COLD_PLAN = Symbol('codex-cold-plan')
+type CodexColdPlan = Readonly<{
+  [CODEX_COLD_PLAN]: true
+  kind: 'codex-cold-subtree-v1'
+  threadId: string
+  generation: string
+  guard: SharedRuntimeMutationGuard
+  descendantIds: readonly string[]
+  parentEdges: readonly (readonly [string, string])[]
+  subtreeIds: readonly string[]
+  activeIds: readonly string[]
+  archivedIds: readonly string[]
+}>
+type CodexColdPreflight = { ok: true; alreadyCold?: boolean; receipt: CodexColdPlan } | { ok: false; reason: string }
+
+const sameIdSet = (left: readonly string[], right: readonly string[]) =>
+  left.length === right.length && left.every((id) => right.includes(id))
+
+const sameParentEdges = (left: readonly (readonly [string, string])[], right: readonly (readonly [string, string])[]) =>
+  left.length === right.length && left.every(([id, parent]) => right.some(([otherId, otherParent]) => id === otherId && parent === otherParent))
+
+const isCodexColdPlan = (value: unknown): value is CodexColdPlan => {
+  if (!value || typeof value !== 'object') return false
+  const plan = value as Partial<CodexColdPlan>
+  return plan[CODEX_COLD_PLAN] === true && plan.kind === 'codex-cold-subtree-v1' && typeof plan.threadId === 'string' &&
+    typeof plan.generation === 'string' && Array.isArray(plan.descendantIds) &&
+    Array.isArray(plan.parentEdges) && Array.isArray(plan.subtreeIds) &&
+    Array.isArray(plan.activeIds) && Array.isArray(plan.archivedIds) && !!plan.guard
+}
+
+async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string): Promise<CodexColdPreflight> {
+  const generation = expectedGeneration ?? codexRuntimeGeneration(dir)
+  if (!generation || codexRuntimeGeneration(dir) !== generation)
+    return { ok: false, reason: 'Codex shared app-server generation is unproven or changed before subtree census' }
   const sock = codexAppServerSock(dir)
-  const [guard, archivedList, activeList] = await Promise.all([
-    codexTargetMutationGuard(threadId, dir),
+  const [loaded, activeDescendants, archivedDescendants, archivedList, activeList] = await Promise.all([
+    codexLoadedReferenceIds(sock),
+    codexThreadCollection(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
+    codexThreadCollection(sock, { ancestorThreadId: threadId, archived: true, sourceKinds: [] }),
     codexThreadList(sock, { archived: true, sourceKinds: [] }),
     codexThreadList(sock, { archived: false, sourceKinds: [] }),
   ])
-  if (guard.descendantIds.length)
-    return { ok: false, reason: `Codex thread ${threadId} has owned descendants (${guard.descendantIds.join(', ')}); subtree archive is not proven safe` }
-  if (!guard.healthy) return { ok: false, reason: guard.error || `Codex thread ${threadId} target state is unknown` }
+  if (codexRuntimeGeneration(dir) !== generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed during subtree census' }
+  if (!loaded.ok) return { ok: false, reason: loaded.error }
+  if (!activeDescendants.ok) return { ok: false, reason: activeDescendants.error }
+  if (!archivedDescendants.ok) return { ok: false, reason: archivedDescendants.error }
   if (!archivedList.ok) return { ok: false, reason: archivedList.error }
   if (!activeList.ok) return { ok: false, reason: activeList.error }
-  const inArchived = archivedList.ids.includes(threadId)
-  const inActive = activeList.ids.includes(threadId)
-  if (inArchived === inActive) return { ok: false, reason: `Codex thread ${threadId} has ambiguous disk collection state (archived=${inArchived}, active=${inActive})` }
-  if (guard.targetTurnPresence === 'active') return { ok: false, reason: `Codex thread ${threadId} has an active turn; terminal-state confirmation is required before archive` }
-  if (guard.targetTurnPresence === 'unknown') return { ok: false, reason: `Codex thread ${threadId} turn state is unknown; refusing to archive without terminal-state confirmation` }
-  if (guard.targetTurnPresence === 'none')
-    return inArchived ? { ok: true, alreadyCold: true, guard } : { ok: true, guard }
-  if (inArchived) return { ok: false, reason: `Codex thread ${threadId} is archived but remains loaded` }
-  return { ok: true, guard }
+
+  const activeDescendantSet = new Set(activeDescendants.ids)
+  const archivedDescendantSet = new Set(archivedDescendants.ids)
+  const duplicateDescendants = activeDescendants.ids.filter((id) => archivedDescendantSet.has(id))
+  if (duplicateDescendants.length)
+    return { ok: false, reason: `Codex subtree members occur in both active and archived descendant collections (${duplicateDescendants.join(', ')})` }
+  const descendantIds = [...activeDescendants.ids, ...archivedDescendants.ids]
+  if (descendantIds.includes(threadId)) return { ok: false, reason: `Codex target ${threadId} is duplicated in its own descendant closure` }
+
+  const parentById = new Map([...activeDescendants.parentById, ...archivedDescendants.parentById])
+  const depthById = new Map<string, number>()
+  for (const id of descendantIds) {
+    const seen = new Set([id])
+    let cursor = id
+    let depth = 0
+    while (cursor !== threadId) {
+      const next = parentById.get(cursor)
+      if (!next) return { ok: false, reason: `Codex descendant ${id} has no complete parent chain to target ${threadId} (unowned or reassigned)` }
+      if (seen.has(next)) return { ok: false, reason: `Codex descendant ${id} has a cyclic parent chain` }
+      seen.add(next)
+      cursor = next
+      depth++
+    }
+    depthById.set(id, depth)
+  }
+
+  const activeSet = new Set(activeList.ids)
+  const archivedSet = new Set(archivedList.ids)
+  const subtreeIds = [...descendantIds, threadId]
+  for (const id of subtreeIds) {
+    const inActive = activeSet.has(id)
+    const inArchived = archivedSet.has(id)
+    if (!inActive && !inArchived)
+      return { ok: false, reason: `Codex subtree member ${id} is absent from both native collections (unowned or reassigned)` }
+    if (inActive && inArchived)
+      return { ok: false, reason: `Codex subtree member ${id} occurs in both active and archived native collections` }
+    if (id !== threadId) {
+      const expectedActive = activeDescendantSet.has(id)
+      if (inActive !== expectedActive)
+        return { ok: false, reason: `Codex subtree member ${id} changed collection assignment during ownership census` }
+    }
+  }
+
+  const loadedSet = new Set(loaded.referenceIds)
+  const loadedSubtreeIds = subtreeIds.filter((id) => loadedSet.has(id))
+  const turnStates = await Promise.all(loadedSubtreeIds.map(async (id) => ({ id, state: await codexTargetTurnPresence(sock, id) })))
+  if (codexRuntimeGeneration(dir) !== generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed during subtree turn census' }
+  for (const { id, state } of turnStates) {
+    if (!state.ok) return { ok: false, reason: state.error }
+    if (state.turnPresence === 'active') return { ok: false, reason: `Codex subtree member ${id} has an active turn` }
+    if (state.turnPresence === 'unknown') return { ok: false, reason: `Codex subtree member ${id} turn state is unknown` }
+    if (archivedSet.has(id)) return { ok: false, reason: `Codex archived subtree member ${id} remains loaded` }
+  }
+
+  const targetTurnPresence: SharedRuntimeMutationGuard['targetTurnPresence'] = loadedSet.has(threadId) ? 'idle' : 'none'
+  const guard: SharedRuntimeMutationGuard = {
+    healthy: true,
+    referenceIds: [...loaded.referenceIds],
+    targetTurnPresence,
+    descendantIds: [...descendantIds],
+  }
+  const activeIds = [...activeDescendants.ids]
+    .sort((left, right) => (depthById.get(right) ?? 0) - (depthById.get(left) ?? 0))
+    .concat(activeSet.has(threadId) ? [threadId] : [])
+  const archivedIds = [...archivedDescendants.ids, ...(archivedSet.has(threadId) ? [threadId] : [])]
+  const parentEdges = descendantIds.map((id) => [id, parentById.get(id)!] as const)
+  const receipt: CodexColdPlan = Object.freeze({
+    [CODEX_COLD_PLAN]: true as const,
+    kind: 'codex-cold-subtree-v1',
+    threadId,
+    generation,
+    guard,
+    descendantIds: Object.freeze([...descendantIds]),
+    parentEdges: Object.freeze(parentEdges),
+    subtreeIds: Object.freeze([...subtreeIds]),
+    activeIds: Object.freeze(activeIds),
+    archivedIds: Object.freeze(archivedIds),
+  })
+  return { ok: true, ...(activeIds.length ? {} : { alreadyCold: true }), receipt }
+}
+
+async function codexMutationGuard(
+  threadId: string,
+  dir = runtimeRoot(),
+  opts: { coldReceipt?: unknown } = {},
+): Promise<SharedRuntimeMutationGuard> {
+  if (opts.coldReceipt === undefined) return codexTargetMutationGuard(threadId, dir)
+  if (!isCodexColdPlan(opts.coldReceipt) || opts.coldReceipt.threadId !== threadId)
+    return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt is invalid' }
+  const current = await codexColdPreflight(threadId, dir, opts.coldReceipt.generation)
+  if (!current.ok) {
+    const guard = await codexTargetMutationGuard(threadId, dir)
+    return { ...guard, healthy: false, coldTeardownAuthorized: false, error: current.reason }
+  }
+  const authorized = sameIdSet(opts.coldReceipt.descendantIds, current.receipt.descendantIds) &&
+    sameParentEdges(opts.coldReceipt.parentEdges, current.receipt.parentEdges) &&
+    sameIdSet(opts.coldReceipt.activeIds, current.receipt.activeIds) &&
+    sameIdSet(opts.coldReceipt.archivedIds, current.receipt.archivedIds)
+  return {
+    ...current.receipt.guard,
+    healthy: authorized,
+    coldTeardownAuthorized: authorized,
+    ...(authorized ? {} : { error: 'adapter cold teardown receipt no longer matches the target subtree' }),
+  }
+}
+
+async function codexRestoreColdPlan(plan: CodexColdPlan, dir = runtimeRoot()): Promise<{ ok: true } | { ok: false; reason: string }> {
+  if (codexRuntimeGeneration(dir) !== plan.generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
+  const sock = codexAppServerSock(dir)
+  const [activeBefore, archivedBefore] = await Promise.all([
+    codexThreadList(sock, { archived: false, sourceKinds: [] }),
+    codexThreadList(sock, { archived: true, sourceKinds: [] }),
+  ])
+  if (!activeBefore.ok || !archivedBefore.ok)
+    return { ok: false, reason: 'archive state is unknown and could not be reconciled' }
+  if (codexRuntimeGeneration(dir) !== plan.generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
+  const activeSet = new Set(activeBefore.ids)
+  const archivedSet = new Set(archivedBefore.ids)
+  if (plan.archivedIds.some((id) => !archivedSet.has(id) || activeSet.has(id)))
+    return { ok: false, reason: 'an originally-archived Codex subtree member changed collection; compensation was not authorized' }
+  if (plan.activeIds.some((id) => activeSet.has(id) === archivedSet.has(id)))
+    return { ok: false, reason: 'an originally-active Codex subtree member has ambiguous collection state' }
+  const fence = { dir, generation: plan.generation }
+  const restoreIds = [...plan.activeIds].reverse().filter((id) => archivedSet.has(id))
+  for (const id of restoreIds) {
+    const restored = await codexThreadMutation(sock, 'thread/unarchive', id, fence)
+    if (!restored.ok) return { ok: false, reason: `compensation failed for ${id}: ${restored.error}` }
+  }
+  const [activeAfter, archivedAfter] = await Promise.all([
+    codexThreadList(sock, { archived: false, sourceKinds: [] }),
+    codexThreadList(sock, { archived: true, sourceKinds: [] }),
+  ])
+  const restored = activeAfter.ok && archivedAfter.ok && codexRuntimeGeneration(dir) === plan.generation &&
+    plan.activeIds.every((id) => activeAfter.ids.includes(id) && !archivedAfter.ids.includes(id)) &&
+    plan.archivedIds.every((id) => archivedAfter.ids.includes(id) && !activeAfter.ids.includes(id))
+  return restored ? { ok: true } : { ok: false, reason: 'compensation failed or archive state is unknown' }
 }
 
 // Read a loaded thread id off the app-server via `thread/loaded/list`. With the backend now OWNING the thread
@@ -1116,6 +1307,8 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRunt
     const listener = await listenerAt(sock, 800)
     if (!pidLive && listener === 'dead') return { healthy: true, references: [] }
     if (!pidLive || listener !== 'live') return { healthy: false, references: [], error: 'Codex shared root state is unknown (PID/listener identity is not proven)' }
+    const generation = codexRuntimeGeneration(dir)
+    if (!generation) return { healthy: false, references: [], error: 'Codex shared root detached receipt/socket generation is not proven' }
     return new Promise<SharedRuntimeProbe>((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
@@ -1133,7 +1326,9 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRunt
       settled = true
       clearTimeout(timer)
       try { conn.destroy() } catch { /* */ }
-      resolve(result)
+      resolve(result.healthy && codexRuntimeGeneration(dir) !== generation
+        ? { healthy: false, references: result.references, error: 'Codex shared root detached receipt/socket generation changed during ownership probe' }
+        : result)
     }
     const fail = (error: string) => done({ healthy: false, references: [...references.values()], error })
     timer = setTimeout(() => fail('codex app-server ownership probe timed out after 5000ms'), 5000)
@@ -1898,75 +2093,67 @@ export const codexHarness: Harness = {
     const dir = runtimeRoot()
     const generationBefore = codexRuntimeGeneration(dir)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
-    const sock = codexAppServerSock(dir)
-    const [guard, archivedList, activeList] = await Promise.all([
-      codexTargetMutationGuard(threadId, dir),
-      codexThreadList(sock, { archived: true, sourceKinds: [] }),
-      codexThreadList(sock, { archived: false, sourceKinds: [] }),
-    ])
+    const result = await codexColdPreflight(threadId, dir, generationBefore)
     if (codexRuntimeGeneration(dir) !== generationBefore)
       return { ok: false, reason: 'shared Codex app-server generation changed during cold retirement guard' }
-    if (guard.descendantIds.length) return { ok: false, reason: `Codex thread ${threadId} has owned descendants (${guard.descendantIds.join(', ')}); cold retirement is not proven safe` }
-    if (!guard.healthy) return { ok: false, reason: guard.error || `Codex thread ${threadId} target state is unknown` }
-    if (!archivedList.ok) return { ok: false, reason: archivedList.error }
-    if (!activeList.ok) return { ok: false, reason: activeList.error }
-    if (guard.targetTurnPresence !== 'none') return { ok: false, reason: `Codex thread ${threadId} is still loaded` }
-    const inArchived = archivedList.ids.includes(threadId)
-    const inActive = activeList.ids.includes(threadId)
-    if (!inArchived || inActive) return { ok: false, reason: `Codex thread ${threadId} is not uniquely in the archived collection (archived=${inArchived}, active=${inActive})` }
+    if (!result.ok) return result
+    if (!result.alreadyCold)
+      return { ok: false, reason: `Codex target subtree ${result.receipt.activeIds.join(', ')} is not fully archived` }
     return { ok: true, alreadyCold: true }
   },
   coldPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
-    const result = await codexColdPreflight(rec.harnessSessionId)
-    return result.ok ? { ok: true, ...(result.alreadyCold ? { alreadyCold: true } : {}) } : result
+    return codexColdPreflight(rec.harnessSessionId)
   },
-  coldRuntime: async (rec) => {
+  coldRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
     const threadId = rec.harnessSessionId
-    const sock = codexAppServerSock(runtimeRoot())
-    const generationBefore = codexRuntimeGeneration(runtimeRoot())
+    const dir = runtimeRoot()
+    const sock = codexAppServerSock(dir)
+    const generationBefore = codexRuntimeGeneration(dir)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
-    const preflight = await codexColdPreflight(threadId)
-    if (preflight && !preflight.ok) return preflight
-    if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore) return { ok: false, reason: 'shared Codex app-server generation changed during target guard' }
-    if (preflight?.ok && preflight.alreadyCold) return { ok: true }
-    const siblingBefore = preflight.guard.referenceIds.filter((referenceId) => referenceId !== threadId)
+    if (suppliedReceipt !== undefined && (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== threadId))
+      return { ok: false, reason: 'Codex cold teardown receipt is missing, malformed, or names a different target' }
+    const frozenPlan = isCodexColdPlan(suppliedReceipt) ? suppliedReceipt : null
+    if (frozenPlan && frozenPlan.generation !== generationBefore)
+      return { ok: false, reason: 'shared Codex app-server generation changed after archive preflight' }
+    const preflight = await codexColdPreflight(threadId, dir, frozenPlan?.generation ?? generationBefore)
+    if (!preflight.ok) return preflight
+    const plan = frozenPlan ?? preflight.receipt
+    if (frozenPlan && (!sameIdSet(frozenPlan.descendantIds, preflight.receipt.descendantIds) ||
+      !sameParentEdges(frozenPlan.parentEdges, preflight.receipt.parentEdges) ||
+      !sameIdSet(frozenPlan.activeIds, preflight.receipt.activeIds) ||
+      !sameIdSet(frozenPlan.archivedIds, preflight.receipt.archivedIds)))
+      return { ok: false, reason: 'Codex target subtree ownership or collection assignment changed after archive preflight' }
+    if (codexRuntimeGeneration(dir) !== plan.generation)
+      return { ok: false, reason: 'shared Codex app-server generation changed during target subtree guard' }
+    if (plan.activeIds.length === 0) return { ok: true }
+    const subtreeSet = new Set(plan.subtreeIds)
+    const siblingBefore = plan.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId))
+    const fence = { dir, generation: plan.generation }
+
+    const compensate = async (reason: string): Promise<{ ok: false; reason: string }> => {
+      const restored = await codexRestoreColdPlan(plan, dir)
+      return { ok: false, reason: restored.ok ? reason : `${reason}; ${restored.reason}` }
+    }
+
     const coldCheck = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
-      const [guard, archivedList, activeList] = await Promise.all([
-        codexTargetMutationGuard(threadId),
-        codexThreadList(sock, { archived: true, sourceKinds: [] }),
-        codexThreadList(sock, { archived: false, sourceKinds: [] }),
-      ])
-      if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
-      if (guard.descendantIds.length) return { ok: false, reason: `Codex thread ${threadId} acquired owned descendants during archive (${guard.descendantIds.join(', ')})` }
-      if (!guard.healthy) return { ok: false, reason: guard.error || 'Codex post-archive target guard is unhealthy' }
-      if (!archivedList.ok) return { ok: false, reason: archivedList.error }
-      if (!activeList.ok) return { ok: false, reason: activeList.error }
-      if (guard.targetTurnPresence !== 'none') return { ok: false, reason: `Codex thread ${threadId} remains loaded after thread/archive` }
-      if (!archivedList.ids.includes(threadId)) return { ok: false, reason: `Codex thread ${threadId} is absent from both loaded and archived collections` }
-      if (activeList.ids.includes(threadId)) return { ok: false, reason: `Codex thread ${threadId} remains in the non-archived collection` }
-      const afterIds = new Set(guard.referenceIds.filter((referenceId) => referenceId !== threadId))
+      const after = await codexColdPreflight(threadId, dir, plan.generation)
+      if (!after.ok) return after
+      if (codexRuntimeGeneration(dir) !== plan.generation) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
+      if (!sameIdSet(plan.descendantIds, after.receipt.descendantIds) || !sameParentEdges(plan.parentEdges, after.receipt.parentEdges))
+        return { ok: false, reason: `Codex target descendant closure changed during archive (before=${plan.descendantIds.join(', ')}; after=${after.receipt.descendantIds.join(', ')})` }
+      if (after.receipt.activeIds.length)
+        return { ok: false, reason: `Codex target subtree remains in the active collection (${after.receipt.activeIds.join(', ')})` }
+      if (!sameIdSet(plan.subtreeIds, after.receipt.archivedIds))
+        return { ok: false, reason: 'Codex target subtree is not uniquely archived after cold teardown' }
+      const afterIds = new Set(after.receipt.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId)))
       if (siblingBefore.some((referenceId) => !afterIds.has(referenceId))) return { ok: false, reason: 'a pre-existing shared Codex sibling reference disappeared during archive' }
       return { ok: true }
     }
-    const fence = { dir: runtimeRoot(), generation: generationBefore }
-    const archived = await codexThreadMutation(sock, 'thread/archive', rec.harnessSessionId, fence)
-    if (!archived.ok) {
-      if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore)
-        return { ok: false, reason: `${archived.error}; shared Codex app-server generation changed, so archive state is unknown and no compensation was attempted` }
-      // RPC transport failure is commit-unknown. Reconcile collections before deciding whether compensation is needed.
-      const [archivedList, activeList] = await Promise.all([
-        codexThreadList(sock, { archived: true, sourceKinds: [] }),
-        codexThreadList(sock, { archived: false, sourceKinds: [] }),
-      ])
-      if (archivedList.ok && archivedList.ids.includes(rec.harnessSessionId)) {
-        const restored = await codexThreadMutation(sock, 'thread/unarchive', rec.harnessSessionId, fence)
-        const stillActive = await codexThreadList(sock, { archived: false, sourceKinds: [] })
-        const suffix = restored.ok && stillActive.ok && stillActive.ids.includes(rec.harnessSessionId) ? '' : '; compensation/reconciliation failed'
-        return { ok: false, reason: `${archived.error}${suffix}` }
-      }
-      return { ok: false, reason: archivedList.ok && activeList.ok ? archived.error : `${archived.error}; archive state is unknown and could not be reconciled` }
+    for (const id of plan.activeIds) {
+      const archived = await codexThreadMutation(sock, 'thread/archive', id, fence)
+      if (!archived.ok) return compensate(`${archived.error} while archiving Codex subtree member ${id}`)
     }
     let verified: { ok: true } | { ok: false; reason: string } = { ok: false, reason: 'Codex archive verification timed out' }
     const verifyDeadline = Date.now() + 30_000
@@ -1976,15 +2163,15 @@ export const codexHarness: Harness = {
       if (Date.now() < verifyDeadline) await new Promise((resolve) => setTimeout(resolve, 100))
     }
     if (verified.ok) return verified
-    if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore)
-      return { ok: false, reason: `${verified.reason}; shared Codex app-server generation changed, so no compensation was attempted` }
-    const restored = await codexThreadMutation(sock, 'thread/unarchive', rec.harnessSessionId, fence)
-    const active = await codexThreadList(sock, { archived: false, sourceKinds: [] })
-    const suffix = restored.ok && active.ok && active.ids.includes(rec.harnessSessionId) ? '' : '; compensation failed or archive state is unknown'
-    return { ok: false, reason: `${verified.reason}${suffix}` }
+    return compensate(verified.reason)
   },
-  restoreRuntime: async (rec) => {
+  restoreRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
+    if (suppliedReceipt !== undefined) {
+      if (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== rec.harnessSessionId)
+        return { ok: false, reason: 'Codex cold compensation receipt is invalid or names a different target' }
+      return codexRestoreColdPlan(suppliedReceipt)
+    }
     const sock = codexAppServerSock(runtimeRoot())
     const reconcile = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
       const [active, archived] = await Promise.all([
@@ -2006,7 +2193,7 @@ export const codexHarness: Harness = {
     key: 'codex-app-server',
     label: 'Codex app-server',
     pidFile: codexAppServerPid(runtimeDir),
-    isolationFile: codexAppServerIsolation(runtimeDir),
+    receiptFile: codexAppServerReceipt(runtimeDir),
     residency: async () => {
       const sock = codexAppServerSock(runtimeDir)
       let pid = 0
@@ -2021,7 +2208,7 @@ export const codexHarness: Harness = {
       const result = await codexLoadedReferenceIds(sock)
       return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error }
     },
-    mutationGuard: (targetReferenceId) => codexTargetMutationGuard(targetReferenceId, runtimeDir),
+    mutationGuard: (targetReferenceId, opts) => codexMutationGuard(targetReferenceId, runtimeDir, opts),
     probe: () => codexSharedRuntimeProbe(runtimeDir),
   }],
   // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT

package/spec-cli/src/host-resources.ts

@@ -7,7 +7,7 @@ import { defaultHarness, HARNESSES, harnessById, sessionIdentityEnvVars, type Ha
 import { listSessionIds, readConfig, readJsonConfig, readPublicRecordEntry, readRawRecord, runtimeRoot, type PublicRecordEntry, type RawRecord } from './layout.js'
 import { repoRoot } from './git.js'
 import { endpointRecordPath } from './host.js'
-import { parseProcStat, processStartToken, processTopology, type ProcessIdentity } from './process-identity.js'
+import { detachedRuntimeGenerationToken, parseProcStat, processStartToken, verifyDetachedRuntime, type ProcessIdentity } from './process-identity.js'
 import { readBackendInstanceRecords, type BackendInstanceRecord } from './runtime-ownership.js'
 
 type Proc = ProcessIdentity & {
@@ -384,6 +384,7 @@ const sessionStopBlocker = async (
   harnessId: string | null,
   recs = rawRecords(),
   knownProbes?: Map<string, SharedRuntimeProbe>,
+  opts: { coldReceipt?: unknown } = {},
 ): Promise<string | null> => {
   const allowed = harnessId
     ? new Set((harnessById(harnessId).sharedRuntimes?.(runtimeRoot()) ?? []).map((descriptor) => descriptor.key))
@@ -392,7 +393,6 @@ const sessionStopBlocker = async (
     if (allowed && !allowed.has(key)) continue
     const descriptor = entry.descriptor
     const pid = runtimePid(descriptor.pidFile)
-    const startToken = pid ? processStartToken(pid) : null
     const ownerCounts = new Map<string, number>()
     for (const rec of entry.recs) if (rec.harness_session_id) ownerCounts.set(rec.harness_session_id, (ownerCounts.get(rec.harness_session_id) ?? 0) + 1)
     const targetThread = entry.recs.find((rec) => rec.session_id === id)?.harness_session_id
@@ -401,24 +401,16 @@ const sessionStopBlocker = async (
     if (!knownProbes && descriptor.mutationGuard) {
       if (!targetThread) return `${descriptor.label} target has no exact governed thread identity`
       if (!pid) return `${descriptor.label} target-scoped mutation guard has no readable owner PID`
-      if (!startToken) return `${descriptor.label} PID ${pid} target-scoped mutation guard has no readable process-start identity`
-      const topologyBefore = processTopology(pid)
-      let stampBefore = ''
-      try { stampBefore = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* legacy unsafe runtime */ }
-      if (!topologyBefore || topologyBefore.startToken !== startToken || topologyBefore.processGroupId !== pid || topologyBefore.sessionId !== pid ||
-        stampBefore !== `detached-v3 ${pid} ${startToken} ${pid} ${pid}`)
-        return `${descriptor.label} PID ${pid}@${startToken} has no matching live detached process-boundary record`
+      const identityBefore = verifyDetachedRuntime(pid, descriptor.receiptFile)
+      if (!identityBefore.ok)
+        return `${descriptor.label} PID ${pid} has no matching live detached process-boundary record: ${identityBefore.reason}`
       let guard
-      try { guard = await descriptor.mutationGuard(targetThread) }
+      try { guard = await descriptor.mutationGuard(targetThread, opts) }
       catch (error) { return `${descriptor.label} target-scoped mutation guard failed: ${(error as Error).message}` }
-      const startAfter = processStartToken(pid)
-      const topologyAfter = processTopology(pid)
-      let stampAfter = ''
-      try { stampAfter = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* changed/missing identity */ }
-      if (startAfter !== startToken || !topologyAfter || topologyAfter.startToken !== startToken ||
-        topologyAfter.processGroupId !== pid || topologyAfter.sessionId !== pid || stampAfter !== stampBefore)
-        return `${descriptor.label} PID/start/isolation identity changed during target-scoped mutation guard`
-      if (guard.descendantIds.length)
+      const identityAfter = verifyDetachedRuntime(pid, descriptor.receiptFile)
+      if (!identityAfter.ok || detachedRuntimeGenerationToken(identityAfter.identity) !== detachedRuntimeGenerationToken(identityBefore.identity))
+        return `${descriptor.label} PID/start/detached-receipt identity changed during target-scoped mutation guard${identityAfter.ok ? '' : `: ${identityAfter.reason}`}`
+      if (guard.descendantIds.length && guard.coldTeardownAuthorized !== true)
         return `${descriptor.label} target thread ${targetThread} has owned descendants (${guard.descendantIds.join(', ')})`
       if (!guard.healthy)
         return `${descriptor.label} target thread ${targetThread} is unknown: ${guard.error || 'target-scoped mutation guard failed'}`
@@ -433,17 +425,13 @@ const sessionStopBlocker = async (
       ? `${siblings.length} live sibling thread(s)`
       : probe.healthy ? `${probe.references.length} live thread reference(s)` : 'an unproven live reference set'
     if (!pid) return `${descriptor.label} has ${liveReason} but no readable owner PID`
-    if (!startToken) return `${descriptor.label} PID ${pid} has ${liveReason} but no readable process-start identity`
-    const topology = processTopology(pid)
-    let stamp = ''
-    try { stamp = readFileSync(descriptor.isolationFile, 'utf8').trim() } catch { /* legacy unsafe runtime */ }
-    if (!topology || topology.startToken !== startToken || topology.processGroupId !== pid || topology.sessionId !== pid ||
-      stamp !== `detached-v3 ${pid} ${startToken} ${pid} ${pid}`) {
+    const identity = verifyDetachedRuntime(pid, descriptor.receiptFile)
+    if (!identity.ok) {
       const refs = probe.references.map((reference) => reference.referenceId).join(', ') || 'no loaded threads'
-      return `${descriptor.label} PID ${pid}@${startToken} serves ${refs} and has no matching live detached process-boundary record`
+      return `${descriptor.label} PID ${pid} serves ${refs} and has no matching live detached process-boundary record: ${identity.reason}`
     }
     if (!probe.healthy)
-      return `${descriptor.label} PID ${pid}@${startToken} has an unproven live reference set: ${probe.error || 'unknown probe failure'}`
+      return `${descriptor.label} PID ${pid}@${identity.identity.startToken} has an unproven live reference set: ${probe.error || 'unknown probe failure'}`
   }
   return null
 }
@@ -658,9 +646,13 @@ export async function collectResourceReport(opts: { procRoot?: string; persist?:
   return report
 }
 
-export async function assertSessionStopSafe(id: string, rec: (HarnessLivenessRecord & { harness?: string }) | null): Promise<void> {
+export async function assertSessionStopSafe(
+  id: string,
+  rec: (HarnessLivenessRecord & { harness?: string }) | null,
+  opts: { coldReceipt?: unknown } = {},
+): Promise<void> {
   if (!rec) throw new ResourceConflict(`refusing to stop ${id}: no readable session record proves the adapter or leaf owner`)
-  const blocker = await sessionStopBlocker(id, rec.harness || null)
+  const blocker = await sessionStopBlocker(id, rec.harness || null, rawRecords(), undefined, opts)
   if (blocker) throw new ResourceConflict(`refusing to stop ${id}: ${blocker}`)
 }
 

package/spec-cli/src/init.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
-import { join, resolve, relative } from 'node:path'
+import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
@@ -81,6 +81,20 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
+// Detect once, at adoption, while the root checkout still names the branch being adopted. Steady-state
+// layout never re-derives trunk identity from a mutable checkout (an ordinary `git switch node/x` must not
+// turn that feature branch into trunk).
+function adoptionMainBranch(dir: string): string {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    if (branch) return branch
+  } catch { /* render the one product-level repair below */ }
+  const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
+  error.name = 'ConfigError'
+  throw error
+}
+
 export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
@@ -153,18 +167,23 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   const cfgDest = join(targetDir, 'spexcode.json')
   const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    if (flagRaw) {
-      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
-      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
-      cfg.harnesses = flagRaw
+    const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+    const stampedBranch = typeof cfg.mainBranch !== 'string' || !cfg.mainBranch.trim()
+    if (stampedBranch) cfg.mainBranch = adoptionMainBranch(targetDir)
+    if (flagRaw) cfg.harnesses = flagRaw
+    if (flagRaw || stampedBranch) {
       writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
-      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+      console.log(`✓ stamped ${[
+        flagRaw ? `"harnesses": ${JSON.stringify(flagRaw)}` : '',
+        stampedBranch ? `"mainBranch": ${JSON.stringify(cfg.mainBranch)}` : '',
+      ].filter(Boolean).join(' and ')} into the existing spexcode.json (other fields untouched)`)
     } else {
       console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
     }
   } else {
     const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
     cfg.harnesses = chosenHarnesses
+    cfg.mainBranch = adoptionMainBranch(targetDir)
     if (nativeChosen.length && cfg.sessions?.launchers) {
       cfg.sessions.launchers = Object.fromEntries(
         Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
@@ -173,7 +192,7 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
     writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
+    console.log(`✓ planted spexcode.json — mainBranch ${JSON.stringify(cfg.mainBranch)}, harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
   // 2. install the git hooks. Unknown existing hooks are user-owned and stay byte-identical. An exact

package/spec-cli/src/layout.ts

@@ -9,7 +9,7 @@ export { encodeProject, spexcodeHome } from './project-store.js'
 
 export type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
-  mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
+  mainBranch?: string              // stable source-of-truth branch stamped by init (default: "main")
   branchPrefix?: string            // how a branch names its node (default: "node/")
   preset?: string                  // the SELECTED init preset — which cumulative .plugins tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
   // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
@@ -115,16 +115,8 @@ export function gitCommonDir(): string {
 
 export function mainBranch(): string {
   let checkout: string
-  try {
-    checkout = mainCheckout()
-  } catch { return 'main' }
-  const override = readConfig(checkout).mainBranch?.trim()
-  if (override) return override
-  try {
-    const cur = git(['-C', checkout, 'symbolic-ref', '--short', 'HEAD']).trim()
-    if (cur) return cur
-  } catch { /* detached/bare checkout: use the documented conventional default */ }
-  return 'main'
+  try { checkout = mainCheckout() } catch { return 'main' }
+  return readConfig(checkout).mainBranch?.trim() || 'main'
 }
 
 // the MAIN checkout (the root working tree) for a project — the SAME answer from main OR any linked worktree

package/spec-cli/src/process-identity.ts

@@ -1,10 +1,36 @@
+import { randomUUID } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { platform } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 
 export type ProcessIdentity = { pid: number; startToken: string }
-export type ProcessTopology = ProcessIdentity & { processGroupId: number; sessionId: number }
+
+export type ProcessAdapter = Readonly<{
+  platform: NodeJS.Platform
+  startToken(pid: number): string | null
+  processGroupId(pid: number): number | null
+  linuxSessionId(pid: number): number | null
+}>
+
+export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
+  receiptVersion: 4
+  processGroupId: number
+  linuxSessionId?: number
+}>
+
+export type DetachedRuntimeVerification =
+  | { ok: true; identity: VerifiedDetachedRuntime }
+  | { ok: false; reason: string }
+
+type DetachedLaunchReceiptV4 = {
+  version: 4
+  kind: 'spexcode-detached-runtime'
+  pid: number
+  startToken: string
+  processGroupId: number
+  linuxSessionId?: number
+}
 
 export function parseProcStat(text: string): { ppid: number; processGroupId: number; sessionId: number; ticks: number; startToken: string; rssPages: number } {
   const end = text.lastIndexOf(')')
@@ -21,22 +47,6 @@ export function parseProcStat(text: string): { ppid: number; processGroupId: num
   }
 }
 
-export function processTopology(pid: number, procRoot = '/proc'): ProcessTopology | null {
-  if (platform() === 'linux' || procRoot !== '/proc') {
-    try {
-      const stat = parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8'))
-      return { pid, startToken: stat.startToken, processGroupId: stat.processGroupId, sessionId: stat.sessionId }
-    } catch { return null }
-  }
-  try {
-    const [processGroupId, sessionId] = execFileSync('ps', ['-o', 'pgid=', '-o', 'sess=', '-p', String(pid)], { encoding: 'utf8' }).trim().split(/\s+/).map(Number)
-    const startToken = processStartToken(pid, procRoot)
-    return startToken && Number.isFinite(processGroupId) && Number.isFinite(sessionId)
-      ? { pid, startToken, processGroupId, sessionId }
-      : null
-  } catch { return null }
-}
-
 export function processStartToken(pid: number, procRoot = '/proc'): string | null {
   if (platform() === 'linux' || procRoot !== '/proc') {
     try { return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken }
@@ -47,3 +57,118 @@ export function processStartToken(pid: number, procRoot = '/proc'): string | nul
     return started || null
   } catch { return null }
 }
+
+const procField = (pid: number, field: 'processGroupId' | 'sessionId'): number | null => {
+  try {
+    const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'))
+    return stat[field]
+  } catch { return null }
+}
+
+const psProcessGroupId = (pid: number): number | null => {
+  try {
+    const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
+    return Number.isInteger(value) && value > 0 ? value : null
+  } catch { return null }
+}
+
+export const hostProcessAdapter: ProcessAdapter = Object.freeze({
+  platform: platform(),
+  startToken: (pid) => processStartToken(pid),
+  processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
+  linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
+})
+
+const exactKeys = (value: Record<string, unknown>, expected: string[]) => {
+  const actual = Object.keys(value).sort()
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
+}
+
+const parseDetachedLaunchReceipt = (text: string, hostPlatform: NodeJS.Platform): DetachedLaunchReceiptV4 | null => {
+  let value: unknown
+  try { value = JSON.parse(text) } catch { return null }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const receipt = value as Record<string, unknown>
+  const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort()
+  if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
+    !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
+    !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
+    (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0))) return null
+  return receipt as DetachedLaunchReceiptV4
+}
+
+const observeDetachedRuntime = (pid: number, adapter: ProcessAdapter): DetachedRuntimeVerification => {
+  if (adapter.platform === 'win32') return { ok: false, reason: 'detached runtime identity is unsupported on win32' }
+  const startBefore = adapter.startToken(pid)
+  if (!startBefore) return { ok: false, reason: `PID ${pid} has no readable process-start identity` }
+  const processGroupId = adapter.processGroupId(pid)
+  if (processGroupId !== pid) return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` }
+  let linuxSessionId: number | undefined
+  if (adapter.platform === 'linux') {
+    const sessionId = adapter.linuxSessionId(pid)
+    if (sessionId !== pid) return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` }
+    linuxSessionId = sessionId
+  }
+  const startAfter = adapter.startToken(pid)
+  if (!startAfter || startAfter !== startBefore)
+    return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` }
+  return {
+    ok: true,
+    identity: Object.freeze({
+      pid,
+      startToken: startAfter,
+      receiptVersion: 4,
+      processGroupId,
+      ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
+    }),
+  }
+}
+
+export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): DetachedRuntimeVerification {
+  let text: string
+  try { text = readFileSync(receiptFile, 'utf8') }
+  catch { return { ok: false, reason: 'detached launch receipt is missing or unreadable' } }
+  const receipt = parseDetachedLaunchReceipt(text, adapter.platform)
+  if (!receipt) return { ok: false, reason: 'detached launch receipt has the wrong version or shape' }
+  if (receipt.pid !== pid) return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` }
+  if (receipt.processGroupId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` }
+  if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` }
+  const live = observeDetachedRuntime(pid, adapter)
+  if (!live.ok) return live
+  if (live.identity.startToken !== receipt.startToken)
+    return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` }
+  return live
+}
+
+export function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): VerifiedDetachedRuntime {
+  const observed = observeDetachedRuntime(pid, adapter)
+  if (!observed.ok) throw new Error(`cannot prove detached shared runtime: ${observed.reason}`)
+  const receipt: DetachedLaunchReceiptV4 = {
+    version: 4,
+    kind: 'spexcode-detached-runtime',
+    pid,
+    startToken: observed.identity.startToken,
+    processGroupId: observed.identity.processGroupId,
+    ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
+  }
+  mkdirSync(dirname(receiptFile), { recursive: true })
+  const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`
+  let published = false
+  try {
+    writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 })
+    renameSync(tmp, receiptFile)
+    published = true
+    const verified = verifyDetachedRuntime(pid, receiptFile, adapter)
+    if (!verified.ok) throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`)
+    return verified.identity
+  } catch (error) {
+    rmSync(tmp, { force: true })
+    if (published) rmSync(receiptFile, { force: true })
+    throw error
+  }
+}
+
+export const detachedRuntimeGenerationToken = (identity: VerifiedDetachedRuntime) =>
+  `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`

package/spec-cli/src/runtime-ownership.ts

@@ -4,7 +4,7 @@ import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeF
 import { dirname, join } from 'node:path'
 import { repoRoot } from './git.js'
 import { readJsonConfig, runtimeRoot } from './layout.js'
-import { processStartToken, processTopology, type ProcessIdentity } from './process-identity.js'
+import { processStartToken, writeDetachedRuntimeReceipt, type ProcessIdentity } from './process-identity.js'
 
 export type BackendInstanceRecord = {
   version: 1
@@ -51,20 +51,11 @@ export function unregisterBackendInstance(instanceId: string, pid = process.pid)
   } catch { /* not ours / already removed */ }
 }
 
-export function writeIsolationStamp(pid: number, file: string): void {
-  const topology = processTopology(pid)
-  if (!topology) throw new Error(`cannot identify shared runtime PID ${pid}`)
-  if (topology.processGroupId !== pid || topology.sessionId !== pid)
-    throw new Error(`shared runtime PID ${pid} is not detached from its launch session (pgrp=${topology.processGroupId}, session=${topology.sessionId})`)
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, `detached-v3 ${pid} ${topology.startToken} ${topology.processGroupId} ${topology.sessionId}\n`, { mode: 0o600 })
-}
-
 export function spawnDetachedRuntime(opts: {
   cwd: string
   logFile: string
   pidFile: string
-  isolationFile: string
+  receiptFile: string
   command: string
   args: string[]
   env?: NodeJS.ProcessEnv
@@ -85,15 +76,13 @@ export function spawnDetachedRuntime(opts: {
   if (!child.pid) throw new Error(`could not spawn detached shared runtime: ${opts.command}`)
   child.unref()
   try {
-    writeIsolationStamp(child.pid, opts.isolationFile)
-    const startToken = processStartToken(child.pid)
-    if (!startToken) throw new Error(`cannot identify detached shared runtime PID ${child.pid}`)
+    const identity = writeDetachedRuntimeReceipt(child.pid, opts.receiptFile)
     writeFileSync(opts.pidFile, `${child.pid}\n`, { mode: 0o600 })
-    return { pid: child.pid, startToken }
+    return { pid: identity.pid, startToken: identity.startToken }
   } catch (error) {
     try { child.kill('SIGTERM') } catch { /* exact just-spawned child already exited */ }
     rmSync(opts.pidFile, { force: true })
-    rmSync(opts.isolationFile, { force: true })
+    rmSync(opts.receiptFile, { force: true })
     throw error
   }
 }

package/spec-cli/src/sessions.ts

@@ -2437,10 +2437,11 @@ async function assertSessionLeafOwned(id: string, rec: SessRec): Promise<LeafIde
   return { pid, startToken, ownerNeedle }
 }
 
-async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = false): Promise<void> {
+async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = false, coldReceipt?: unknown): Promise<void> {
   // The caller resolves one readable owner before entering this seam. An absent/corrupt record never reaches
   // tmux, signals, or adapter cleanup: a bare session id is an address, not ownership authority.
-  const assertOwned = () => assertSessionStopSafe(id, rec ? { ...rec, harness: rec.harness } : null)
+  const assertOwned = () => assertSessionStopSafe(id, rec ? { ...rec, harness: rec.harness } : null,
+    { ...(requireCold && coldReceipt !== undefined ? { coldReceipt } : {}) })
   await assertOwned()
   if (!rec) throw new ResourceConflict(`refusing to stop ${id}: no readable session owner`)
   const harness = harnessById(rec.harness || defaultHarness.id)
@@ -2453,7 +2454,7 @@ async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = f
   launchedAt.delete(id)
   await harness.cleanupRuntime(rec)
   if (requireCold) {
-    const cold = await harness.coldRuntime?.(rec)
+    const cold = await harness.coldRuntime?.(rec, coldReceipt)
     if (cold && !cold.ok) throw new ResourceConflict(`refusing to archive ${id}: ${cold.reason}`)
   }
 }
@@ -2521,7 +2522,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
       if (rootAbsent) return true
       const pre = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: true })
       if (!pre || pre.ok) {
-        const cold = await h.coldRuntime?.({ ...wt.rec, archived: false, stopped: true })
+        const cold = await h.coldRuntime?.({ ...wt.rec, archived: false, stopped: true }, pre?.ok ? pre.receipt : undefined)
         if (!cold || cold.ok) return true
       }
     }
@@ -2541,8 +2542,8 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     : liveness({ ...wt.rec, archived: false, stopped: false }, snap)
   if (lv === 'unknown' || lv === 'starting')
     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 Codex turns and owned descendants
-  // refuse here, leaving the leaf/shared root/record untouched; coldRuntime is the commit cleanup after this.
+  // 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.
   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
@@ -2552,7 +2553,8 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
   let coldAttempted = false
   try {
     coldAttempted = true
-    await stopAgentProcess(id, { ...wt.rec, archived: false, stopped: lv === 'offline' }, true)
+    await stopAgentProcess(id, { ...wt.rec, archived: false, stopped: lv === 'offline' }, true,
+      preflight?.ok ? preflight.receipt : undefined)
     coldCommitted = true
     const latest = readRecord(id)
     if (!latest) throw new ResourceConflict(`refusing to archive ${id}: session record disappeared before filing`)
@@ -2566,7 +2568,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     writeRecord({ ...latest, archived: true, stopped: true, coldProof: coldProofFor(latest) })
   } catch (error) {
     if (coldCommitted) {
-      const restored = await h.restoreRuntime?.(wt.rec)
+      const restored = await h.restoreRuntime?.(wt.rec, preflight?.ok ? preflight.receipt : undefined)
       if (restored && !restored.ok) {
         const current = readRecord(id)
         if (current) writeRecord({ ...current, archived: false, stopped: true, coldProof: null, adapterRecovery: `restore-runtime:${restored.reason}` })

package/spec-cli/templates/hooks/pre-commit

@@ -58,18 +58,12 @@ fi
 # stamp already passed above. Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
 #
 # The trunk is resolved the SAME way the rest of SpexCode resolves it — `spex internal trunk` = layout.ts
-# mainBranch() (config override → the main checkout's current branch → 'main') — so the guard protects
-# whatever the repo's trunk is actually named, NOT a hardcoded 'main' (which gave a `master`/non-`main`
-# trunk zero protection). When the CLI isn't resolvable (advisory mode), fall back to a pure-git
-# auto-detect of the main checkout's current branch, then 'main' — still protecting a non-`main` trunk.
+# mainBranch() (the stable mainBranch project fact stamped at adoption; conventional default 'main') — so
+# the guard protects whatever the repo's trunk is actually named. When the CLI isn't resolvable (advisory
+# mode), only the convention is available: shell does not guess identity from a mutable checkout.
 branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo)
 git_dir=$(git rev-parse --git-dir 2>/dev/null)
 trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
-# Fallback auto-detect: the main checkout's current branch. Strip the hook's exported GIT_DIR/
-# GIT_INDEX_FILE first — otherwise they pin discovery to the COMMITTING worktree and `-C "$main_root"`
-# is ignored, so it would read THIS branch and think every node branch is the trunk. (`spex internal
-# trunk` above is immune: layout.ts mainBranch() resolves through git.ts's env-stripping git().)
-[ -n "$trunk" ] || trunk=$(env -u GIT_DIR -u GIT_INDEX_FILE git -C "$main_root" symbolic-ref --short HEAD 2>/dev/null)
 [ -n "$trunk" ] || trunk=main
 if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
   echo "✗ SpexCode: direct commits on $trunk (the trunk) are blocked." >&2