@try-works/dsh-recursive-mode 0.1.0

package/src/lock.ts

@@ -0,0 +1,369 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Lock-hash + lock-chain validation for recursive-mode runs.
+ *
+ * Ports recursive-lock.py / verify-locks.py / recursive_phase_rules.py
+ * semantics (byte-for-byte where observable):
+ * - lockHashFromContent: LF-normalize, strip LockHash lines, SHA-256 hex
+ * - getLockStatus: MISSING / DRAFT / STALE_LOCK / LOCKED
+ * - getPrerequisites / getPrerequisiteBlockers: sequence ordering
+ * - validateChain: per-phase validity + break + next legal phase
+ * - receipts: read/write/invalidate with Python-identical JSON
+ *
+ * R3 (run 02).
+ */
+
+export const PHASE_SEQUENCE = [
+  '00-requirements.md',
+  '00-worktree.md',
+  '01-as-is.md',
+  '01.5-root-cause.md',
+  '02-to-be-plan.md',
+  '03-implementation-summary.md',
+  '03.5-code-review.md',
+  '04-test-summary.md',
+  '05-manual-qa.md',
+  '06-decisions-update.md',
+  '07-state-update.md',
+  '08-memory-impact.md',
+] as const
+
+export const OPTIONAL_PHASES = new Set([
+  '01-as-is.md',
+  '01.5-root-cause.md',
+  '02-to-be-plan.md',
+  '03-implementation-summary.md',
+  '03.5-code-review.md',
+  '04-test-summary.md',
+  '05-manual-qa.md',
+])
+
+const LOCK_HASH_LINE_RE = /^[ \t]*LockHash:.*(?:\n|$)/gm
+const STATUS_RE = new RegExp('^[ \\t]*Status:\\s*(?:`|")?(\\w+)(?:`|")?\\s*$', 'm')
+const LOCK_HASH_RE = new RegExp('^[ \\t]*LockHash:\\s*(?:`|")?([a-fA-F0-9]{64})(?:`|")?\\s*$', 'm')
+const LOCKED_AT_RE = new RegExp('^[ \\t]*LockedAt:\\s*(?:`|")?([^`"\\r\\n]+)(?:`|")?\\s*$', 'm')
+
+export interface LockReceipt {
+  artifact: string
+  artifact_path: string
+  artifact_hash: string
+  locked_at: string
+  prerequisite_hashes: Record<string, string>
+  previous_receipt_hash: string | null
+  receipt_hash: string
+}
+
+export type LockStatus = 'MISSING' | 'DRAFT' | 'STALE_LOCK' | 'LOCKED'
+
+export interface PrerequisiteBlocker {
+  artifact: string
+  status: string
+  path: string
+}
+
+export interface StaleDownstream {
+  artifact: string
+  reason: string
+}
+
+export interface ChainPhaseResult {
+  file: string
+  status: LockStatus
+  lockValid: boolean
+  lockProblems: string[]
+}
+
+export interface LockChainResult {
+  runId: string
+  phases: ChainPhaseResult[]
+  breakPhase: string | null
+  nextLegalPhase: string | null
+  complete: boolean
+  staleReceipts: StaleDownstream[]
+}
+
+/** LF-normalize, strip every LockHash: line, return the normalized content. */
+export function normalizeForLockHash(content: string): string {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  return normalized.replace(LOCK_HASH_LINE_RE, '')
+}
+
+/** SHA-256 hex over the UTF-8 bytes of the normalized content. */
+export function lockHashFromContent(content: string): string {
+  const normalized = normalizeForLockHash(content)
+  return createHash('sha256').update(normalized, 'utf8').digest('hex')
+}
+
+export function phaseIndex(artifactFile: string): number {
+  return PHASE_SEQUENCE.indexOf(artifactFile as (typeof PHASE_SEQUENCE)[number])
+}
+
+export function isCoreArtifact(artifactFile: string): boolean {
+  return phaseIndex(artifactFile) >= 0
+}
+
+/**
+ * Every earlier phase in PHASE_SEQUENCE that exists on disk.
+ * Mirrors: [phase for phase in PHASE_SEQUENCE[:idx] if (run_dir / phase).exists()]
+ */
+export function getPrerequisites(runDir: string, artifactFile: string): string[] {
+  const idx = phaseIndex(artifactFile)
+  if (idx <= 0) return []
+  const prereqs: string[] = []
+  for (const phase of PHASE_SEQUENCE.slice(0, idx)) {
+    if (existsSync(join(runDir, phase))) prereqs.push(phase)
+  }
+  return prereqs
+}
+
+/**
+ * Canonical lock-validity classifier:
+ * MISSING (no file) / DRAFT (not LOCKED) / STALE_LOCK (missing or mismatched hash fields) / LOCKED.
+ */
+export function getLockStatus(artifactPath: string): LockStatus {
+  if (!existsSync(artifactPath)) return 'MISSING'
+  let content: string
+  try { content = readFileSync(artifactPath, 'utf8') } catch { return 'MISSING' }
+  const statusMatch = STATUS_RE.exec(content)
+  if (!statusMatch || statusMatch[1] !== 'LOCKED') return 'DRAFT'
+  const hashMatch = LOCK_HASH_RE.exec(content)
+  const lockedAtMatch = LOCKED_AT_RE.exec(content)
+  if (!hashMatch || !lockedAtMatch) return 'STALE_LOCK'
+  const storedHash = hashMatch[1].toLowerCase()
+  const actualHash = lockHashFromContent(content)
+  if (storedHash !== actualHash) return 'STALE_LOCK'
+  return 'LOCKED'
+}
+
+/** Every prerequisite whose status is not LOCKED, in PHASE_SEQUENCE order. */
+export function getPrerequisiteBlockers(runDir: string, artifactFile: string): PrerequisiteBlocker[] {
+  const blockers: PrerequisiteBlocker[] = []
+  for (const prereq of getPrerequisites(runDir, artifactFile)) {
+    const status = getLockStatus(join(runDir, prereq))
+    if (status !== 'LOCKED') {
+      blockers.push({ artifact: prereq, status, path: join(runDir, prereq) })
+    }
+  }
+  return blockers
+}
+
+export function receiptPath(runDir: string, artifactFile: string): string {
+  const stem = artifactFile.replace(/\.md$/, '')
+  return join(runDir, 'locks', stem + '.receipt.json')
+}
+
+export function readReceipt(runDir: string, artifactFile: string): LockReceipt | null {
+  const rpath = receiptPath(runDir, artifactFile)
+  if (!existsSync(rpath)) return null
+  try {
+    return JSON.parse(readFileSync(rpath, 'utf8')) as LockReceipt
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write a lock receipt with Python-identical JSON semantics.
+ */
+export function writeReceipt(runDir: string, artifactFile: string, artifactPath: string): LockReceipt {
+  const content = readFileSync(artifactPath, 'utf8')
+  const artifactHash = lockHashFromContent(content)
+
+  const prereqHashes: Record<string, string> = {}
+  for (const prereq of getPrerequisites(runDir, artifactFile)) {
+    const prereqPath = join(runDir, prereq)
+    if (existsSync(prereqPath)) {
+      const prereqStatus = getLockStatus(prereqPath)
+      if (prereqStatus !== 'LOCKED') {
+        throw new Error(`Cannot write receipt for '${artifactFile}': prerequisite '${prereq}' is not LOCKED (status: ${prereqStatus})`)
+      }
+      prereqHashes[prereq] = lockHashFromContent(readFileSync(prereqPath, 'utf8'))
+    }
+  }
+
+  const existing = readReceipt(runDir, artifactFile)
+  const prevReceiptHash: string | null = existing ? existing.receipt_hash : null
+
+  const now = new Date()
+  const lockedAt = now.toISOString().replace(/\.\d{3}Z$/, 'Z')
+
+  const base: Omit<LockReceipt, 'receipt_hash'> = {
+    artifact: artifactFile,
+    artifact_path: artifactPath,
+    artifact_hash: artifactHash,
+    locked_at: lockedAt,
+    prerequisite_hashes: prereqHashes,
+    previous_receipt_hash: prevReceiptHash,
+  }
+
+  // Python json.dumps(sort_keys=True) compact serialization:
+  // keys sorted lexicographically, separators (', ', ': '), ensure_ascii.
+  const receiptHash = createHash('sha256').update(pythonJsonDumps(base), 'utf8').digest('hex')
+
+  const receipt: LockReceipt = { ...base, receipt_hash: receiptHash }
+
+  const locksDir = join(runDir, 'locks')
+  mkdirSync(locksDir, { recursive: true })
+  const rpath = receiptPath(runDir, artifactFile)
+  writeFileSync(rpath, pythonJsonDumpsIndent(receipt), 'utf8')
+  return receipt
+}
+
+export function invalidateReceipt(runDir: string, artifactFile: string): boolean {
+  const rpath = receiptPath(runDir, artifactFile)
+  if (existsSync(rpath)) {
+    rmSync(rpath, { force: true })
+    return true
+  }
+  return false
+}
+
+/**
+ * Downstream phases (strictly after artifactFile in PHASE_SEQUENCE) whose
+ * receipt's prerequisite_hashes[artifactFile] differs from the current hash
+ * (or the artifact no longer exists).
+ */
+export function getStaleDownstreamPhases(runDir: string, artifactFile: string): StaleDownstream[] {
+  const idx = phaseIndex(artifactFile)
+  if (idx < 0) return []
+  let currentHash: string | null = null
+  const artifactPath = join(runDir, artifactFile)
+  if (existsSync(artifactPath)) {
+    currentHash = lockHashFromContent(readFileSync(artifactPath, 'utf8'))
+  }
+  const stale: StaleDownstream[] = []
+  for (const downstream of PHASE_SEQUENCE.slice(idx + 1)) {
+    const receipt = readReceipt(runDir, downstream)
+    if (!receipt) continue
+    const prereqHashes = receipt.prerequisite_hashes ?? {}
+    if (!(artifactFile in prereqHashes)) continue
+    const storedHash = prereqHashes[artifactFile]
+    if (currentHash === null || storedHash !== currentHash) {
+      stale.push({ artifact: downstream, reason: `prerequisite '${artifactFile}' hash changed` })
+    }
+  }
+  return stale
+}
+
+export function getNextLegalPhase(runDir: string): string | null {
+  for (const phase of PHASE_SEQUENCE) {
+    const phasePath = join(runDir, phase)
+    const status = getLockStatus(phasePath)
+    if (status === 'LOCKED') continue
+    if (!existsSync(phasePath) && OPTIONAL_PHASES.has(phase)) continue
+    if (getPrerequisiteBlockers(runDir, phase).length > 0) return null
+    return phase
+  }
+  return null
+}
+
+/** All receipts whose prerequisite_hashes reference a missing or changed artifact. */
+export function getAllStaleReceipts(runDir: string): StaleDownstream[] {
+  const stale: StaleDownstream[] = []
+  for (const phase of PHASE_SEQUENCE) {
+    const receipt = readReceipt(runDir, phase)
+    if (!receipt) continue
+    const prereqHashes = receipt.prerequisite_hashes ?? {}
+    for (const [prereq, storedHash] of Object.entries(prereqHashes)) {
+      const prereqPath = join(runDir, prereq)
+      if (!existsSync(prereqPath)) {
+        stale.push({ artifact: phase, reason: `prerequisite '${prereq}' no longer exists` })
+        continue
+      }
+      const currentHash = lockHashFromContent(readFileSync(prereqPath, 'utf8'))
+      if (storedHash !== currentHash) {
+        stale.push({ artifact: phase, reason: `prerequisite '${prereq}' content changed since lock at ${receipt.locked_at}` })
+      }
+    }
+  }
+  return stale
+}
+
+/**
+ * Validate the full lock chain of a run: per-phase lock status, break phase,
+ * next legal phase, completion, and stale receipts.
+ */
+export function validateChain(runDir: string, runId: string): LockChainResult {
+  const phases: ChainPhaseResult[] = []
+  let breakPhase: string | null = null
+  let complete = true
+  for (const phase of PHASE_SEQUENCE) {
+    const phasePath = join(runDir, phase)
+    const status = getLockStatus(phasePath)
+    const problems: string[] = []
+    const lockValid = status === 'LOCKED'
+    if (!lockValid && breakPhase === null) {
+      breakPhase = phase
+      complete = false
+    }
+    if (!lockValid && status !== 'MISSING') {
+      if (status === 'DRAFT') problems.push(`Status is not LOCKED (${status})`)
+      else if (status === 'STALE_LOCK') problems.push('LockHash mismatch or missing lock fields')
+    }
+    phases.push({ file: phase, status, lockValid, lockProblems: problems })
+  }
+  const nextLegalPhase = getNextLegalPhase(runDir)
+  const staleReceipts = getAllStaleReceipts(runDir)
+  return { runId, phases, breakPhase, nextLegalPhase, complete, staleReceipts }
+}
+
+/**
+ * Python json.dumps(obj, sort_keys=True, separators=(', ', ': '), ensure_ascii=True)
+ * compact serialization. Exported for parity testing against the Python oracle.
+ */
+export function serializeForReceiptHash(obj: object): string {
+  return pythonJsonDumps(obj)
+}
+
+/** Python json.dumps(obj, sort_keys=True) compact serialization (receipt_hash input). */
+function pythonJsonDumps(obj: object): string {
+  const rec = obj as Record<string, unknown>
+  const keys = Object.keys(rec).sort()
+  const parts = keys.map(key => {
+    const value = rec[key]
+    return `${jsonString(key)}: ${jsonValue(value)}`
+  })
+  return '{' + parts.join(', ') + '}'
+}
+
+/** Python json.dumps(obj, indent=2, sort_keys=True) disk serialization. */
+function pythonJsonDumpsIndent(obj: object): string {
+  const rec = obj as Record<string, unknown>
+  const keys = Object.keys(rec).sort()
+  const inner = keys.map(key => {
+    const value = rec[key]
+    return '  ' + jsonString(key) + ': ' + jsonValueIndent(value, 2)
+  })
+  return '{\n' + inner.join(',\n') + '\n}'
+}
+
+function jsonString(s: string): string {
+  return JSON.stringify(s)
+}
+
+function jsonValue(value: unknown): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string') return jsonString(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (Array.isArray(value)) return '[' + value.map(jsonValue).join(', ') + ']'
+  if (typeof value === 'object') return pythonJsonDumps(value as Record<string, unknown>)
+  return 'null'
+}
+
+function jsonValueIndent(value: unknown, depth: number): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string') return jsonString(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (Array.isArray(value)) return '[' + value.map(v => jsonValueIndent(v, depth)).join(', ') + ']'
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>
+    const keys = Object.keys(obj).sort()
+    const pad = '  '.repeat(depth)
+    const inner = keys.map(key => pad + '  ' + jsonString(key) + ': ' + jsonValueIndent(obj[key], depth + 1))
+    return '{\n' + inner.join(',\n') + '\n' + pad + '}'
+  }
+  return 'null'
+}

package/src/policy.ts

@@ -0,0 +1,56 @@
+/**
+ * recursive:policy prompt-section renderer (Phase C R5, PROPOSAL 8.4 Layer 3).
+ * Renders the CURRENT phase's contract from folded state + enforcement config:
+ * what must exist before advancing, which tools are denied/asked this phase,
+ * the strict/pragmatic TDD mode, the QA mode, and the lock chain - the same
+ * rules the machine gates enforce (no prompt/gate contradiction).
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { PHASE_SEQUENCE, getLockStatus } from './lock.ts'
+import { foldRun } from './status.ts'
+import type { RecursivePhaseState } from './lifecycle.ts'
+import type { EnforcementConfig } from './enforcement.ts'
+import { DEFAULT_ENFORCEMENT } from './enforcement.ts'
+
+export interface PolicyContext {
+  worktreeRoot: string
+  runId: string
+  folded: RecursivePhaseState | null
+  config?: EnforcementConfig
+}
+
+/**
+ * Render the current-phase contract. Empty string when no run is active.
+ */
+export function renderRecursivePolicy(context: PolicyContext | null): string {
+  if (!context || !context.runId) return ''
+  const runDir = join(context.worktreeRoot, '.recursive', 'run', context.runId)
+  const folded = context.folded ?? null
+  const config = context.config ?? DEFAULT_ENFORCEMENT
+
+  // Derive the current phase from files (never trust an unchecked fold).
+  let currentPhase = folded?.phase ?? ''
+  let nextRequired = ''
+  const status = existsSync(runDir) ? foldRun(runDir, context.runId) : null
+  if (status?.currentPhase) {
+    currentPhase = status.currentPhase.label + ' (' + status.currentPhase.status + ')'
+    nextRequired = status.currentPhase.phaseName + ' (' + status.currentPhase.key + ')'
+  }
+
+  const strictness = (gate: EnforcementConfig[keyof EnforcementConfig]) => gate
+  const lines = [
+    'You are in a recursive-mode session (enforcement active).',
+    '- Current phase: ' + (currentPhase || 'unknown'),
+    '- Next required artifact: ' + (nextRequired || 'none - run complete'),
+    '- Lock chain: phases lock monotonically (' + PHASE_SEQUENCE.join(' -> ') + ').',
+    '- Gates in force: pre-step ' + strictness(config.preStep) + ', tool guards ' + strictness(config.toolGuards) + ', tamper ' + strictness(config.tamper) + '.',
+    '- A transition that fails its gates is BLOCKED (strict) or warns (advisory); no rejected transition advances state.',
+    '- Writes to a Status: LOCKED phase doc are denied/asked; reopen explicitly to edit.',
+    '- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA sign-off for human/hybrid modes.',
+    '- The control-plane root is resolved STRICTLY from this session workspace (never scan other workspaces).',
+    '- Scratch is disposable, git-ignored, and never citable as an Input.',
+    '- The workflow spec lives at /.recursive/RECURSIVE.md; bootstrap it when missing.',
+  ]
+  return lines.join('\n')
+}

package/src/projection.ts

@@ -0,0 +1,237 @@
+/**
+ * recursive session projection unit (Phase D R2/R9, PROPOSAL 11.2/11.4): the
+ * pure fold that maps SessionEvent[] -> per-run wire-JSON, grouped by
+ * worktree root first then runId. The board, inspector, node, and strip all
+ * render from this whole value; the client NEVER scrapes /.recursive/run/.
+ *
+ * The unit is three pure synchronous functions (init/apply/view) plus a zod
+ * schema + stateVersion (the session-projection ProjectionDefinition
+ * contract). apply returns the same state reference for unrelated events
+ * (Object.is zero-work rule), so non-recursive sessions cost nothing.
+ *
+ * Worktree scoping (binding invariant, run 03 R1): the fold only commits a
+ * recursive/* event whose worktreeRoot is INSIDE the workspace control-plane
+ * root captured at registration; out-of-workspace events are dropped.
+ *
+ * The core fold is structural (RecursiveEventLike) so it is unit-testable
+ * without a live session; the ProjectionDefinition adapts the framework's
+ * SessionEvent to it.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { z as zod } from 'zod'
+import type { ZodType } from 'zod'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import type { RecursiveProjection, RecursiveRunCard, RecursiveRunState, RecursivePhaseRow, RecursiveGateBlock, RecursiveTamper, RecursiveSubagent } from './types.ts'
+
+/** Declare the 'recursive' projection key on the shared type table. */
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    /** Runs grouped by worktree root, then runId. */
+    recursive: RecursiveProjection
+  }
+}
+
+/** Structural event shape the pure fold reads (unit-testable without a session). */
+export interface RecursiveEventLike {
+  type: string
+  data?: Record<string, unknown>
+}
+
+/** Mutable fold accumulator (private to the pure fold; never leaks). */
+export interface RecursiveFoldState {
+  /** The workspace control-plane root this unit is scoped to ('' = accept all). */
+  workspaceRoot: string
+  /** Runs grouped by worktree root then runId. */
+  byWorktree: RecursiveProjection
+}
+
+export function emptyRecursiveFoldState(workspaceRoot = ''): RecursiveFoldState {
+  // B6: the unit itself has no session/agent to learn the workspace root from —
+  // init() is synchronous and receives no context. The EMITTERS are the scope
+  // authority: they resolve the control-plane root per-call and never append a
+  // cross-workspace event. workspaceRoot = '' (accept-all) is therefore a
+  // per-session safety default, not a no-op: (a) each session's projection cell
+  // is its own workspace (the log belongs to one agent), and (b) the re-key
+  // guard still refuses a merge whose repoRoot falls outside the captured
+  // root. A host that registers a session-scoped root may still pass it; the
+  // default is the per-session invariant, not a cross-workspace hole.
+  return { workspaceRoot, byWorktree: {} }
+}
+
+/** Whether a worktreeRoot is inside (or equal to) the workspace root. */
+export function isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean {
+  if (workspaceRoot === '') return true
+  const w = worktreeRoot.replace(/\\/g, '/').replace(/\/$/, '')
+  const r = workspaceRoot.replace(/\\/g, '/').replace(/\/$/, '')
+  return w === r || w.startsWith(r + '/')
+}
+
+function ensureCard(state: RecursiveFoldState, runId: string, worktreeRoot: string): RecursiveRunCard {
+  let tree = state.byWorktree[worktreeRoot]
+  if (tree === undefined) {
+    tree = {}
+    state.byWorktree[worktreeRoot] = tree
+  }
+  let card = tree[runId]
+  if (card === undefined) {
+    card = { runId, worktreeRoot, phases: {}, state: 'active', tampers: {}, subagents: {} }
+    tree[runId] = card
+  }
+  return card
+}
+
+function asRunState(value: unknown): RecursiveRunState {
+  return value === 'new' || value === 'active' || value === 'paused' || value === 'blocked' || value === 'complete'
+    ? value as RecursiveRunState
+    : 'active'
+}
+
+/** Pure transition: previous state + one committed event -> next state. */
+/** Internal transition signals (never commit into the projection). */
+const INTERNAL_RECURSIVE_EVENTS = new Set(['recursive/phase-intent'])
+
+export function foldRecursiveProjection(state: RecursiveFoldState, event: RecursiveEventLike): RecursiveFoldState {
+  const type = event.type
+  if (typeof type !== 'string' || !type.startsWith('recursive/')) return state
+  if (INTERNAL_RECURSIVE_EVENTS.has(type)) return state
+  const data = event.data ?? {}
+  const runId = typeof data.runId === 'string' ? data.runId : ''
+  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
+  if (runId === '' || worktreeRoot === '') return state
+  // Binding workspace-scoping invariant: drop out-of-workspace events.
+  if (!isInsideWorkspace(worktreeRoot, state.workspaceRoot)) return state
+
+  const card = ensureCard(state, runId, worktreeRoot)
+
+  switch (type) {
+    case 'recursive/run-created': {
+      if (typeof data.template === 'string') card.template = data.template
+      if (typeof data.repo === 'string') card.repo = data.repo
+      return state
+    }
+    case 'recursive/phase': {
+      const phase = String(data.phase ?? '')
+      if (phase === '') return state
+      const row: RecursivePhaseRow = card.phases[phase] ?? { phase, status: String(data.status ?? '') }
+      row.status = String(data.status ?? '')
+      card.phases[phase] = row
+      return state
+    }
+    case 'recursive/phase-locked': {
+      const phase = String(data.phase ?? '')
+      if (phase === '') return state
+      const row: RecursivePhaseRow = card.phases[phase] ?? { phase, status: 'LOCKED' }
+      row.status = 'LOCKED'
+      row.lockedAt = String(data.lockedAt ?? '')
+      row.lockHash = String(data.lockHash ?? '')
+      card.phases[phase] = row
+      return state
+    }
+    case 'recursive/gate-blocked': {
+      const gate: RecursiveGateBlock = {
+        failures: Array.isArray(data.failures) ? data.failures.map(String) : [],
+        kind: String(data.kind ?? ''),
+      }
+      card.gateBlocked = gate
+      return state
+    }
+    case 'recursive/tamper': {
+      const path = String(data.path ?? '')
+      if (path === '') return state
+      const t: RecursiveTamper = { path, reason: String(data.reason ?? '') }
+      card.tampers[path] = t
+      return state
+    }
+    case 'recursive/run-merged': {
+      const repoRoot = typeof data.repoRoot === 'string' ? data.repoRoot : ''
+      if (repoRoot === '') return state
+      // R9: a merged run is listed under the repo root, not the stale worktree
+      // path. Re-key by moving the card across the outer group — but only when
+      // the repo root itself is inside the workspace (binding invariant);
+      // otherwise the merge note is recorded without crossing scope.
+      card.mergedToRepoRoot = repoRoot
+      if (isInsideWorkspace(repoRoot, state.workspaceRoot)) {
+        const tree = state.byWorktree[worktreeRoot]
+        if (tree !== undefined && tree[runId] === card) {
+          delete tree[runId]
+          if (Object.keys(tree).length === 0) delete state.byWorktree[worktreeRoot]
+        }
+        const target = state.byWorktree[repoRoot] ?? (state.byWorktree[repoRoot] = {})
+        target[runId] = card
+        // The card's own worktreeRoot now reflects the merge target.
+        card.worktreeRoot = repoRoot
+      }
+      return state
+    }
+    case 'recursive/run-state': {
+      card.state = asRunState(data.state)
+      if (typeof data.reason === 'string') card.stateReason = data.reason
+      return state
+    }
+    case 'recursive/subagent-start':
+    case 'recursive/subagent-end': {
+      const childId = String(data.childId ?? '')
+      if (childId === '') return state
+      const sub: RecursiveSubagent = card.subagents[childId] ?? {
+        childId,
+        role: String(data.role ?? ''),
+        provider: String(data.provider ?? ''),
+      }
+      sub.role = String(data.role ?? sub.role)
+      sub.provider = String(data.provider ?? sub.provider)
+      if (type === 'recursive/subagent-end') {
+        sub.status = (data.status === 'running' || data.status === 'done' || data.status === 'failed')
+          ? data.status as 'running' | 'done' | 'failed'
+          : 'done'
+      }
+      card.subagents[childId] = sub
+      return state
+    }
+    default:
+      return state
+  }
+}
+
+/** Wire-payload schema (view output) — plain-JSON validation before it leaves the host. */
+const recursivePhaseRowSchema = zod.object({
+  phase: zod.string(),
+  status: zod.string(),
+  lockedAt: zod.string().optional(),
+  lockHash: zod.string().optional(),
+})
+
+const recursiveSubagentSchema = zod.object({
+  childId: zod.string(),
+  role: zod.string(),
+  provider: zod.string(),
+  status: zod.enum(['running', 'done', 'failed']).optional(),
+})
+
+const recursiveRunCardSchema = zod.object({
+  runId: zod.string(),
+  worktreeRoot: zod.string(),
+  repo: zod.string().optional(),
+  template: zod.string().optional(),
+  phases: zod.record(zod.string(), recursivePhaseRowSchema),
+  state: zod.enum(['new', 'active', 'paused', 'blocked', 'complete']),
+  stateReason: zod.string().optional(),
+  gateBlocked: zod.object({ failures: zod.array(zod.string()), kind: zod.string() }).optional(),
+  tampers: zod.record(zod.string(), zod.object({ path: zod.string(), reason: zod.string() })),
+  subagents: zod.record(zod.string(), recursiveSubagentSchema),
+  mergedToRepoRoot: zod.string().optional(),
+})
+
+export const recursiveProjectionSchema: ZodType<RecursiveProjection> = zod.record(
+  zod.string(),
+  zod.record(zod.string(), recursiveRunCardSchema),
+)
+
+/** The registered projection unit (key 'recursive'). */
+export const recursiveProjectionUnit: ProjectionDefinition<'recursive', RecursiveFoldState> = {
+  key: 'recursive',
+  schema: recursiveProjectionSchema,
+  init: () => emptyRecursiveFoldState(),
+  apply: (state, event: SessionEvent) => foldRecursiveProjection(state, event as RecursiveEventLike),
+  view: (state) => state.byWorktree,
+  stateVersion: 1,
+}