thinkpool-pair 0.7.242 → 0.7.244

package/bridge.mjs

@@ -105,11 +105,13 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, laneStatusOf, nativeClaudeFallbackHint } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, closeLaneDecision, laneStatusOf, nativeClaudeFallbackHint, buildDispatchPreview, authorizeDispatchApproval, verifyDurableDispatchAuthority } from './cross-terminal.mjs'
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
+import { classifyCodeEvent, unknownCodeEventNotice } from './code-event-contract.mjs'
+import { fetchPairControlDeliveryAuthority } from './pair-control-authority.mjs'
 import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantTextSince, sideContextBlock, sideSnapshot } from './side-lane.mjs'
 import { planMeterLine } from './plan-meters.mjs'
 import { makeThrottledTrack } from './presence.mjs'
@@ -643,6 +645,31 @@ const supabase = createClient(SUPABASE_URL, SUPABASE_ANON, {
   realtime: { params: { eventsPerSecond: 60 } },
 })
 
+// Authenticated re-read for previewed Dispatch. Realtime is intentionally not
+// trusted here: any room member can observe the public wake-up frame. RLS plus
+// the bridge's live member token supplies the item/event rows that the pure
+// verifier consumes. Timeout/offline/malformed state all fail closed.
+async function readDurableDispatchAuthority ({ controlItemId, expected, timeoutMs = 5000 } = {}) {
+  if (!codeAuthToken || !/^[0-9a-f-]{36}$/i.test(String(controlItemId || ''))) return { ok: false, code: 'durable_authority_unavailable' }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  timer.unref?.()
+  const headers = { apikey: SUPABASE_ANON, Authorization: `Bearer ${codeAuthToken}` }
+  try {
+    const itemUrl = `${SUPABASE_URL}/rest/v1/code_pair_control_items?id=eq.${encodeURIComponent(controlItemId)}&select=*`
+    const eventsUrl = `${SUPABASE_URL}/rest/v1/code_pair_control_events?item_id=eq.${encodeURIComponent(controlItemId)}&select=*&order=created_at.asc`
+    const [itemRes, eventRes] = await Promise.all([
+      fetch(itemUrl, { headers, signal: controller.signal }),
+      fetch(eventsUrl, { headers, signal: controller.signal }),
+    ])
+    if (!itemRes.ok || !eventRes.ok) return { ok: false, code: 'durable_authority_read_failed' }
+    const [items, events] = await Promise.all([itemRes.json(), eventRes.json()])
+    if (!Array.isArray(items) || items.length !== 1 || !Array.isArray(events)) return { ok: false, code: 'durable_authority_shape' }
+    return verifyDurableDispatchAuthority({ item: items[0], events, expected: { ...expected, controlItemId } })
+  } catch { return { ok: false, code: 'durable_authority_unavailable' } }
+  finally { clearTimeout(timer) }
+}
+
 // Owner's plan (free|plus) — gates the Ensemble dispatch ceiling (Free 3 / Plus 6).
 // Resolved from the owner token (codeAuthToken); RLS lets a user read their OWN
 // profiles row. Cached; defaults to 'free' (the safe lower ceiling) until the fetch
@@ -1032,7 +1059,7 @@ const announce = () => {
   // on a custom provider without the owner's account-channel registry.
   const provNames = providerNameMap()
   return bcast('bridge', {
-    v: 2, name, repo: repoLabel, branch: readBranch(),
+    v: 2, name, bridge_id: BRIDGE_ID, repo: repoLabel, branch: readBranch(),
     // sdkWarn: the auto-pulled agent SDK failed its boot compatibility smoke test —
     // surfaced so the room can show a banner (turns may misbehave; pin a good SDK).
     ...(sdkStatus.ok === false ? { sdkWarn: `${sdkStatus.version}: ${sdkStatus.reason}` } : {}),
@@ -1142,6 +1169,16 @@ function pairRequest(type, payload = {}, timeoutMs = 4000) {
     catch { clearTimeout(timer); pairWaiters.delete(reqId); resolve({ error: 'Could not reach the account bridge.' }) }
   })
 }
+function attachDurablePermissionSource(entry, payload) {
+  const event = {
+    kind: 'needs-input', subtype: 'pair-control',
+    summary: 'A protected action requires a durable decision.',
+    permissionId: String(payload?.id || '').slice(0, 160),
+  }
+  pushLog(entry, event)
+  bcast('code-event', { term: entry.id, evt: event })
+  return { ...payload, source: { epoch: 0, cid: event.cid, seq: event.seq } }
+}
 // ── Tier 3 — raise a standalone permission card on a target session ──────────
 // The cross-ROOM post lands here on the RECEIVING side: a person in THIS room must
 // approve the incoming task before it injects (the second half of dual consent —
@@ -1152,7 +1189,7 @@ function pairRequest(type, payload = {}, timeoutMs = 4000) {
 function raiseCard(entry, req) {
   return new Promise((resolve) => {
     if (!entry?.pending) return resolve('deny')
-    const payload = { term: entry.id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk }
+    const payload = attachDurablePermissionSource(entry, { term: entry.id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk })
     entry.pending.set(req.id, { resolve, payload })
     announce()
     bcast('code-perm-req', payload)
@@ -1620,11 +1657,27 @@ function printLocal(evt) {
   }
 }
 
+// Emit a safe degradation record for an unknown provider/client event. The rejected
+// payload never reaches a client or disk; the bridge-observed rejection does.
+function recordUnknownCodeEvent(entry, evt) {
+  const notice = unknownCodeEventNotice(evt)
+  process.stderr.write(`\n  ◇ ${notice.message}\n`)
+  if (entry?.id) {
+    pushLog(entry, notice)
+    bcast('code-event', { term: entry.id, evt: notice })
+  }
+  return notice
+}
+
 // Single stamp+append point for a structured session's replayed log. Assigns the
 // per-term contiguous seq (C1), appends, and caps at STRUCTURED_LOG_MAX (oldest
 // first). EVERY event that joins entry.log must go through here so the client's
 // "drop ≤ seqHi" cursor stays correct (a logged event with no seq would break it).
 function pushLog(entry, evt) {
+  if (!classifyCodeEvent(evt).known) {
+    recordUnknownCodeEvent(entry, evt)
+    return null
+  }
   // Single stamp point: guarantee ts+cid on EVERY logged event. echoYou() and the
   // /model,/clear control lines called pushLog WITHOUT a prior stampEvent, so
   // `you`/`control` were logged with a seq but NO ts. On a long session the
@@ -2039,6 +2092,34 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       provider: args?.provider,
     }
   }
+  const dispatchContext = (now = Date.now()) => ({
+    runtime: entry.runtime,
+    mode: entry.mode,
+    hop: entry.hop || 0,
+    spawnTimes: entry.spawnTimes || [],
+    now,
+    spawnedLive: [...sessions.values()].filter((session) => session.spawnedBy).length,
+    totalLive: sessions.size + terms.size,
+    plan: ownerPlan,
+    disabled: process.env.TP_SPAWN_OFF === '1',
+  })
+  // Dispatch uses the same durable pair-control permission transport as every
+  // protected action. The preview is additive evidence on that one request;
+  // this Promise is not another approval store or an autonomous allow path.
+  const requestDispatchApproval = (req) => new Promise((resolve) => {
+    const payload = attachDurablePermissionSource(entry, {
+      term: id, id: req.id, toolName: 'mcp__thinkpool__spawn_terminal',
+      // Exact arguments are already bound into dispatchPreview.fingerprint. Do not
+      // copy raw tool input into the public wake-up frame or the reconnect cache.
+      risk: 'high', answerFormat: 'dispatch',
+      dispatchPreview: req.dispatchPreview,
+    })
+    entry.pending.set(req.id, { resolve, payload, timer: null })
+    announce()
+    bcast('code-perm-req', payload)
+    if (isUserFacingLane(entry)) entry.permNotifier?.arm(req.id, permissionSummary(payload))
+    process.stderr.write(`\n  ${A.yel}● Dispatch preview ready — approve or cancel in the room.${A.rst}\n`)
+  })
   const consumeTerminalOpenBudget = () => {
     const now = Date.now()
     const gate = spawnDecision({
@@ -2280,15 +2361,8 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           const resolved = resolveAgentOpen(args, { worker: true })
           if (resolved.error) return okText(resolved.error)
           const now = Date.now()
-          const gate = spawnDecision({
-            hop: entry.hop || 0,
-            spawnTimes: entry.spawnTimes || [],                                     // sliding-window burst breaker (replenishes on wall-clock, not on a human turn)
-            now,
-            spawnedLive: [...sessions.values()].filter((s) => s.spawnedBy).length,  // dispatch budget counts ONLY spawned lanes
-            totalLive: sessions.size + terms.size,                                  // machine cap counts everything
-            plan: ownerPlan,                                                        // Free 3 / Plus 6 dispatch ceiling
-            disabled: process.env.TP_SPAWN_OFF === '1',
-          })
+          const before = dispatchContext(now)
+          const gate = spawnDecision(before)
           // A refusal that says "close one" without saying WHICH one sends the caller
           // hunting. Adapt the live roster to the pure helper: only lanes THIS caller
           // spawned and that aren't mid-turn — the exact set close_terminal accepts.
@@ -2296,11 +2370,65 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             ref: String(sid).slice(0, 8),
             name: termNames[sid] || undefined,
             spawnedBy: s.spawnedBy,
-            busy: s.session?.turnActive ?? false,
+            busy: (s.session?.turnActive ?? false) || (s.pending?.size ?? 0) > 0,
           }))))
+          const effectiveArgs = {
+            ...args,
+            runtime: resolved.runtime,
+            model: resolved.model,
+            provider: resolved.provider,
+            mode: resolved.mode,
+          }
+          let preview
+          try {
+            preview = buildDispatchPreview({
+              args: effectiveArgs,
+              initiatorTerminalId: id,
+              roomCode: room,
+              bridgeAuthorityId: BRIDGE_ID,
+              localAuthorityId: id,
+              context: {
+                ...before,
+                providerName: resolved.provider ? (providerNameMap()[resolved.provider] || resolved.provider) : undefined,
+                resolvedModel: resolved.model,
+              },
+            })
+          } catch { return okText('Dispatch preview could not be built safely. No lane was created.') }
+          const permissionId = randomUUID()
+          let approval = { decision: 'deny' }
+          try { approval = await requestDispatchApproval({ id: permissionId, input: effectiveArgs, dispatchPreview: preview }) } catch { /* fail closed */ }
+          if (approval?.decision !== 'allow') return okText('Dispatch canceled. No lane or worktree was created.')
+          const currentNow = Date.now()
+          const current = dispatchContext(currentNow)
+          const durable = await readDurableDispatchAuthority({
+            controlItemId: approval.controlItemId,
+            expected: {
+              roomCode: room,
+              bridgeAuthorityId: BRIDGE_ID,
+              localAuthorityId: id,
+              fingerprint: preview.fingerprint,
+            },
+          })
+          if (!durable.ok) return okText('Dispatch approval could not be verified from the durable room authority. No lane was created.')
+          const authorization = authorizeDispatchApproval({
+            preview,
+            approvedFingerprint: durable.fingerprint,
+            args: effectiveArgs,
+            initiatorTerminalId: id,
+            roomCode: room,
+            bridgeAuthorityId: BRIDGE_ID,
+            localAuthorityId: id,
+            context: {
+              ...current,
+              providerName: resolved.provider ? (providerNameMap()[resolved.provider] || resolved.provider) : undefined,
+              resolvedModel: resolved.model,
+            },
+            permissionId,
+          })
+          if (!authorization.ok) return okText(authorization.reason || 'Dispatch approval is stale or does not match this request. No lane was created.')
           // Record this spawn, pruning timestamps that have already left the window
           // (identical predicate to recentSpawnCount) so the array can't grow unbounded.
-          entry.spawnTimes = [...(entry.spawnTimes || []).filter((t) => Number.isFinite(t) && t > now - SPAWN.windowMs), now]
+          entry.spawnTimes = [...(entry.spawnTimes || []).filter((t) => Number.isFinite(t) && t > currentNow - SPAWN.windowMs), currentNow]
           const newId = randomUUID()
           const newRef = String(newId).slice(0, 8)
           const fromRef = String(id).slice(0, 8)
@@ -2376,7 +2504,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // the web's code-close), which no-ops if the id isn't a live session.
       ...(!entry.flowRole ? [tool(
         'close_terminal',
-        'Close an agent lane that YOU opened with spawn_terminal (identified by ref/id/name). You can only close lanes you spawned yourself — never a sibling someone else is working in, and never the main terminal. Use it to clean up after a fan-out once you have collected the results with read_terminal.',
+        'Close an IDLE agent lane that YOU opened with spawn_terminal (identified by ref/id/name). Active turns and permission waits are protected: collect the completed result with read_terminal before closing. You can only close lanes you spawned yourself — never a sibling someone else is working in, and never the main terminal.',
         {
           terminal: z.string().describe('ref, id, or name of the lane you spawned (from read_terminal)'),
         },
@@ -2387,7 +2515,15 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           if (!target) return okText(`No terminal matches "${args?.terminal}". Call read_terminal with no argument to list the open terminals.`)
           const te = sessions.get(target.id)
           if (!te) return okText(`Terminal ${target.ref} is not an agent lane (or already closed) — only spawned agent lanes can be closed this way.`)
-          if (te.spawnedBy !== id) return okText(`Terminal ${target.ref} was not opened by you — you can only close lanes you spawned yourself. Leave it to the person running it.`)
+          const close = closeLaneDecision({
+            callerId: id,
+            spawnedBy: te.spawnedBy,
+            busy: (te.session?.turnActive ?? false) || (te.pending?.size ?? 0) > 0,
+          })
+          if (!close.ok && close.reason === 'not-owner') return okText(`Terminal ${target.ref} was not opened by you — you can only close lanes you spawned yourself. Leave it to the person running it.`)
+          if (!close.ok && close.reason === 'busy') {
+            return okText(`Terminal ${target.ref} is still working or waiting for a permission decision. close_terminal will not kill an active turn. Wait until read_terminal reports it idle/completed, collect its result, then close it. If it is genuinely stuck, ask a person to press Stop.`)
+          }
           endStructured(target.id)
           return okText(`Closed agent lane ${target.ref}${target.name ? ` ("${target.name}")` : ''}.`)
         },
@@ -2562,6 +2698,15 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // default Claude env is left exactly as-is (unchanged path).
     env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), ...(resolveProviderEnv(provider) || {}), TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
+      if (!classifyCodeEvent(evt).known) {
+        // Never archive or replay an unknown provider payload as a known fact. Do
+        // leave a durable, user-visible bridge error so a provider upgrade cannot
+        // silently strand a busy lane or erase its failure from the transcript.
+        const notice = recordUnknownCodeEvent(entry, evt)
+        printLocal(notice)
+        announce()
+        return
+      }
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
       // keeping the transcript (scrollback survives; live context is gone).
       if (resume && evt.kind === 'error') {
@@ -2861,7 +3006,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       }
       // Keep the broadcast payload with the resolver so a reconnect can re-send it
       // (replay-request handler) — pending cards never enter the replayed event log.
-      const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions, asker: req.asker, answerFormat: req.answerFormat, autoResolutionMs: req.autoResolutionMs }
+      const payload = attachDurablePermissionSource(entry, { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions, asker: req.asker, answerFormat: req.answerFormat, autoResolutionMs: req.autoResolutionMs })
       const pending = { resolve, payload, timer: null }
       entry.pending.set(req.id, pending)
       announce()
@@ -2926,7 +3071,9 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
 // hook already degrades to, so draining to deny is always safe.
 function pendingResolution(pending, payload = {}) {
   const decision = payload.decision || 'deny'
-  return pending?.payload?.answerFormat === 'codex'
+  return pending?.payload?.answerFormat === 'dispatch'
+    ? { decision, dispatchFingerprint: payload.dispatchFingerprint || null, controlItemId: payload.controlItemId || null }
+    : pending?.payload?.answerFormat === 'codex'
     ? { decision, answers: payload.answers || {} }
     : decision
 }
@@ -2956,7 +3103,7 @@ function allowPending(s) {
     // AskUserQuestion (risk:'ask') is a deliberate human gate — flipping to bypass means
     // "run tools without asking", not "auto-approve my plan / answer my question" — leave
     // those for the human.
-    if (p?.payload?.risk === 'plan' || p?.payload?.risk === 'ask') continue
+    if (p?.payload?.risk === 'plan' || p?.payload?.risk === 'ask' || p?.payload?.answerFormat === 'dispatch') continue
     if (p?.timer) clearTimeout(p.timer)
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
@@ -3606,17 +3753,29 @@ channel
   .on('broadcast', { event: 'code-perm' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
     const p = s && payload.id && s.pending.get(payload.id)
-    // Pass the raw decision through — normal tools use allow/deny, plan cards
-    // use run/accept/keep (claude-session interprets). Default deny on missing.
-    // Answered from a device → retract the "needs you" banner on every OTHER device
-    // (permNotifier.resolve is a no-op unless its grace timer already fired).
-    if (p) {
+    if (!p) return
+    // `tpcode` is a public transport. Treat the frame only as a wake-up hint and
+    // reproduce its resolved item + unique delivery attempt through owner-authenticated
+    // RLS reads before touching the local pending resolver. A forged broadcast then
+    // has no more authority than packet noise.
+    void fetchPairControlDeliveryAuthority({
+      supabaseUrl: SUPABASE_URL,
+      anonKey: SUPABASE_ANON,
+      token: codeAuthToken,
+      roomCode: room,
+      bridgeId: BRIDGE_ID,
+      payload,
+    }).then((authority) => {
+      if (!authority.ok || sessions.get(payload.term)?.pending.get(payload.id) !== p) {
+        if (!authority.ok && process.env.TP_DEBUG) process.stderr.write(`\n  ◇ ignored unverified permission delivery (${authority.code})\n`)
+        return
+      }
       if (p.timer) clearTimeout(p.timer)
       s.pending.delete(payload.id)
       s.permNotifier?.resolve(payload.id)
-      p.resolve(pendingResolution(p, payload))
+      p.resolve(pendingResolution(p, { ...payload, decision: authority.decision }))
       announce()
-    }
+    })
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)

package/code-event-contract.mjs

@@ -0,0 +1,106 @@
+/* Canonical ThinkPool Code event contract.
+   Keep this module browser-safe: the bridge and src/pages/code both consume it. */
+
+export const EVENT_CLASS = Object.freeze({
+  VOLATILE_PRESENCE: 'volatile-presence',
+  REPLAYABLE_PROGRESS: 'replayable-progress',
+  REPLAYABLE_COMMAND: 'replayable-command',
+  DURABLE_DELIVERY_EVIDENCE: 'durable-delivery-evidence',
+  UNKNOWN: 'unknown',
+})
+
+const V = EVENT_CLASS.VOLATILE_PRESENCE
+const P = EVENT_CLASS.REPLAYABLE_PROGRESS
+const C = EVENT_CLASS.REPLAYABLE_COMMAND
+const E = EVENT_CLASS.DURABLE_DELIVERY_EVIDENCE
+
+// Exhaustive over every kind currently emitted into a Code room, its retained log,
+// or the durable __agent notification stream. `answer`/`control`/etc. are commands
+// replayed by the transcript; they are not durable decision records. Foundation B
+// will add actor-bound decision records and authoritative verification receipts.
+// Adding a producer without adding its kind here is a test/dev error and a
+// fail-closed production value.
+export const CODE_EVENT_REGISTRY = Object.freeze({
+  system: V,
+  thinking_tokens: V,
+  effort: V,
+  mode: V,
+  usage: V,
+  suggestion: V,
+  stalled: V,
+  compact: V,
+  assistant_stream: V,
+  models: V,
+  'model-switch': V,
+  capabilities: V,
+  'update-available': V,
+
+  you: P,
+  assistant: P,
+  tool_result: P,
+  note: P,
+  pool: P,
+  chat: P,
+  whisper: P,
+  compaction: P,
+  'side-started': P,
+  'side-handback': P,
+  answer: C,
+  control: C,
+  clear: C,
+  'queue-add': C,
+  'queue-cancel': C,
+  propose: C,
+  'propose-done': C,
+
+  result: E,
+  error: E,
+  mockup: E,
+  image: E,
+  'needs-input': E,
+  'needs-resolved': E,
+  'turn-done': E,
+})
+
+export const CODE_EVENT_KINDS = Object.freeze(Object.keys(CODE_EVENT_REGISTRY))
+
+const strictByDefault = () =>
+  typeof process !== 'undefined' && (process.env?.NODE_ENV === 'test' || process.env?.NODE_ENV === 'development')
+
+export function classifyCodeEvent (eventOrKind, { strict = strictByDefault() } = {}) {
+  const kind = typeof eventOrKind === 'string' ? eventOrKind : eventOrKind?.kind
+  const eventClass = typeof kind === 'string' ? CODE_EVENT_REGISTRY[kind] : null
+  if (!eventClass) {
+    if (strict) throw new TypeError(`Unknown ThinkPool Code event kind: ${String(kind)}`)
+    return Object.freeze({ kind: kind ?? null, known: false, eventClass: EVENT_CLASS.UNKNOWN, durable: false, replayable: false, authorizes: false, completes: false })
+  }
+  return Object.freeze({
+    kind,
+    known: true,
+    eventClass,
+    // A replayable command is historical UI context, not a durable decision fact.
+    // Only delivery evidence currently has the archive-level durability contract.
+    durable: eventClass === E,
+    replayable: eventClass !== V,
+    // Foundation B supplies actor-bound authorization. Classification alone never does.
+    authorizes: false,
+    // Lifecycle completion additionally requires an explicit verification receipt.
+    completes: false,
+  })
+}
+
+// Preserve observability without copying an unregistered payload into the replay
+// or archive. This is a bridge-observed delivery failure, not a claim about what
+// the producer meant or a substitute for its event.
+export function unknownCodeEventNotice (eventOrKind) {
+  const rawKind = typeof eventOrKind === 'string' ? eventOrKind : eventOrKind?.kind
+  const unknownKind = typeof rawKind === 'string' ? rawKind.slice(0, 120) : null
+  return {
+    kind: 'error',
+    subtype: 'unknown_event',
+    message: `Unrecognized Code event${unknownKind ? ` "${unknownKind}"` : ''} was rejected; this lane needs recovery.`,
+    unknownKind,
+  }
+}
+
+export const isKnownCodeEventKind = (kind) => Object.hasOwn(CODE_EVENT_REGISTRY, kind)

package/cross-terminal.mjs

@@ -8,6 +8,9 @@
    the structured-event compaction here mirrors that file's digestLine shape.
    Spec: docs/specs/2026-06-28-cross-terminal-awareness.md */
 
+import { createHash } from 'node:crypto'
+import { BLOCKED_REASON, projectLaneLifecycle } from './lane-lifecycle.mjs'
+
 // Bounds — the pull tool is self-limiting (the agent only calls it when it needs
 // to), but a runaway loop must still be capped (the cost-guard / C10 class).
 export const PEEK = {
@@ -72,7 +75,16 @@ export const laneStatusOf = (entry = {}, now = Date.now(), limits = LANE_STATUS)
     statusFlag = 'BLOCKED'; statusReason = 'repeated errors'
   }
 
-  return { busy: !!busy, lastActionAt, lastActionAgeMs, statusFlag, statusReason }
+  const lifecycle = projectLaneLifecycle({
+    events: log,
+    busy: !!busy,
+    pendingCount,
+    pendingReason: BLOCKED_REASON.NEEDS_DECISION,
+    stalled: statusFlag === 'STUCK',
+    failed: failures >= limits.repeatedFailureCount && !busy,
+    rawStatus: statusFlag || (busy ? 'busy' : 'idle'),
+  })
+  return { busy: !!busy, lastActionAt, lastActionAgeMs, statusFlag, statusReason, lifecycle }
 }
 
 export const formatLaneAge = (ageMs) => {
@@ -86,7 +98,7 @@ export const formatLaneAge = (ageMs) => {
   return `${Math.floor(h / 24)}d ago`
 }
 
-const laneStatusText = (x) => `${x.busy ? 'busy' : 'idle'} · ${formatLaneAge(x.lastActionAgeMs)}${x.statusFlag ? ` · ${x.statusFlag}` : ''}`
+const laneStatusText = (x) => `${x.lifecycle?.state || 'Blocked'}${x.lifecycle?.reason ? ` (${x.lifecycle.reason})` : ''} · ${formatLaneAge(x.lastActionAgeMs)}`
 
 const clip = (s, cap) => {
   const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim()
@@ -220,7 +232,7 @@ export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, line
   } else {
     body = cleanPtyTail(hit.buf, n).join('\n') || '(no output yet)'
   }
-  return `Terminal ${label(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
+  return `Terminal ${label(hit)} (${hit.kind} · ${hit.cmd}) · ${laneStatusText(hit)} — last ${n} lines:\n${body}`
 }
 
 // A native Claude Code account failure is provider-wide, not model-specific. Retrying
@@ -406,6 +418,133 @@ export const spawnDecision = ({ hop = 0, spawnTimes = [], now = 0, spawnedLive =
   return { ok: true }
 }
 
+// ── Previewed Dispatch contract ────────────────────────────────────────────
+// The durable pair-control row remains the approval authority. This contract
+// supplies the immutable, secret-free object that row refers to and the bridge
+// rechecks immediately before it spends a lane. No token, provider credential,
+// host path, or mutable process object is copied into the preview.
+const DISPATCH_ARG_KEYS = Object.freeze(['mode', 'model', 'name', 'provider', 'runtime', 'sliceType', 'task'])
+const DISPATCH_MODES = new Set(['default', 'acceptEdits', 'bypassPermissions', 'plan'])
+const DISPATCH_RUNTIMES = new Set(['claude', 'codex'])
+const DISPATCH_SLICES = new Set(['scaffold', 'feature', 'fix', 'review'])
+const secretValue = /((?<![a-z0-9])sk-[a-z0-9_-]{8,}|(?<![a-z0-9])gsk_[a-z0-9_-]{8,}|(?<![a-z0-9])AIza[a-z0-9_-]{8,}|bearer\s+[a-z0-9._-]{8,})/ig
+const hostPath = /(?:\/home\/|\/users\/|\/private\/|\/tmp\/|[a-z]:\\|\\\\)/ig
+const canonical = (value) => {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]))
+  return value
+}
+const sha256 = (value) => createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')
+const bounded = (value, max) => value == null ? null : String(value).slice(0, max)
+const safeCopy = (value, max) => bounded(value, max)?.replace(secretValue, '[credential redacted]').replace(hostPath, '[host path redacted]') || ''
+
+export function normalizeDispatchArgs (args = {}, inherited = {}) {
+  if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some((key) => !DISPATCH_ARG_KEYS.includes(key))) {
+    throw new TypeError('Invalid dispatch arguments')
+  }
+  const runtime = args.runtime || inherited.runtime || 'claude'
+  const mode = args.mode || (inherited.mode === 'plan' ? 'default' : inherited.mode) || 'default'
+  if (!DISPATCH_RUNTIMES.has(runtime) || !DISPATCH_MODES.has(mode) || (args.sliceType && !DISPATCH_SLICES.has(args.sliceType))) {
+    throw new TypeError('Invalid dispatch arguments')
+  }
+  return Object.freeze({
+    name: bounded(args.name, 80),
+    task: bounded(args.task, 12000),
+    model: bounded(args.model, 160),
+    sliceType: bounded(args.sliceType, 24),
+    runtime,
+    provider: bounded(args.provider, 160),
+    mode,
+  })
+}
+
+export function dispatchCapSnapshot ({ hop = 0, spawnTimes = [], now = 0, spawnedLive = 0, totalLive = 0, plan = 'free', disabled = false } = {}, limits = SPAWN) {
+  const o = { ...SPAWN, ...(limits || {}) }
+  const planName = plan === 'plus' ? 'plus' : 'free'
+  const planLimit = maxSpawnedFor(planName, o)
+  return Object.freeze({
+    killSwitch: disabled === true,
+    hop: Object.freeze({ used: Math.max(0, Number(hop) || 0), limit: o.maxHop }),
+    width: Object.freeze({ requested: 1, live: Math.max(0, Number(spawnedLive) || 0), limit: planLimit }),
+    machine: Object.freeze({ live: Math.max(0, Number(totalLive) || 0), limit: o.machineMax }),
+    plan: Object.freeze({ name: planName, price: planName === 'plus' ? '€5/mo' : '€0', used: Math.max(0, Number(spawnedLive) || 0), limit: planLimit }),
+    burst: Object.freeze({ used: recentSpawnCount(spawnTimes, now, o.windowMs), limit: o.perWindowCap, windowMinutes: Math.round(o.windowMs / 60000) }),
+  })
+}
+
+export function buildDispatchPreview ({ args, initiatorTerminalId, roomCode, bridgeAuthorityId, localAuthorityId, context = {}, limits = SPAWN } = {}) {
+  if (!initiatorTerminalId || !roomCode || !bridgeAuthorityId || !localAuthorityId) throw new TypeError('Dispatch authority is incomplete')
+  const exactArgs = normalizeDispatchArgs(args, { runtime: context.runtime, mode: context.mode })
+  const caps = dispatchCapSnapshot(context, limits)
+  // The terminal initiates the request; it is NOT the human approver. The human
+  // actor is bound later by code_pair_control_items.resolved_by plus the matching
+  // durable resolution/delivery-attempt events.
+  const authority = Object.freeze({ initiatorTerminalId: String(initiatorTerminalId), roomCode: String(roomCode).toUpperCase(), bridgeAuthorityId: String(bridgeAuthorityId), localAuthorityId: String(localAuthorityId) })
+  const fingerprint = sha256({ authority, exactArgs, caps })
+  const provider = exactArgs.provider || (exactArgs.runtime === 'codex' ? 'OpenAI / Codex login' : 'Anthropic / host default')
+  const model = exactArgs.model || context.resolvedModel || 'runtime default'
+  const purpose = safeCopy(exactArgs.name || exactArgs.task?.split(/\r?\n/)[0] || 'Open one worker lane', 120)
+  return Object.freeze({
+    version: 1,
+    fingerprint,
+    purpose,
+    packages: Object.freeze([{ title: safeCopy(exactArgs.name || 'Worker package', 80), task: safeCopy(exactArgs.task || 'Open idle for a later hand-off.', 600) }]),
+    runtime: Object.freeze({
+      name: exactArgs.runtime,
+      provider: safeCopy(context.providerName || provider, 120),
+      model: safeCopy(model, 160),
+      band: 'Start: now–1 min · completion: task-dependent',
+      execution: 'Runs locally on the bridge machine; no cloud worker is created.',
+      accountAndSpend: `Uses the host’s ${safeCopy(context.providerName || provider, 100)} account/BYOK. Provider usage is the spend source; ThinkPool has no credit meter.`,
+    }),
+    permissions: Object.freeze({ mode: exactArgs.mode, consequence: exactArgs.mode === 'bypassPermissions'
+      ? 'Unattended local access within this worker’s sandbox and tool policy.'
+      : exactArgs.mode === 'plan' ? 'Planning only; execution remains gated.' : 'Protected local actions keep their normal permission gates.' }),
+    worktree: 'Automatically creates one visible lateral worker lane and an isolated git worktree on this machine.',
+    caps,
+  })
+}
+
+export function authorizeDispatchApproval ({ preview, approvedFingerprint, args, initiatorTerminalId, roomCode, bridgeAuthorityId, localAuthorityId, context = {}, decision = 'allow', consumed = false, permissionId = null, consumedPermissionId = null, limits = SPAWN } = {}) {
+  if (decision !== 'allow') return { ok: false, code: 'dispatch_canceled' }
+  if (consumed) return { ok: false, code: permissionId && permissionId === consumedPermissionId ? 'idempotent_replay' : 'approval_replayed' }
+  let current
+  try { current = buildDispatchPreview({ args, initiatorTerminalId, roomCode, bridgeAuthorityId, localAuthorityId, context, limits }) } catch { return { ok: false, code: 'invalid_dispatch' } }
+  if (!preview || preview.fingerprint !== approvedFingerprint) return { ok: false, code: 'approval_mismatch' }
+  if (current.fingerprint !== preview.fingerprint) return { ok: false, code: 'stale_dispatch' }
+  const gate = spawnDecision(context, limits)
+  if (!gate.ok) return { ok: false, code: 'cap_denied', reason: gate.reason }
+  return { ok: true, code: 'approved', preview: current }
+}
+
+// A public Realtime broadcast is only a wake-up hint. This verifier consumes the
+// rows the bridge re-read through its authenticated room-member token. Exactly one
+// durable winner (resolved_by) must own both the resolution and the single delivery
+// attempt, and every immutable authority/fingerprint field must match.
+export function verifyDurableDispatchAuthority ({ item, events = [], expected = {} } = {}) {
+  const fail = (code) => ({ ok: false, code })
+  const fp = String(expected.fingerprint || '')
+  if (!item || item.id !== expected.controlItemId) return fail('control_item_mismatch')
+  if (item.session_code !== String(expected.roomCode || '').toUpperCase()) return fail('wrong_room')
+  if (item.action_kind !== 'dispatch' || item.item_kind !== 'approval') return fail('wrong_action')
+  if (item.status !== 'resolved' || item.resolution_code !== 'approved' || !item.resolved_by) return fail('not_approved')
+  if (item.resolution_policy !== 'either_member' || item.required_actor_id != null) return fail('wrong_resolution_policy')
+  if (item.bridge_authority_id !== expected.bridgeAuthorityId) return fail('wrong_bridge_authority')
+  if (item.local_authority_id !== expected.localAuthorityId) return fail('wrong_local_authority')
+  if (!/^[0-9a-f]{64}$/.test(fp)) return fail('invalid_fingerprint')
+  if (!String(item.request_context?.action || '').includes(`fp:${fp}`)) return fail('request_fingerprint_mismatch')
+  if (item.resolution_payload?.dispatch_fingerprint !== fp) return fail('resolution_fingerprint_mismatch')
+  const relevant = (Array.isArray(events) ? events : []).filter((event) => event?.item_id === item.id)
+  const resolutions = relevant.filter((event) => event.event_type === 'resolved' && event.actor_id === item.resolved_by &&
+    event.payload?.resolution_payload?.dispatch_fingerprint === fp && event.payload?.resolution_code === 'approved')
+  if (resolutions.length !== 1) return fail('resolution_event_mismatch')
+  const attempts = relevant.filter((event) => event.event_type === 'delivery_attempted' && event.actor_id === item.resolved_by &&
+    event.payload?.data?.dispatch_fingerprint === fp)
+  if (attempts.length !== 1) return fail('delivery_attempt_mismatch')
+  if (relevant.some((event) => event.event_type === 'delivered' || event.event_type === 'delivery_failed')) return fail('delivery_already_final')
+  return { ok: true, code: 'durable_dispatch_authorized', fingerprint: fp, humanActorId: item.resolved_by, attemptKey: attempts[0].correlation_key }
+}
+
 // When a spawn is refused, "close one before opening another" is useless advice if the
 // caller has to go hunting for WHICH one. Rooms fill up with finished lanes nobody
 // closed (Max, 2026-07-10: "clean up the finished ensemble terminals there's a lot"),
@@ -417,8 +556,18 @@ export const spawnDecision = ({ hop = 0, spawnTimes = [], now = 0, spawnedLive =
 // Only lanes this caller spawned are suggested: close_terminal refuses the others, and
 // suggesting a sibling's lane is how you get an agent killing someone else's work.
 export const CLOSABLE_HINT_MAX = 6
+export const closeLaneDecision = ({ callerId, spawnedBy, busy } = {}) => {
+  if (!callerId || spawnedBy !== callerId) return { ok: false, reason: 'not-owner' }
+  if (busy) return { ok: false, reason: 'busy' }
+  return { ok: true }
+}
+
 export const closableLanes = (callerId, lanes = []) =>
-  (Array.isArray(lanes) ? lanes : []).filter((l) => l && l.spawnedBy === callerId && !l.busy)
+  (Array.isArray(lanes) ? lanes : []).filter((l) => l && closeLaneDecision({
+    callerId,
+    spawnedBy: l.spawnedBy,
+    busy: l.busy,
+  }).ok)
 
 export const formatClosableHint = (callerId, lanes = [], max = CLOSABLE_HINT_MAX) => {
   const idle = closableLanes(callerId, lanes)

package/event-id.mjs

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto'
 import { boundStructuredEvent, STRUCTURED_EVENT_CAP } from './event-bounds.mjs'
+import { classifyCodeEvent } from './code-event-contract.mjs'
 
 /* event-id.mjs — stamp a structured event with a stable identity + timestamp
    BEFORE it is logged + broadcast.
@@ -61,8 +62,11 @@ export function makeSeqCounter(startAfter = 0) {
 // consumed a seq + set the durable archive floor while the client dropped them, leaving
 // the client's oldest RENDERED seq above the floor → a phantom "load earlier history"
 // pill on a fresh lane (models fires on every session init) that fetched nothing.
-export const NO_SEQ_KINDS = new Set(['system', 'thinking_tokens', 'effort', 'models', 'model-switch', 'queue-add', 'queue-cancel', 'propose-done', 'update-available'])
-export const seqable = (evt) => !!evt && typeof evt === 'object' && !NO_SEQ_KINDS.has(evt.kind)
+export const NO_SEQ_KINDS = new Set(['system', 'thinking_tokens', 'effort', 'models', 'queue-add', 'queue-cancel', 'propose-done', 'update-available'])
+export const seqable = (evt) => {
+  if (!evt || typeof evt !== 'object') return false
+  return classifyCodeEvent(evt, { strict: false }).known && !NO_SEQ_KINDS.has(evt.kind)
+}
 
 // Highest numeric `seq` across a log of events (0 when none) — the floor a restored
 // session's counter resumes above.

package/lane-lifecycle.mjs

@@ -0,0 +1,181 @@
+import { classifyCodeEvent } from './code-event-contract.mjs'
+
+// This file ships in the standalone thinkpool-pair tarball. Keep the canonical
+// vocabulary here rather than importing from ../src (which is not packaged).
+// The browser-side module re-exports these constants from this file.
+export const LIFECYCLE_STATE = Object.freeze({
+  WORKING: 'Working', BLOCKED: 'Blocked', FAILED: 'Failed', DONE: 'Done', CANCELED: 'Canceled',
+})
+export const BLOCKED_REASON = Object.freeze({
+  NEEDS_DECISION: 'needs_decision', NEEDS_INPUT: 'needs_input', DEPENDENCY: 'dependency',
+  OFFLINE: 'offline', STALLED: 'stalled', UNKNOWN_GAP: 'unknown_gap',
+  VERIFICATION_REQUIRED: 'verification_required',
+})
+
+const TERMINAL = new Set([LIFECYCLE_STATE.FAILED, LIFECYCLE_STATE.DONE, LIFECYCLE_STATE.CANCELED])
+const RESULT_CANCELED = new Set(['aborted', 'cancelled', 'canceled', 'interrupted'])
+
+export function canTransitionLifecycle (from, to, { beginsNewWork = false } = {}) {
+  if (!from || from === to) return true
+  if (TERMINAL.has(from)) return beginsNewWork && to === LIFECYCLE_STATE.WORKING
+  return from === LIFECYCLE_STATE.WORKING || from === LIFECYCLE_STATE.BLOCKED
+}
+
+export function transitionLifecycle (current, next, opts = {}) {
+  if (!canTransitionLifecycle(current?.state, next?.state, opts)) {
+    if (opts.strict !== false) throw new TypeError(`Illegal lifecycle transition: ${current?.state} -> ${next?.state}`)
+    return current
+  }
+  return { ...next, rawStatus: next.rawStatus ?? current?.rawStatus ?? null }
+}
+
+// JSON.stringify's array replacer applies at every nesting level. The previous
+// implementation therefore discarded nested assistant blocks/payload fields and
+// could treat two conflicting events as identical. Sort every object recursively
+// so replay identity compares the complete event, not a top-level silhouette.
+const stableEventShape = (event) => JSON.stringify(event, (_key, value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, value[key]]))
+})
+
+// Replay identity is two-dimensional: cid identifies the optimistic/live event and
+// seq identifies its durable position. A conflict in either dimension is evidence
+// of a split/restarted stream, never a reason to choose whichever array order arrived.
+const normalizeReplayEvents = (events) => {
+  const input = Array.isArray(events) ? events : []
+  const allSequenced = input.every((event) => Number.isFinite(event?.seq))
+  const ordered = input
+    .map((event, sourceIndex) => ({ event, shape: stableEventShape(event), sourceIndex }))
+    .sort((a, b) => {
+      // Old/current optimistic transcript events can legitimately have no seq.
+      // Their array position is the only boundary order; lexical kind sorting
+      // can move a `you` event after its aborted `result` and resurrect a turn.
+      if (!allSequenced) return a.sourceIndex - b.sourceIndex
+      if (a.event.seq !== b.event.seq) return a.event.seq - b.event.seq
+      const at = Number(a.event?.ts) || 0, bt = Number(b.event?.ts) || 0
+      if (at !== bt) return at - bt
+      return String(a.event?.cid || '').localeCompare(String(b.event?.cid || '')) || a.shape.localeCompare(b.shape)
+    })
+  const cids = new Map()
+  const seqs = new Map()
+  const out = []
+  const conflicts = []
+  for (const item of ordered) {
+    const { event, shape } = item
+    const cid = typeof event?.cid === 'string' && event.cid ? event.cid : null
+    const seq = Number.isFinite(event?.seq) ? event.seq : null
+    const cidPrior = cid ? cids.get(cid) : null
+    const seqPrior = seq != null ? seqs.get(seq) : null
+    if (cidPrior || seqPrior) {
+      const prior = cidPrior || seqPrior
+      if (prior.shape !== shape) conflicts.push({ cid, seq, priorCid: prior.cid, priorSeq: prior.seq })
+      continue
+    }
+    const record = { cid, seq, shape }
+    if (cid) cids.set(cid, record)
+    if (seq != null) seqs.set(seq, record)
+    out.push(event)
+  }
+  return { events: out, conflicts }
+}
+
+const base = (state, reason = null, extra = {}) => ({ state, reason, phase: null, freshness: 'current', transport: 'online', rawStatus: null, verified: false, ...extra })
+
+export function projectLaneLifecycle ({
+  events = [], busy = false, pendingCount = 0, pendingReason = null,
+  stalled = false, offline = false, stale = false, failed = false, canceled = false,
+  rawStatus = null,
+} = {}) {
+  let out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_INPUT, { rawStatus })
+  const replay = normalizeReplayEvents(events)
+  let unknownEvent = false
+  for (const event of replay.events) {
+    const contract = classifyCodeEvent(event, { strict: false })
+    if (!contract.known) { unknownEvent = true; continue }
+    if (contract.eventClass === 'volatile-presence') continue
+    if (event.kind === 'pool' && (event.transient || event.pending)) {
+      continue
+    }
+    if (event.kind === 'you' || event.kind === 'assistant' || event.kind === 'tool_result' || event.kind === 'pool') {
+      out = base(LIFECYCLE_STATE.WORKING, null, { rawStatus, phase: event.kind })
+    } else if (event.kind === 'propose' || event.kind === 'answer') {
+      out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_DECISION, { rawStatus })
+    } else if (event.kind === 'needs-input') {
+      out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_INPUT, { rawStatus })
+    } else if (event.kind === 'error') {
+      out = base(LIFECYCLE_STATE.FAILED, null, { rawStatus })
+    } else if (event.kind === 'result') {
+      if (RESULT_CANCELED.has(event.subtype)) out = base(LIFECYCLE_STATE.CANCELED, null, { rawStatus })
+      else if (event.subtype && event.subtype !== 'success') out = base(LIFECYCLE_STATE.FAILED, null, { rawStatus })
+      // An agent-supplied `verified` field (or a broad caller flag) is only a
+      // claim. Foundation B will wire an authority-bound receipt; Foundation A
+      // deliberately cannot make a lane Done from transcript evidence alone.
+      else out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.VERIFICATION_REQUIRED, { rawStatus })
+    }
+  }
+
+  if (replay.conflicts.length || unknownEvent) out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.UNKNOWN_GAP, { rawStatus })
+  else if (failed) out = base(LIFECYCLE_STATE.FAILED, null, { rawStatus })
+  else if (canceled) out = base(LIFECYCLE_STATE.CANCELED, null, { rawStatus })
+  else if (pendingCount > 0) out = base(LIFECYCLE_STATE.BLOCKED, pendingReason || BLOCKED_REASON.NEEDS_DECISION, { rawStatus })
+  else if (stalled) out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.STALLED, { rawStatus, phase: 'stalled' })
+  else if (busy && !TERMINAL.has(out.state)) out = base(LIFECYCLE_STATE.WORKING, null, { rawStatus, phase: out.phase || 'active' })
+  else if (offline && !TERMINAL.has(out.state)) out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.OFFLINE, { rawStatus })
+
+  if (offline) out.transport = 'offline'
+  if (stale) out.freshness = 'stale'
+  return Object.freeze(out)
+}
+
+export function projectFlowLifecycle (rawStatus) {
+  switch (rawStatus) {
+    case 'building': case 'dispatched': case 'reviewing': case 'assembling': case 'planning':
+      return base(LIFECYCLE_STATE.WORKING, null, { rawStatus, phase: rawStatus })
+    case 'awaiting_approval': case 'approved':
+      return base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_DECISION, { rawStatus })
+    case 'pending': case 'ready': case 'reverted':
+      return base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.DEPENDENCY, { rawStatus })
+    case 'failed': return base(LIFECYCLE_STATE.FAILED, null, { rawStatus })
+    case 'cancelled': case 'canceled': return base(LIFECYCLE_STATE.CANCELED, null, { rawStatus })
+    // A task's commit and an assembled artifact are evidence, not an observed
+    // verification receipt. No caller-provided boolean can promote Flow to Done.
+    case 'done': return base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.VERIFICATION_REQUIRED, { rawStatus })
+    default: return base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_INPUT, { rawStatus })
+  }
+}
+
+export function projectRecoveryWatermark ({ events = [], epoch = 0, floor = null, gap = null, offline = false, stale = false } = {}) {
+  const replay = normalizeReplayEvents(events)
+  const foreignEpoch = replay.events.some((e) => Number.isFinite(e?.epoch) && e.epoch !== epoch)
+  const seqEvents = replay.events.filter((e) => Number.isFinite(e?.seq) && (!Number.isFinite(e?.epoch) || e.epoch === epoch))
+  const last = seqEvents.reduce((best, e) => !best || e.seq > best.seq ? e : best, null)
+  let unknownGap = gap && Number.isFinite(gap.from) && Number.isFinite(gap.to)
+    ? { from: gap.from, to: gap.to, reason: gap.reason || 'unknown', recoverable: gap.recoverable !== false }
+    : null
+  if (!unknownGap && (replay.conflicts.length || foreignEpoch)) {
+    const seqs = replay.conflicts.map((c) => c.seq).filter(Number.isFinite)
+    unknownGap = {
+      from: seqs.length ? Math.min(...seqs) : null,
+      to: seqs.length ? Math.max(...seqs) : null,
+      reason: replay.conflicts.length ? 'conflicting_event_identity' : 'foreign_epoch',
+      recoverable: true,
+    }
+  }
+  if (!unknownGap && seqEvents.length > 1) {
+    for (let i = 1; i < seqEvents.length; i++) {
+      if (seqEvents[i].seq > seqEvents[i - 1].seq + 1) {
+        unknownGap = { from: seqEvents[i - 1].seq + 1, to: seqEvents[i].seq - 1, reason: 'out_of_order_or_trimmed', recoverable: true }
+        break
+      }
+    }
+  }
+  return Object.freeze({
+    epoch,
+    floor: Number.isFinite(floor) ? floor : null,
+    lastProven: last ? { cid: last.cid || null, seq: last.seq, epoch } : null,
+    unknownGap,
+    freshness: stale ? 'stale' : 'current',
+    transport: offline ? 'offline' : 'online',
+    globalRollbackAvailable: false,
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.242",
+  "version": "0.7.244",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -33,6 +33,8 @@
     "update-gate.mjs",
     "agent-notify.mjs",
     "agent-detect.mjs",
+    "code-event-contract.mjs",
+    "pair-control-authority.mjs",
     "event-id.mjs",
     "event-bounds.mjs",
     "plan-meters.mjs",
@@ -41,6 +43,7 @@
     "session-store.mjs",
     "side-lane.mjs",
     "cross-terminal.mjs",
+    "lane-lifecycle.mjs",
     "interrupted-resume.mjs",
     "flow-conductor.mjs",
     "flow-worktree.mjs",

package/pair-control-authority.mjs

@@ -0,0 +1,76 @@
+// Durable authority check for the bridge's public `code-perm` transport.
+// Realtime is only a wake-up hint: the owner-authenticated REST reads below
+// must reproduce the resolved item and its unique delivery-attempt record before
+// a local pending action is allowed to move.
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const SAFE_KEY = /^[A-Za-z0-9][A-Za-z0-9._:@-]{7,159}$/
+const FINAL_STATUS = new Set(['resolved', 'denied'])
+
+const denied = (code) => Object.freeze({ ok: false, code })
+
+export function verifyPairControlDeliveryAuthority ({ item, attempts, payload, roomCode, bridgeId } = {}) {
+  if (!item || !payload || !UUID.test(String(payload.controlItemId || '')) ||
+      !SAFE_KEY.test(String(payload.attemptKey || '')) ||
+      !Number.isSafeInteger(payload.controlVersion) || payload.controlVersion < 1) {
+    return denied('invalid_delivery_hint')
+  }
+  const context = item.request_context
+  const resolution = item.resolution_payload
+  if (item.id !== payload.controlItemId || item.session_code !== String(roomCode || '').toUpperCase() ||
+      item.item_kind !== 'approval' || !['approval', 'dispatch'].includes(item.action_kind) ||
+      item.resolution_policy !== 'either_member' || item.required_actor_id != null ||
+      !FINAL_STATUS.has(item.status) || Number(item.version) !== payload.controlVersion ||
+      item.bridge_authority_id !== bridgeId || item.local_authority_id !== payload.term ||
+      !context || context.permission_id !== payload.id || context.terminal_ref !== payload.term ||
+      !resolution || resolution.decision !== payload.decision || !item.resolved_by) {
+    return denied('authority_mismatch')
+  }
+  if ((item.status === 'resolved' && !['approved', 'answered'].includes(item.resolution_code)) ||
+      (item.status === 'denied' && item.resolution_code !== 'rejected')) {
+    return denied('resolution_mismatch')
+  }
+  const matching = Array.isArray(attempts) ? attempts.filter((event) =>
+    event?.actor_id === item.resolved_by && Number(event.item_version) === Number(item.version) &&
+    event.correlation_key === payload.attemptKey && event.payload?.data?.transport === 'code-perm') : []
+  if (matching.length !== 1) return denied('delivery_attempt_unverified')
+  return Object.freeze({
+    ok: true,
+    code: 'durable_delivery_authorized',
+    decision: resolution.decision,
+    itemId: item.id,
+    version: Number(item.version),
+    attemptKey: payload.attemptKey,
+  })
+}
+
+export async function fetchPairControlDeliveryAuthority ({
+  fetchImpl = globalThis.fetch, supabaseUrl, anonKey, token, roomCode, bridgeId, payload,
+} = {}) {
+  if (typeof fetchImpl !== 'function' || !supabaseUrl || !anonKey || !token || !roomCode || !bridgeId ||
+      !UUID.test(String(payload?.controlItemId || '')) || !SAFE_KEY.test(String(payload?.attemptKey || ''))) {
+    return denied('authority_unavailable')
+  }
+  const headers = { apikey: anonKey, Authorization: `Bearer ${token}` }
+  const itemUrl = new URL('/rest/v1/code_pair_control_items', supabaseUrl)
+  itemUrl.searchParams.set('id', `eq.${payload.controlItemId}`)
+  itemUrl.searchParams.set('session_code', `eq.${String(roomCode).toUpperCase()}`)
+  itemUrl.searchParams.set('select', 'id,session_code,item_kind,action_kind,resolution_policy,required_actor_id,status,version,resolution_code,resolution_payload,resolved_by,bridge_authority_id,local_authority_id,request_context')
+  const eventUrl = new URL('/rest/v1/code_pair_control_events', supabaseUrl)
+  eventUrl.searchParams.set('item_id', `eq.${payload.controlItemId}`)
+  eventUrl.searchParams.set('event_type', 'eq.delivery_attempted')
+  eventUrl.searchParams.set('correlation_key', `eq.${payload.attemptKey}`)
+  eventUrl.searchParams.set('select', 'actor_id,item_version,correlation_key,payload')
+  eventUrl.searchParams.set('limit', '2')
+  try {
+    const [itemResponse, eventResponse] = await Promise.all([
+      fetchImpl(itemUrl, { headers }), fetchImpl(eventUrl, { headers }),
+    ])
+    if (!itemResponse.ok || !eventResponse.ok) return denied('authority_read_failed')
+    const [items, attempts] = await Promise.all([itemResponse.json(), eventResponse.json()])
+    if (!Array.isArray(items) || items.length !== 1 || !Array.isArray(attempts)) return denied('authority_read_invalid')
+    return verifyPairControlDeliveryAuthority({ item: items[0], attempts, payload, roomCode, bridgeId })
+  } catch {
+    return denied('authority_read_failed')
+  }
+}