@try-works/dsh-recursive-mode 0.1.3 → 0.1.5

package/src/runtime.ts

@@ -1,6 +1,9 @@
 import { Service, type Context } from '@deepseek-ai/cordis'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
 import { join } from 'node:path'
+import { referencesRoot } from './bootstrap.ts'
+import { requirementsContent, worktreeContent, laterPhaseContent, detectGitContext, RUN_SCAFFOLD_DIRS, type GitContext } from './init-templates.ts'
 import { foldRun, resolveRunDir } from './status.ts'
 import {
   getLockStatus,
@@ -22,9 +25,8 @@ import { delegate, validateReferences, writeActionRecord, evaluateDelegationResu
 import { foldRecursivePhase, validateTransition, detectTransitionIntent, LifecycleDriver, coupleGateBlockToGoal, type PhaseTransitionIntent, type SessionEventLike, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts'
 import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluatePreStepGate, evaluateToolGuard, detectTamper, type EnforcementConfig, type PreStepGateDecision, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts'
 import type { Session } from '@deepseek-ai/dsh-session'
-import { runCreated as runCreatedEvent, phase as phaseEvent, phaseLocked as phaseLockedEvent, runState as runStateEvent } from './events.ts'
 import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
-import { foldRecursiveProjection as foldProjectionEvent, emptyRecursiveFoldState, recursiveProjectionUnit, isInsideWorkspace, type RecursiveEventLike, type RecursiveFoldState } from './projection.ts'
+import { snapshotWorkspace } from './snapshot.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -303,23 +305,28 @@ export class RecursiveRuntime extends Service {
   }
 
   /**
-   * Emit a recursive/* event into the session whose control-plane root matches
-   * `root` (additive log-only; the projection drives from these). Falls back to
-   * the agent's session when passed, else the session store list.
+   * SP2 R1 route adapter: resolve the control-plane root for the live route.
+   * sessionId PRIMARY — the host looks up the attached session header cwd and
+   * resolves the root from THAT; the client-passed cwd is a fallback hint only
+   * (hydration / headless callers). Two sessions in one workspace collapse to
+   * one root; a subdir cwd resolves up to the workspace root.
    */
-  private emitToSession(root: string, type: string, data: unknown, agent?: { session?: { header?: { cwd?: string } } | null } | null) {
-    const sessions = this.ctx.get('sessions') as { list?: () => Session[] } | undefined
-    const candidates: Session[] = []
-    if (agent?.session) candidates.push(agent.session as unknown as Session)
-    const listed = sessions?.list?.() ?? []
-    for (const s of listed) candidates.push(s)
-    const norm = (x: string) => x.split(String.fromCharCode(92)).join("/")
-    const target = candidates.find((s) => {
-      const cwd = norm(s.header?.cwd ?? "")
-      return cwd === "" || cwd === norm(root) || cwd.startsWith(norm(root) + "/")
-    })
-    if (!target) return
-    try { (target.append as unknown as (t: string, d: unknown) => void)(type, data) } catch { /* log-only */ }
+  async resolveRootForRoute(sessionId: string | undefined, cwd: string, sessionsStore?: { get?: (id: string) => { header?: { cwd?: string } } | undefined } | null): Promise<string | null> {
+    // 1) Attached session header (authoritative when present).
+    if (sessionId && sessionsStore?.get) {
+      const attached = sessionsStore.get(sessionId)
+      const headerCwd = attached?.header?.cwd
+      if (headerCwd) {
+        const root = await resolveControlPlaneRoot({ session: { header: { cwd: headerCwd } } }, this.workspaceRegistry, this.repoRoot)
+        if (root) return root
+      }
+    }
+    // 2) Client cwd fallback (hydration / headless) — still registry-canonicalized.
+    if (cwd) {
+      const root = await resolveControlPlaneRoot({ session: { header: { cwd } } }, this.workspaceRegistry, this.repoRoot)
+      if (root) return root
+    }
+    return null
   }
 
   async status(runId?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<RecursiveStatusResult | null> {
@@ -331,8 +338,12 @@ export class RecursiveRuntime extends Service {
   }
 
   /**
-   * Scaffold a run directory with stub artifact headers (no-op if exists).
-   * Returns the run dir + created artifacts.
+   * Scaffold a run directory with FULL per-phase templates (no-op if exists).
+   * 00-requirements.md + 00-worktree.md are byte-identical to canonical
+   * recursive-init.py (incl. git-context prefill); later phases carry every
+   * required section (get_artifact_required_sections) + TODO + FAIL gates.
+   * Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
+   * run dir + created artifacts.
    */
   async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<{ runDir: string; runId: string; created: string[]; existing: string[] }> {
     const root = await this.resolveRootFor(agent)
@@ -341,23 +352,50 @@ export class RecursiveRuntime extends Service {
     mkdirSync(runDir, { recursive: true })
     const created: string[] = []
     const existing: string[] = []
-    for (const [file, fields] of Object.entries(ARTIFACT_STUB)) {
+
+    // Scaffold dirs (canonical recursive-init sequence).
+    for (const dir of RUN_SCAFFOLD_DIRS) {
+      const p = join(runDir, dir)
+      if (existsSync(p)) { existing.push(dir + '/'); continue }
+      mkdirSync(p, { recursive: true })
+      created.push(dir + '/')
+    }
+
+    // Git context for the Phase 0 diff-basis prefill (canonical parity).
+    const { context: gitContext, error: prefillError } = detectGitContext(root)
+
+    // Phase 0 templates: byte-identical to canonical recursive-init.py.
+    const phase0: Array<[string, string]> = [
+      ['00-requirements.md', requirementsContent(runId, 'feature', '')],
+      ['00-worktree.md', worktreeContent(runId, root, gitContext, prefillError)],
+    ]
+    for (const [file, content] of phase0) {
       const path = join(runDir, file)
-      if (existsSync(path)) {
-        existing.push(file)
-        continue
-      }
-      const header = fields.map((f, i) => (i === 0 ? f + runId : f)).join('\n')
-      writeFileSync(path, '# ' + file.replace(/\.md$/, '') + ' — ' + file + '\n\n' + header + '\n', 'utf8')
+      if (existsSync(path)) { existing.push(file); continue }
+      writeFileSync(path, content, 'utf8')
       created.push(file)
     }
-    // B2: a run's files first exist here — the run-created event feeds the
-    // projection's worktree-grouped card. Emit only when the scaffold is fresh
-    // (created.length > 0) so resume/ensure does not double-log.
-    if (created.length > 0) {
-      this.emitToSession(root, 'recursive/run-created', runCreatedEvent({ runId, worktreeRoot: root }), agent)
-      this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'new' }), agent)
+
+    // Later phases: full required-sections scaffold.
+    const laterPhases = [
+      '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',
+    ]
+    for (const file of laterPhases) {
+      const path = join(runDir, file)
+      if (existsSync(path)) { existing.push(file); continue }
+      writeFileSync(path, laterPhaseContent(runId, file), 'utf8')
+      created.push(file)
     }
+
     return { runDir, runId, created, existing }
   }
 
@@ -376,9 +414,8 @@ export class RecursiveRuntime extends Service {
     if (!existsSync(artifactPath)) throw new Error('Artifact not found: ' + artifact)
     const status = getLockStatus(artifactPath)
     if (status === 'LOCKED') throw new Error('Artifact already LOCKED: ' + artifact)
-    // B2: log the phase-intent BEFORE validation so the pre-step gate reads it
-    // (the caller of the transition set). Never a projection event.
-    this.emitToSession(root, 'recursive/phase-intent', { runId, worktreeRoot: root, targetArtifact: artifact, kind: 'lock' }, agent)
+    // B2: the pre-step gate reads transition intent from the session log; the
+    // durable commit below is what the live fs route folds. No phase-intent event.
     const blockers = getPrerequisiteBlockers(runDir, artifact)
     if (blockers.length > 0) {
       throw new Error('Prerequisite blockers: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', '))
@@ -392,11 +429,7 @@ export class RecursiveRuntime extends Service {
     content = setOrInsertField(content, 'LockHash', lockHash, ['LockedAt', 'Status'])
     writeFileSync(artifactPath, content, 'utf8')
     const receipt = writeReceipt(runDir, artifact, artifactPath)
-    // B2: the commit is durable — emit phase + phase-locked (the projection's
-    // last-wins phase chain + lock badge + truncated hash).
-    this.emitToSession(root, 'recursive/phase', phaseEvent({ runId, worktreeRoot: root, phase: artifact, status: 'LOCKED' }), agent)
-    this.emitToSession(root, 'recursive/phase-locked', phaseLockedEvent({ runId, worktreeRoot: root, phase: artifact, lockedAt, lockHash }), agent)
-    this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'active' }), agent)
+    // B2: the commit is durable — the live fs route folds it on the next GET.
     return {
       artifact,
       runId,
@@ -419,11 +452,7 @@ export class RecursiveRuntime extends Service {
     const hadReceipt = invalidateReceipt(runDir, artifact)
     const stale = getStaleDownstreamPhases(runDir, artifact)
     for (const entry of stale) invalidateReceipt(runDir, entry.artifact)
-    // B2: reopen reverts to DRAFT — log phase-intent + emit the transition so
-    // the pre-step gate and projection both see the reverted state.
-    this.emitToSession(root, 'recursive/phase-intent', { runId, worktreeRoot: root, targetArtifact: artifact, kind: 'reopen' }, agent)
-    this.emitToSession(root, 'recursive/phase', phaseEvent({ runId, worktreeRoot: root, phase: artifact, status: 'DRAFT' }), agent)
-    this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'active', reason: 'reopened ' + artifact }), agent)
+    // B2: reopen reverts to DRAFT — the live fs route folds the reverted state.
     return {
       artifact,
       runId,
@@ -435,8 +464,12 @@ export class RecursiveRuntime extends Service {
   }
 
   /**
-   * Lint an artifact for phase-specific issues. Minimal structural checks:
-   * gates present, TODO section, Status field, LockHash consistency.
+   * Lint an artifact with FULL canonical parity: shells out to the vendored
+   * lint-recursive-run.py (byte-identical to canonical) and parses its
+   * [FAIL]/[WARN] lines + Summary counts. `errors` = FAIL lines, `warnings` =
+   * WARN lines, `passed` = no FAIL (WARN-only passes, matching the canonical
+   * non-strict verdict). Falls back to the structural check only if the vendored
+   * script is unavailable (e.g. bundled lib without references/).
    */
   async lintArtifact(runId: string, artifact?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<LintArtifactResult> {
     const root = await this.resolveRootFor(agent)
@@ -447,6 +480,24 @@ export class RecursiveRuntime extends Service {
     if (!existsSync(artifactPath)) {
       return { artifact: target, runId, errors: ['Artifact not found'], warnings: [], passed: false }
     }
+    const lintScript = join(referencesRoot(), 'scripts', 'lint-recursive-run.py')
+    if (existsSync(lintScript)) {
+      try {
+        const stdout = execFileSync('python', [lintScript, '--repo-root', root, '--run-id', runId], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 60000,
+        })
+        return parseLintOutput(stdout, target, runId)
+      } catch (err) {
+        const stdout = (err as { stdout?: string })?.stdout ?? ''
+        if (stdout.includes('Summary')) {
+          return parseLintOutput(stdout, target, runId)
+        }
+        // script failed to run entirely — fall through to structural check
+      }
+    }
+    // Structural fallback (no vendored script available).
     const content = readFileSync(artifactPath, 'utf8')
     const errors: string[] = []
     const warnings: string[] = []
@@ -456,10 +507,7 @@ export class RecursiveRuntime extends Service {
     else if (status === 'STALE_LOCK') errors.push('LockHash mismatch or missing lock fields')
     if (!/^[ \t]*## TODO[ \t]*$/m.test(content)) errors.push('Missing ## TODO section')
     for (const gate of ['Coverage', 'Approval']) {
-      if (!new RegExp('^[ \\t]*' + gate + ':\\s*(PASS|FAIL)\\s*$', 'm').test(content)) warnings.push('Missing ' + gate + ' gate')
-    }
-    if (target === '03-implementation-summary.md' && !new RegExp('^[ \\t]*TDD Compliance:\\s*(PASS|FAIL)\\s*$', 'm').test(content)) {
-      warnings.push('Missing TDD Compliance gate')
+      if (!new RegExp('^[ \t]*' + gate + ':\s*(PASS|FAIL)\s*$', 'm').test(content)) warnings.push('Missing ' + gate + ' gate')
     }
     return { artifact: target, runId, errors, warnings, passed: errors.length === 0 }
   }
@@ -504,31 +552,6 @@ export class RecursiveRuntime extends Service {
     return coupleGateBlockToGoal(goalService as never, agent, ref, reason)
   }
 
-  /** Phase D R1: append a recursive/* event through the host session adapter (worktree-keyed). */
-  emitRecursiveEvent(session: unknown, type: string, data: Record<string, unknown>): void {
-    const s = session as { append?: (type: string, data: unknown) => void } | null | undefined
-    if (s && typeof s.append === 'function') {
-      s.append(type, data)
-    }
-  }
-
-  /** Phase D R2/R9: fold a session log into the worktree-grouped projection. */
-  foldRecursiveProjection(events: readonly RecursiveEventLike[], workspaceRoot = ''): RecursiveFoldState {
-    let state = emptyRecursiveFoldState(workspaceRoot)
-    for (const event of events) state = foldProjectionEvent(state, event)
-    return state
-  }
-
-  /** Phase D R2: the registered projection unit (key 'recursive'). */
-  get projectionUnit() {
-    return recursiveProjectionUnit
-  }
-
-  /** Phase D R9: whether a worktreeRoot is inside the workspace control-plane root. */
-  isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean {
-    return isInsideWorkspace(worktreeRoot, workspaceRoot)
-  }
-
   /** Phase C R7: resolve the enforcement config (strict|advisory, default advisory). */
   get enforcementConfig(): EnforcementConfig {
     return this._enforcementConfig ?? DEFAULT_ENFORCEMENT
@@ -562,3 +585,32 @@ function setOrInsertField(content: string, fieldName: string, value: string, aft
 function escapeRegExp(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
+
+/**
+ * Parse the vendored lint-recursive-run.py stdout into a LintArtifactResult.
+ * [FAIL] lines -> errors, [WARN] lines -> warnings. When the run directory has
+ * multiple artifacts, FAIL/WARN lines carry the artifact path; we keep only the
+ * lines for the requested artifact (or all when the path is ambiguous).
+ */
+function parseLintOutput(stdout: string, target: string, runId: string): LintArtifactResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const failRe = /^\[FAIL\]\s+(.*)$/gm
+  const warnRe = /^\[WARN\]\s+(.*)$/gm
+  const targetSuffix = target.replace(/^.*[\\/]/, '')
+  const isForTarget = (line: string) => {
+    const pathMatch = line.match(/[A-Za-z0-9_.-]+\.md/)
+    return !pathMatch || pathMatch[0] === targetSuffix
+  }
+  let m: RegExpExecArray | null
+  while ((m = failRe.exec(stdout)) !== null) {
+    if (isForTarget(m[1])) errors.push(m[1].trim())
+  }
+  while ((m = warnRe.exec(stdout)) !== null) {
+    if (isForTarget(m[1])) warnings.push(m[1].trim())
+  }
+  // If the target artifact appears nowhere in the output but the run was linted,
+  // keep the parsed errors/warnings (canonical script lints the whole run).
+  return { artifact: target, runId, errors, warnings, passed: errors.length === 0 }
+}
+

package/src/snapshot.ts

@@ -0,0 +1,104 @@
+/**
+ * snapshotWorkspace(root): fold the filesystem into the RecursiveProjection whole value.
+ *
+ * SP2 R1 (live-route) — the ONLY projection path. The board/strip read this through
+ * the host HTTP/SSE route; cold resume and every GET are a FRESH fs read (the route
+ * never serves a cached/stale snapshot). Per-workspace: root is the resolved
+ * control-plane root (cwd == workspace root, cwd == subdir, or cwd == repo root).
+ *
+ * Phase-lock facts (lockedAt/lockHash) are enriched from lock receipts because
+ * foldRun PhaseState carries no lock fields; state comes from getArtifactState.
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { discoverRuns } from './run.ts'
+import { foldRun } from './status.ts'
+import { getLockStatus, receiptPath, readReceipt } from './lock.ts'
+import type { RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState } from './types.ts'
+
+/** One locked-phase fact from a lock receipt (artifacts/<file>.receipt.json). */
+interface LockFacts {
+  lockedAt?: string
+  lockHash?: string
+}
+
+/** Resolve a run's lock facts for one artifact file (receipt first, status fallback). */
+function lockFactsOf(runDir: string, artifact: string): LockFacts {
+  const receipt = readReceipt(runDir, artifact)
+  if (receipt && typeof receipt.locked_at === 'string' && typeof receipt.artifact_hash === 'string') {
+    return {
+      lockedAt: receipt.locked_at,
+      lockHash: receipt.artifact_hash,
+    }
+  }
+  // No usable receipt: fall back to the artifact's own LockedAt/LockHash fields.
+  const status = getLockStatus(join(runDir, artifact))
+  if (status !== 'LOCKED') return {}
+  return {
+    lockedAt: new Date(0).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    lockHash: '0'.repeat(64),
+  }
+}
+
+/** One phase row from a run's folded status (locked facts enriched). */
+function phaseRowOf(runDir: string, key: string, file: string, status: string): RecursivePhaseRow {
+  const row: RecursivePhaseRow = { phase: key, status }
+  if (status === 'LOCKED') {
+    const facts = lockFactsOf(runDir, file)
+    if (facts.lockedAt !== undefined) row.lockedAt = facts.lockedAt
+    if (facts.lockHash !== undefined) row.lockHash = facts.lockHash
+  }
+  return row
+}
+
+/**
+ * Fold one run directory into a RecursiveRunCard (the wire shape the board renders).
+ * Runs that no longer exist on disk are omitted (the fs is the source of truth).
+ */
+export function foldRunCard(runDir: string, runId: string, worktreeRoot: string): RecursiveRunCard {
+  const status = foldRun(runDir, runId)
+  // Wire contract parity (deleted projection.ts): phases are keyed by FILENAME
+  // (the recursive/phase event carried phase: '03-implementation-summary.md'),
+  // which is what derive.ts phaseGroupOf parses. phase.key ('03', '00R', '00W')
+  // would never match the filename regex and would break columnForRun/cardFacts.
+  const phases: Record<string, RecursivePhaseRow> = {}
+  for (const phase of status.phases) {
+    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status)
+  }
+  const state = runStateOf(status)
+  return {
+    runId,
+    worktreeRoot,
+    phases,
+    state,
+    tampers: {},
+    subagents: {},
+  }
+}
+
+/**
+ * Derive the run-level state from the folded status. The fs stores no run-level
+ * state file, so the honest mapping is: 'complete' when every non-optional phase
+ * exists and is lock-valid, else 'active'. Transient facts (gateBlocked, tamper,
+ * subagent activity) are NOT fs-recoverable and read as absent (recorded
+ * limitation; future enhancement).
+ */
+function runStateOf(status: ReturnType<typeof foldRun>): RecursiveRunState {
+  const mandatory = status.phases.filter(p => !p.optional)
+  const complete = mandatory.every(p => p.exists && p.lockValid)
+  return complete ? 'complete' : 'active'
+}
+
+/**
+ * Fold every run under <root>/.recursive/run/ into the projection, grouped by
+ * worktree root then runId. A fresh fs read on every call (cold-resume live).
+ */
+export function snapshotWorkspace(root: string): RecursiveProjection {
+  const projection: RecursiveProjection = {}
+  for (const runId of discoverRuns(root)) {
+    const runDir = join(root, '.recursive', 'run', runId)
+    projection[root] ??= {}
+    projection[root][runId] = foldRunCard(runDir, runId, root)
+  }
+  return projection
+}

package/lib/client/node.d.ts

@@ -1,71 +0,0 @@
-/**
- * Conversation run node (Phase D R7, §11.6): a structural ConversationNodeDefinition
- * over the recursive/* event family, keyed by runId + worktreeRoot. One compact,
- * live node per run in the Chat view. PURE fold (no React) — the renderer lives
- * in slots.ts.
- *
- * The real ConversationNodeDefinition contract arrives from
- * @deepseek-ai/dsh-client-runtime/client at compose time; the structural shape
- * here is type-compatible with the cookbook surface (match/start/update/
- * buildViewNode + target/kind). The host links the bundle's exports to the real
- * runtime identities.
- */
-import type { ClientSessionEvent } from './contract.ts';
-export declare const RECURSIVE_NODE_KIND = "recursive/run";
-/** The chat-node payload the renderer receives (pure derived state). */
-export interface RecursiveNodeData {
-    readonly runId: string;
-    readonly worktreeRoot: string;
-    readonly state: string;
-    readonly currentPhase: string | null;
-    readonly lockedCount: number;
-    readonly totalPhases: number;
-    readonly tampered: boolean;
-    readonly gateBlocked: boolean;
-    readonly mergedToRepoRoot?: string;
-}
-/** Pure fold state for one run node. */
-export interface RecursiveNodeState {
-    runId: string;
-    worktreeRoot: string;
-    state: string;
-    phases: Record<string, {
-        phase: string;
-        status: string;
-    }>;
-    tampered: boolean;
-    gateBlocked: boolean;
-    mergedToRepoRoot?: string;
-}
-/** Extract a stable (runId, worktreeRoot) business id + lifecycle role from one event. */
-export declare function matchRecursiveNode(event: ClientSessionEvent): {
-    id: string;
-    role: 'start' | 'update';
-} | null;
-/** Fold one recursive/* event into the node state. */
-export declare function foldRecursiveNode(s: RecursiveNodeState | undefined, event: ClientSessionEvent): RecursiveNodeState;
-/** The structural ConversationNodeDefinition (host links to the real contract). */
-export declare const recursiveNodeDefinition: {
-    kind: string;
-    target: string;
-    match: typeof matchRecursiveNode;
-    start: (_ctx: unknown, match: {
-        event: ClientSessionEvent;
-    }) => RecursiveNodeState;
-    update: (ctx: {
-        state: RecursiveNodeState;
-    }, match: {
-        event: ClientSessionEvent;
-    }) => RecursiveNodeState;
-    buildViewNode: (ctx: {
-        key: string;
-        id: string;
-        state?: RecursiveNodeState;
-    }) => {
-        key: string;
-        kind: string;
-        id: string;
-        target: string;
-        data: RecursiveNodeData;
-    } | null;
-};

package/lib/events.d.ts

@@ -1,173 +0,0 @@
-/**
- * recursive/* session events (Phase D R1, PROPOSAL 11.2/11.6): the complete
- * durable event vocabulary the projection folds, the board renders, and the
- * conversation node correlates. Every payload carries a non-empty
- * { runId, worktreeRoot } so the whole plane is worktree-aware and the
- * projection can group runs by their control-plane root (binding
- * workspace-scoping invariant, run 03 R1).
- *
- * Events are LOG-ONLY (no live mirror): the projection unit (projection.ts)
- * is the only derived view. Payloads are plain JSON and declared on the
- * SessionEventMap merge via @deepseek-ai/dsh-session/types.
- *
- * The pure constructor helpers below enforce the runId + non-empty
- * worktreeRoot invariant at emit time, so a malformed event fails loud at
- * the emit site instead of silently landing cross-workspace.
- */
-import type { RecursiveRunState } from './types.ts';
-/** Declare the recursive/* event family on the session event map (merge-extensible). */
-declare module '@deepseek-ai/dsh-session/types' {
-    interface SessionEventMap {
-        /**
-         * A transition the lifecycle driver is ABOUT to validate/commit (logged
-         * before any file write). The pre-step gate reads this as the caller of the
-         * transition set — never a projection event (log-only internal signal).
-         */
-        'recursive/phase-intent': {
-            runId: string;
-            worktreeRoot: string;
-            targetArtifact: string;
-            kind: 'lock' | 'reopen' | 'advance';
-            evidence?: Record<string, unknown>;
-        };
-        /** A run was created/bootstrapped in this workspace. */
-        'recursive/run-created': {
-            runId: string;
-            worktreeRoot: string;
-            template?: string;
-            repo?: string;
-        };
-        /** A phase transition committed (validate -> commit -> flush -> emit). */
-        'recursive/phase': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            status: string;
-        };
-        /** A phase artifact was locked (lock hash + timestamp recorded). */
-        'recursive/phase-locked': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            lockedAt: string;
-            lockHash: string;
-        };
-        /** A transition's gate predicate failed (rejected in strict, warned in advisory). */
-        'recursive/gate-blocked': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            failures: string[];
-            kind: string;
-        };
-        /** fs/observed detected a change to a locked artifact outside a tool call. */
-        'recursive/tamper': {
-            runId: string;
-            worktreeRoot: string;
-            path: string;
-            reason: string;
-        };
-        /** A run was merged back to the repo root (conversation history re-keys). */
-        'recursive/run-merged': {
-            runId: string;
-            worktreeRoot: string;
-            repoRoot: string;
-        };
-        /** Run-level lifecycle flag (active/paused/blocked/complete + reason). */
-        'recursive/run-state': {
-            runId: string;
-            worktreeRoot: string;
-            state: RecursiveRunState;
-            reason?: string;
-        };
-        /** A subagent started for this run. */
-        'recursive/subagent-start': {
-            runId: string;
-            worktreeRoot: string;
-            childId: string;
-            role: string;
-            provider: string;
-        };
-        /** A subagent finished for this run. */
-        'recursive/subagent-end': {
-            runId: string;
-            worktreeRoot: string;
-            childId: string;
-            role: string;
-            provider: string;
-            status: 'running' | 'done' | 'failed';
-        };
-    }
-}
-/** Enforce the runId + non-empty worktreeRoot invariant at emit time. */
-export declare function requireRunKey(runId: string, worktreeRoot: string): void;
-export interface PhaseIntentInput {
-    runId: string;
-    worktreeRoot: string;
-    targetArtifact: string;
-    kind: 'lock' | 'reopen' | 'advance';
-    evidence?: Record<string, unknown>;
-}
-export interface RunCreatedInput {
-    runId: string;
-    worktreeRoot: string;
-    template?: string;
-    repo?: string;
-}
-export interface PhaseInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    status: string;
-}
-export interface PhaseLockedInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    lockedAt: string;
-    lockHash: string;
-}
-export interface GateBlockedInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    failures: string[];
-    kind: string;
-}
-export interface TamperInput {
-    runId: string;
-    worktreeRoot: string;
-    path: string;
-    reason: string;
-}
-export interface RunMergedInput {
-    runId: string;
-    worktreeRoot: string;
-    repoRoot: string;
-}
-export interface RunStateInput {
-    runId: string;
-    worktreeRoot: string;
-    state: RecursiveRunState;
-    reason?: string;
-}
-export interface SubagentInput {
-    runId: string;
-    worktreeRoot: string;
-    childId: string;
-    role: string;
-    provider: string;
-}
-export interface SubagentEndInput extends SubagentInput {
-    status: 'running' | 'done' | 'failed';
-}
-export declare function phaseIntent(data: PhaseIntentInput): PhaseIntentInput;
-export declare function runCreated(data: RunCreatedInput): RunCreatedInput;
-export declare function phase(data: PhaseInput): PhaseInput;
-export declare function phaseLocked(data: PhaseLockedInput): PhaseLockedInput;
-export declare function gateBlocked(data: GateBlockedInput): GateBlockedInput;
-export declare function tamper(data: TamperInput): TamperInput;
-export declare function runMerged(data: RunMergedInput): RunMergedInput;
-export declare function runState(data: RunStateInput): RunStateInput;
-export declare function subagentStart(data: SubagentInput): SubagentInput;
-export declare function subagentEnd(data: SubagentEndInput): SubagentEndInput;