@try-works/dsh-recursive-mode 0.1.0

package/src/handoff.ts

@@ -0,0 +1,165 @@
+/**
+ * File-backed delegation handoff docs (Phase B R2, PROPOSAL 10.6): a
+ * main-agent handoff.md plus per-child brief.md / reply.md / scratch.md. The
+ * delegation prompt is reference-based (pointers, not full context), so the
+ * child reads the files it needs rather than receiving a monolithic paste.
+ *
+ * Workspace-scoped (run 03 R1): every path resolves under the given root.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+export interface HandoffInput {
+  root: string
+  runId: string
+  delegationId: string
+  role: string
+  objective: string
+  runDocRefs: string[]
+  codeRefs: string[]
+  auditQuestions: string[]
+  requiredOutput: string
+  decisionBasis: string
+  constraints?: string[]
+}
+
+export interface ChildBriefInput {
+  root: string
+  runId: string
+  delegationId: string
+  childId: string
+  slice: string
+  replyContract?: string
+}
+
+function norm(repoRelative: string): string {
+  return repoRelative.replace(/\\/g, '/').replace(/^\/+/, '')
+}
+
+function resolveUnderRoot(root: string, repoRelative: string): string {
+  const normalized = norm(repoRelative)
+  const rootAbs = resolve(root)
+  const abs = resolve(rootAbs, normalized)
+  const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+  if (abs !== rootAbs && !abs.startsWith(rootPrefix)) {
+    throw new Error('Path escapes the workspace root: ' + repoRelative)
+  }
+  return abs
+}
+
+function subagentsDir(root: string, runId: string): string {
+  return resolveUnderRoot(root, '.recursive/run/' + runId + '/subagents')
+}
+
+function bulletList(title: string, values: string[]): string[] {
+  const lines: string[] = [title]
+  if (!values.length) {
+    lines.push('- none')
+    return lines
+  }
+  for (const v of values) lines.push('- ' + String.fromCharCode(96) + norm(v) + String.fromCharCode(96))
+  return lines
+}
+
+/** Main-agent handoff doc: the full delegation info for one delegation. */
+export function createHandoff(input: HandoffInput): string {
+  const { root, runId, delegationId, role, objective } = input
+  const dir = join(subagentsDir(root, runId), delegationId)
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, 'handoff.md')
+
+  const lines: string[] = [
+    '# Delegation handoff: ' + delegationId,
+    '',
+    'Role: ' + role,
+    'Objective: ' + objective,
+    '',
+    '## Run Document References',
+    ...bulletList('', input.runDocRefs).slice(1),
+    '',
+    '## Code References (with line ranges where applicable)',
+    ...bulletList('', input.codeRefs).slice(1),
+    '',
+    '## Audit Questions',
+    ...(input.auditQuestions.length ? input.auditQuestions.map((q, i) => String(i + 1) + '. ' + q) : ['- none']),
+    '',
+    '## Required Output Shape',
+    '',
+    input.requiredOutput,
+    '',
+    '## Constraints',
+    ...(input.constraints?.length ? input.constraints.map((c) => '- ' + c) : ['- none']),
+    '',
+    '## Delegation Decision Basis',
+    '',
+    input.decisionBasis,
+    '',
+  ]
+
+  writeFileSync(path, lines.join('\n'), 'utf8')
+  return path
+}
+
+/** Per-child brief: the receiving slice for one child. */
+export function createChildBrief(input: ChildBriefInput): string {
+  const { root, runId, delegationId, childId, slice } = input
+  const dir = join(subagentsDir(root, runId), delegationId, 'child-' + childId)
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, 'brief.md')
+  const rootNorm = resolve(root).replace(/\\/g, '/')
+
+  const lines: string[] = [
+    '# Child brief: ' + childId,
+    '',
+    'Delegation: ' + delegationId,
+    'Reply file: ' + replyPath(input).replace(/\\/g, '/').replace(rootNorm + '/', ''),
+    '',
+    '## Your Slice',
+    '',
+    slice,
+    '',
+    '## Reply Contract',
+    '',
+    input.replyContract ?? 'Write your submission to reply.md, then call the report tool citing reply.md.',
+    '',
+  ]
+
+  writeFileSync(path, lines.join('\n'), 'utf8')
+  return path
+}
+
+/** Reply path the child must write its submission to. */
+export function replyPath(input: { root: string; runId: string; delegationId: string; childId: string }): string {
+  const { root, runId, delegationId, childId } = input
+  return join(subagentsDir(root, runId), delegationId, 'child-' + childId, 'reply.md')
+}
+
+/** Child-scoped disposable scratch (Phase B R5, PROPOSAL 10.7). */
+export function childScratchPath(input: { root: string; runId: string; childId: string }): string {
+  const { root, runId, childId } = input
+  return resolveUnderRoot(root, '.recursive/run/' + runId + '/scratch/' + childId + '.md')
+}
+
+/**
+ * Build the reference-based delegation prompt (PROPOSAL 10.6): a pointer to
+ * handoff.md + brief.md, instructions to write reply.md and call report citing
+ * it. Short, not a monolithic paste.
+ */
+export function buildDelegationPrompt(input: { root: string; runId: string; delegationId: string; childId: string; handoffPath: string; briefPath: string }): string {
+  const { root, runId, delegationId, childId, handoffPath, briefPath } = input
+  const rootNorm = resolve(root).replace(/\\/g, '/')
+  const handoffRel = norm(handoffPath).replace(rootNorm + '/', '')
+  const briefRel = norm(briefPath).replace(rootNorm + '/', '')
+  const replyRel = norm(replyPath(input)).replace(rootNorm + '/', '')
+  return [
+    'You are a delegated worker for recursive-mode delegation ' + delegationId + ' (child ' + childId + ').',
+    '',
+    '1. Read the full delegation handoff: ' + handoffRel,
+    '2. Read your receiving slice: ' + briefRel,
+    '3. Do the work described in your slice, reading the referenced run docs and code files as needed.',
+    '4. Write your complete submission to: ' + replyRel,
+    '5. Call the report tool citing ' + replyRel + ' and include your verdict, findings, and every reference you used.',
+    '',
+    'Do not modify files outside your child scratch and reply.md unless the handoff explicitly authorizes it.',
+  ].join('\n')
+}

package/src/index.ts

@@ -0,0 +1,283 @@
+import { type Context } from '@deepseek-ai/cordis'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { RecursiveRuntime } from './runtime.ts'
+import { createRecursiveStatusTool } from './recursive_status.tool.ts'
+import { createRecursiveInitTool } from './recursive_init.tool.ts'
+import { createRecursiveLockTool } from './recursive_lock.tool.ts'
+import { createRecursiveLintTool } from './recursive_lint.tool.ts'
+import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
+import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+import { registerRecursiveCommand } from './commands.ts'
+import { stageBWorkflowInit } from './bootstrap.ts'
+import { evaluatePreStepGate, evaluateToolGuard, detectTamper, resolveEnforcementConfig, DEFAULT_ENFORCEMENT, type EnforcementConfig } from './enforcement.ts'
+import { detectTransitionIntent } from './lifecycle.ts'
+import { renderRecursivePolicy } from './policy.ts'
+import {
+  gateBlocked as gateBlockedEvent,
+  tamper as tamperEvent,
+  phaseIntent as phaseIntentEvent,
+  runCreated as runCreatedEvent,
+  phase as phaseEvent,
+  phaseLocked as phaseLockedEvent,
+  runState as runStateEvent,
+  runMerged as runMergedEvent,
+  subagentStart as subagentStartEvent,
+  subagentEnd as subagentEndEvent,
+} from './events.ts'
+import { recursiveProjectionUnit } from './projection.ts'
+
+export const name = '@try-works/dsh-recursive-mode'
+
+export { RecursiveRuntime } from './runtime.ts'
+export { createRecursiveStatusTool } from './recursive_status.tool.ts'
+export { createRecursiveInitTool } from './recursive_init.tool.ts'
+export { createRecursiveLockTool } from './recursive_lock.tool.ts'
+export { createRecursiveLintTool } from './recursive_lint.tool.ts'
+export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
+export { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+export * from './status.ts'
+export {
+  PHASE_SEQUENCE,
+  OPTIONAL_PHASES,
+  normalizeForLockHash,
+  lockHashFromContent,
+  phaseIndex,
+  isCoreArtifact,
+  getPrerequisites,
+  getLockStatus,
+  getPrerequisiteBlockers,
+  receiptPath,
+  readReceipt,
+  writeReceipt,
+  invalidateReceipt,
+  getStaleDownstreamPhases,
+  getNextLegalPhase,
+  getAllStaleReceipts,
+  validateChain,
+} from './lock.ts'
+export type {
+  LockReceipt,
+  LockStatus,
+  PrerequisiteBlocker,
+  StaleDownstream,
+  ChainPhaseResult,
+  LockChainResult,
+} from './lock.ts'
+export * from './run.ts'
+export * from './review.ts'
+export * from './handoff.ts'
+export * from './router.ts'
+export * from './delegation.ts'
+export * from './lifecycle.ts'
+export * from './enforcement.ts'
+export * from './policy.ts'
+export * from './events.ts'
+export * from './projection.ts'
+
+/**
+ * Bundle plugin entry. The Loader activates this row once `tools` is available
+ * (`inject` below); the RecursiveRuntime service is constructed directly so it
+ * is provided on `ctx.recursive` for the lifetime of this fiber, and the
+ * read-path tools (status/init/lock/lint) are registered through it (R2/R4).
+ */
+export const inject = ['tools']
+
+/**
+ * Two-stage init (PROPOSAL §5.10):
+ *  - Stage A (mount-time, this apply): register the isolated ctx.recursive
+ *    service + the recursive_* tools + the /recursive command + the
+ *    recursive:policy prompt section. No repo/run work here.
+ *  - Stage B (agent/session-start): resolve the session's workspace root (R1),
+ *    bootstrap the scaffold if missing, enumerate runs as dir names only, and
+ *    inject a workspace-scoped notice. See stageBWorkflowInit + the
+ *    agent/session-start listener below.
+ */
+export function apply(ctx: Context) {
+  ctx.effect(function* () {
+    // Workspace registry: optional host service (durable). Access via ctx.get —
+    // property access requires inject and would fail boot when undeclared.
+    // Resolve the control-plane root strictly from the session agent's cwd.
+    const workspaceRegistry = ctx.get('workspaceRegistry') as never
+    const recursive = new RecursiveRuntime(ctx, { repoRoot: process.cwd(), workspaceRegistry })
+
+    /** Typed agent payload shape (session is a full Session). */
+    type AgentLike = { session?: Session | null }
+
+    /** Extract the session from a listener payload. */
+    const sessionOf = (p: unknown): Session | null => {
+      const a = (p as { agent?: AgentLike | null } | null)?.agent
+      return a?.session ?? null
+    }
+
+    /** Resolve the session's control-plane root (registry first, cwd fallback). */
+    const rootOf = async (p: unknown): Promise<string> => {
+      const a = (p as { agent?: AgentLike | null } | null)?.agent
+      const root = await recursive.resolveRootFor(a as { session?: { header?: { cwd?: string } } } | null)
+      return root ?? a?.session?.header.cwd ?? process.cwd()
+    }
+
+    /** Emit one recursive/* event into the session log (log-only). */
+    const emit = (session: Session | null, type: string, data: unknown) => {
+      if (!session) return
+      try { (session.append as unknown as (t: string, d: unknown) => void)(type, data) } catch { /* log-only; never fail the gate on an emit error */ }
+    }
+    const disposers = [
+      ctx.tools.register(createRecursiveStatusTool(recursive)),
+      ctx.tools.register(createRecursiveInitTool(recursive)),
+      ctx.tools.register(createRecursiveLockTool(recursive)),
+      ctx.tools.register(createRecursiveLintTool(recursive)),
+      ctx.tools.register(createRecursiveCloseoutTool(recursive)),
+      ctx.tools.register(createRecursiveScratchTool(recursive)),
+    ]
+
+    // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.
+    const commands = ctx.get('commands') as { register: (def: unknown) => () => void } | undefined
+    if (commands) {
+      disposers.push(registerRecursiveCommand({ commands } as never, recursive))
+    }
+
+    // recursive:policy prompt section (Phase C R5): workspace-scoped behavior +
+    // current-phase contract rendered from folded state + enforcement config.
+    const systemPrompt = ctx.get('systemPrompt') as { section: (def: unknown) => () => void } | undefined
+    if (systemPrompt) {
+      disposers.push(systemPrompt.section({
+        name: 'recursive:policy',
+        order: 55,
+        text: (context: unknown) => {
+          const agent = (context as { agent?: { session?: { header?: { cwd?: string }; events?: { type: string; data?: Record<string, unknown> }[] } } } | undefined)?.agent
+          if (!agent) return ''
+          const cwd = agent.session?.header?.cwd ?? ''
+          if (!cwd) return ''
+          const events = agent.session?.events ?? []
+          const intent = detectTransitionIntent(events as never)
+          if (!intent || intent.worktreeRoot === '') return ''
+          return renderRecursivePolicy({ worktreeRoot: intent.worktreeRoot, runId: intent.runId, folded: recursive.foldPhase(events as never), config: recursive.enforcementConfig })
+        },
+      }))
+    }
+
+    // Phase C R3: agent/pre-step phase-transition gate (Layer 1, caller of the
+    // lifecycle transition set). Reads on transition intent only; rejects (strict)
+    // or warns (advisory) when the target gates fail.
+    const agentEvents = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
+    if (agentEvents.on) {
+      disposers.push(agentEvents.on('agent/pre-step', (payload, next) => {
+        const p = payload as { agent?: { session?: { events?: { type: string; data?: Record<string, unknown> }[] } } } | null
+        const events = p?.agent?.session?.events ?? []
+        const session = sessionOf(p)
+        const intent = recursive.detectTransitionIntent(events as never)
+        const decision = evaluatePreStepGate(events as never, recursive.enforcementConfig.preStep)
+        void (async () => {
+          // Emit a committed run-state (blocked) when a gate rejects the intent —
+          // the board then shows the run blocked, not merely a log message.
+          if (decision.gateBlocked && intent?.runId) {
+            const worktreeRoot = intent?.worktreeRoot ?? (await rootOf(p))
+            emit(session, 'recursive/gate-blocked', gateBlockedEvent({ runId: intent.runId, worktreeRoot, phase: intent?.targetArtifact ?? '', failures: decision.failures, kind: 'pre-step' }))
+            emit(session, 'recursive/run-state', runStateEvent({ runId: intent.runId, worktreeRoot, state: 'blocked', reason: 'gate-blocked: ' + decision.failures.join('; ') }))
+          }
+        })()
+        if (decision.kind === 'reject') return { kind: 'reject' }
+        return typeof next === 'function' ? next() : { kind: 'enter', messages: [] }
+      }))
+    }
+
+    // Phase C R4: tools/pre-execute surgical guards (Layer 2, caller of the
+    // transition set). Scope-filtered to the active run's worktree.
+    const toolRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
+    if (toolRuntime.on) {
+      disposers.push(toolRuntime.on('tools/pre-execute', (payload, next) => {
+        const exec = payload as { name?: string; arguments?: unknown; agent?: { session?: { header?: { cwd?: string } } } | null } | null
+        if (!exec?.name) return typeof next === 'function' ? next() : { kind: 'allow' }
+        // B3: per-call root is the session cwd (authoritative when the registry is
+        // absent), never process.cwd().
+        const root = exec?.agent?.session?.header?.cwd ?? ''
+        const decision = evaluateToolGuard(exec as never, root, '', recursive.enforcementConfig.toolGuards)
+        if (decision.kind === 'allow') return typeof next === 'function' ? next() : { kind: 'allow' }
+        if (decision.kind === 'deny') return decision
+        // ask -> in advisory we let it through with a warn (the approval seam is Phase D)
+        return typeof next === 'function' ? next() : { kind: 'allow' }
+      }))
+    }
+
+    // Phase C R8 + Phase D R1: fs/observed lock-tamper warnings -> recursive/tamper event.
+    const fsRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown) => void) => () => void }
+    if (fsRuntime.on) {
+      disposers.push(fsRuntime.on('fs/observed', (payload) => {
+        const p = payload as { target?: { displayPath?: string }; agent?: AgentLike | null } | null
+        const path = p?.target?.displayPath ?? ''
+        if (!path) return
+        // B3: tamper detection is scoped to the SESSION's control-plane root,
+        // not the host checkout.
+        const sessionCwd = p?.agent?.session?.header.cwd ?? ''
+        const tamper = detectTamper(path, sessionCwd, '')
+        if (!tamper) return
+        // Resolve the worktree root from the tampered path (strip /.recursive/run/<id>/).
+        const normalized = path.replace(/\\/g, '/')
+        const marker = '/.recursive/run/'
+        const idx = normalized.indexOf(marker)
+        const worktreeRoot = idx >= 0 ? normalized.slice(0, idx) : sessionCwd
+        // Prefer the observing session's own log (additive); fall back to the
+        // session store list only when the payload carries no session.
+        const session = sessionOf(p) ?? null
+        if (session) {
+          emit(session, 'recursive/tamper', tamperEvent({ runId: tamper.runId, worktreeRoot, path: tamper.path, reason: tamper.reason }))
+          return
+        }
+        const sessions = ctx.get('sessions') as { list?: () => Session[] } | undefined
+        const match = sessions?.list?.().find((s) => {
+          const cwd = (s.header?.cwd ?? '').replace(/\\/g, '/')
+          return cwd === '' || cwd === worktreeRoot || cwd.startsWith(worktreeRoot + '/')
+        })
+        if (match) emit(match, 'recursive/tamper', tamperEvent({ runId: tamper.runId, worktreeRoot, path: tamper.path, reason: tamper.reason }))
+      }))
+    }
+
+    // Phase D R2: register the recursive projection unit (activates only when a
+    // projection registry is composed — headless assemblies stay unaffected).
+    // The unit's cell is per-session: a session's own log is its workspace, so
+    // an accept-all init is scoped by the session boundary (see projection.ts
+    // emptyRecursiveFoldState). The registry (if present) is cached here so the
+    // session-start boundary can re-read run state after the projection drove.
+    let sessionProjections: { snapshot?: (session: Session) => { values: Partial<Record<string, unknown>> } } | null = null
+    ctx.inject(['sessionProjections'], (projectionCtx) => {
+      const registry = (projectionCtx as { sessionProjections?: { register: (def: unknown) => () => void; snapshot?: (session: Session) => unknown } }).sessionProjections
+      if (registry?.register) {
+        disposers.push(registry.register(recursiveProjectionUnit))
+        sessionProjections = registry as { snapshot?: (session: Session) => { values: Partial<Record<string, unknown>> } }
+      }
+    })
+
+    // Stage B (R6): agent/session-start workflow init, workspace-scoped.
+    // NEW sessions emit recursive/run-state('active') after init; resumed
+    // sessions replay the projection (already folded from the persisted log) —
+    // no duplicate run-created. run-created is emitted by the lifecycle at the
+    // init/lock boundary (the only place a run's files first exist).
+    const events = ctx as unknown as { on?: (event: string, listener: (payload: unknown) => void) => () => void }
+    if (events.on) {
+      disposers.push(events.on('agent/session-start', (payload) => {
+        const p = payload as { agent?: AgentLike | null; source?: 'new' | 'resume' }
+        const session = sessionOf(p)
+        const cwd = p?.agent?.session?.header?.cwd
+        if (!cwd) return
+        void (async () => {
+          const root = await recursive.resolveRootFor(p?.agent as { session?: { header?: { cwd?: string } } } | null)
+          if (!root) return
+          const result = stageBWorkflowInit({ root, source: p.source === 'resume' ? 'resume' : 'new' })
+          // Emit run-state for the active run (from the projected wire value, the
+          // one same-source view) when the projection registry is present.
+          if (session) {
+            const runId = result.activeRunId ?? result.runs[result.runs.length - 1] ?? ''
+            if (runId) {
+              const snap = sessionProjections?.snapshot?.(session)
+              const proj = (snap?.values as { recursive?: Record<string, Record<string, { state?: string }>> } | undefined)?.recursive
+              const state = proj?.[root]?.[runId]?.state ?? 'active'
+              emit(session, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: state as 'new' | 'active' | 'paused' | 'blocked' | 'complete' }))
+            }
+          }
+        })()
+      }))
+    }
+
+    yield () => { for (const d of disposers) d() }
+  })
+}

package/src/lifecycle.ts

@@ -0,0 +1,235 @@
+/**
+ * Run state machine + serialized transition driver + recursive/* events
+ * (Phase C R1/R2/R6, PROPOSAL 8.8).
+ *
+ * Authority is TRANSITIONS AND EVENTS ONLY - this module never stores run
+ * state in a second place. It reconciles the file tree via the existing
+ * read path (run.ts/status.ts/lock.ts), validates the target phase's gates
+ * (PROPOSAL 8.4), delegates the artifact write to lock.ts (canonical
+ * lock-hash + monotonic chain preserved), and emits the recursive/* events.
+ * State is DERIVED on every transition; resume/fork/session-restart
+ * reconstruct identical state by re-reading files + folding the session log.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getPrerequisiteBlockers, getLockStatus } from './lock.ts'
+import { getMdFieldValue, getGateStatus } from './status.ts'
+
+/** Run-level durable states (PROPOSAL 8.8). */
+export const RUN_STATES = ['new', 'active', 'paused', 'blocked', 'complete'] as const
+export type RunState = (typeof RUN_STATES)[number]
+
+/** A proposed phase transition the gates validate before any file write. */
+export interface PhaseTransitionIntent {
+  runId: string
+  worktreeRoot: string
+  targetArtifact: string
+  kind: 'lock' | 'reopen' | 'advance'
+  evidence?: {
+    tddMode?: string
+    redEvidencePath?: string
+    greenEvidencePath?: string
+    qaMode?: string
+    qaSignOff?: boolean
+  }
+}
+
+/** Folded phase state (last-wins over recursive/phase + recursive/run-state). */
+export interface RecursivePhaseState {
+  runId: string
+  phase: string
+  status: string
+  runState: RunState
+}
+
+/** A session-event-like carrier (the pure fold reads events by shape). */
+export interface SessionEventLike {
+  type: string
+  data?: Record<string, unknown>
+}
+
+/** Gate check result - the transition set's single output. */
+export interface GateCheckResult {
+  passed: boolean
+  failures: string[]
+}
+
+/**
+ * Payload shapes for the recursive/* events. These are LEGACY structural
+ * views kept for internal consumers; the single source of truth for the
+ * emitted payloads is events.ts (every event carries { runId, worktreeRoot }).
+ * Aligned here so no local interface drifts out of the worktree-keyed
+ * invariant (B7).
+ */
+export interface RecursivePhaseEvent { runId: string; worktreeRoot: string; phase: string; status: string }
+export interface RecursiveRunStateEvent { runId: string; worktreeRoot: string; state: RunState; reason?: string }
+export interface RecursiveGateBlockedEvent { runId: string; worktreeRoot: string; phase: string; failures: string[]; kind: string }
+export interface RecursiveTamperEvent { runId: string; worktreeRoot: string; path: string; reason: string }
+export interface RecursiveTransitionFailedEvent { runId: string; worktreeRoot: string; phase: string; error: string }
+
+/** The audited phase files whose lock requires Audit: PASS (parity with status.ts). */
+const AUDITED_PHASE_FILES = 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', '06-decisions-update.md', '07-state-update.md', '08-memory-impact.md',
+])
+
+/**
+ * Pure last-wins fold over the recursive/* events (the foldPlanMode pattern).
+ * A log with no recursive/phase folds to null; the last recursive/run-state
+ * wins for the run-level flag.
+ */
+export function foldRecursivePhase(events: readonly SessionEventLike[], end = events.length): RecursivePhaseState | null {
+  let runId = ''
+  let phaseName = ''
+  let status = ''
+  let runState: RunState = 'active'
+  let seen = false
+  let index = 0
+  for (const event of events) {
+    if (index >= end) break
+    index++
+    if (event.type === 'recursive/phase') {
+      const d = event.data ?? {}
+      runId = String(d.runId ?? runId)
+      phaseName = String(d.phase ?? phaseName)
+      status = String(d.status ?? status)
+      seen = true
+    } else if (event.type === 'recursive/run-state') {
+      const d = event.data ?? {}
+      runId = String(d.runId ?? runId)
+      runState = asRunState(d.state)
+      seen = true
+    }
+  }
+  return seen ? { runId, phase: phaseName, status, runState } : null
+}
+
+function asRunState(value: unknown): RunState {
+  return RUN_STATES.includes(value as RunState) ? (value as RunState) : 'active'
+}
+
+/** Whether the session log holds an opened turn without its closing turn/end. */
+export function hasOpenTurn(events: readonly SessionEventLike[]): boolean {
+  let open = false
+  for (const event of events) {
+    if (event.type === 'turn/start') open = true
+    else if (event.type === 'turn/end') open = false
+  }
+  return open
+}
+
+/** Detect a pending transition intent from the session log (the lock tool logs it). */
+export function detectTransitionIntent(events: readonly SessionEventLike[]): PhaseTransitionIntent | null {
+  let intent: PhaseTransitionIntent | null = null
+  for (const event of events) {
+    if (event.type === 'recursive/phase-intent') {
+      const d = event.data ?? {}
+      intent = {
+        runId: String(d.runId ?? ''),
+        worktreeRoot: String(d.worktreeRoot ?? ''),
+        targetArtifact: String(d.targetArtifact ?? ''),
+        kind: (d.kind === 'reopen' || d.kind === 'advance' ? d.kind : 'lock'),
+        evidence: d.evidence as PhaseTransitionIntent['evidence'],
+      }
+    }
+  }
+  return intent
+}
+
+/**
+ * Validate a proposed transition against the target phase's gates (PROPOSAL 8.4).
+ * Pure: reads the current file tree + lock.ts chain; writes nothing.
+ */
+export function validateTransition(intent: PhaseTransitionIntent): GateCheckResult {
+  const failures: string[] = []
+  const runDir = join(intent.worktreeRoot, '.recursive', 'run', intent.runId)
+  const artifactPath = join(runDir, intent.targetArtifact)
+
+  if (intent.kind === 'reopen') {
+    const status = getLockStatus(artifactPath)
+    if (status !== 'LOCKED') failures.push('reopen requires a LOCKED artifact (current: ' + status + ')')
+    return { passed: failures.length === 0, failures }
+  }
+
+  // 1. Phase doc exists.
+  if (!existsSync(artifactPath)) {
+    failures.push('phase doc does not exist: ' + intent.targetArtifact)
+    return { passed: false, failures }
+  }
+
+  const content = readFileSync(artifactPath, 'utf8')
+
+  // 2. Monotonic gating (parity with recursive-lock.py).
+  const blockers = getPrerequisiteBlockers(runDir, intent.targetArtifact)
+  for (const b of blockers) failures.push('unlocked prerequisite: ' + b.artifact + ' (' + b.status + ')')
+
+  // 3. TDD evidence (Phase 3).
+  if (intent.targetArtifact === '03-implementation-summary.md') {
+    const tddMode = getMdFieldValue(content, 'TDD Mode') ?? intent.evidence?.tddMode ?? ''
+    if (tddMode === 'strict') {
+      const red = intent.evidence?.redEvidencePath ?? ''
+      const green = intent.evidence?.greenEvidencePath ?? ''
+      if (!red || !existsSync(join(runDir, red))) failures.push('TDD Mode: strict requires a RED evidence path')
+      if (!green || !existsSync(join(runDir, green))) failures.push('TDD Mode: strict requires a GREEN evidence path')
+    } else if (tddMode === 'pragmatic') {
+      if (!/rationale/i.test(content)) failures.push('TDD Mode: pragmatic requires an exception rationale')
+    } else {
+      failures.push('TDD Mode must be declared strict|pragmatic')
+    }
+  }
+
+  // 4. Audit closed (audited phases).
+  if (AUDITED_PHASE_FILES.has(intent.targetArtifact)) {
+    if (getGateStatus(content, 'Audit') !== 'PASS') failures.push('audited phase must end with Audit: PASS')
+    if (!/Requirement Completion Status/.test(content)) failures.push('audited phase requires a Requirement Completion Status section')
+    if (!/Delegation Decision Basis|Delegation Override Reason|Subagent Capability Probe/.test(content)) {
+      failures.push('audited phase requires Delegation Decision Basis / Subagent Capability Probe')
+    }
+  }
+
+  // 5. QA sign-off (Phase 5).
+  if (intent.targetArtifact === '05-manual-qa.md') {
+    const qaMode = getMdFieldValue(content, 'QA Execution Mode') ?? intent.evidence?.qaMode ?? ''
+    if (!qaMode) failures.push('QA Execution Mode must be declared human|agent-operated|hybrid')
+    else if ((qaMode === 'human' || qaMode === 'hybrid') && intent.evidence?.qaSignOff !== true) {
+      failures.push('QA Execution Mode ' + qaMode + ' requires user sign-off')
+    }
+  }
+
+  // 6. Effective inputs re-read.
+  if (!/Effective Inputs Re-read/.test(content)) failures.push('phase doc must re-read effective inputs (## Effective Inputs Re-read)')
+
+  return { passed: failures.length === 0, failures }
+}
+
+/**
+ * A serialized per-run transition driver (coalesced - the single-reservation
+ * pattern). Two concurrent 'lock Phase 3' intents queue; the second observes
+ * the first's committed state instead of racing the write.
+ */
+export class LifecycleDriver {
+  private readonly drivers = new Map<string, Promise<void>>()
+
+  /** Run one transition serially per runId. */
+  serialize(runId: string, run: () => Promise<void>): Promise<void> {
+    const previous = this.drivers.get(runId) ?? Promise.resolve()
+    const next = previous.then(run, run)
+    this.drivers.set(runId, next.then(() => undefined, () => undefined))
+    return next
+  }
+}
+
+/**
+ * Couple a gate-block to the goal service (PROPOSAL 8.4 goal integration).
+ * Graceful no-op when the goal service or agent is unavailable.
+ */
+export function coupleGateBlockToGoal(
+  goalService: { block?: (agent: unknown, ref: unknown, reason: unknown) => unknown } | null | undefined,
+  agent: unknown,
+  ref: unknown,
+  reason: { code: string; message: string },
+): boolean {
+  if (!goalService || typeof goalService.block !== 'function' || !agent) return false
+  goalService.block(agent, ref, reason)
+  return true
+}