@try-works/dsh-recursive-mode 0.1.2 → 0.1.4

package/src/bootstrap.ts

@@ -1,12 +1,28 @@
 /**
- * Idempotent scaffold installer + Stage B workflow init (R6). TS port of
- * install-recursive-mode.py's core: bootstrap the /.recursive/ control plane
- * when missing (no-op when present), enumerate runs as directory names only,
- * and drive the agent/session-start Stage B (new vs resume) workspace-scoped
- * to the session's control-plane root (R1).
+ * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
+ * core: bootstrap the FULL canonical /.recursive/ control plane + cross-tool
+ * bridges byte-identically (RECURSIVE.md marker-wrapped, AGENTS.md, STATE/
+ * DECISIONS, memory routers + shards, config/recursive-router.json, .gitignore,
+ * vendored runtime scripts copied into .recursive/scripts/), plus the
+ * agent/session-start Stage B (new vs resume) workspace-scoped to the session's
+ * control-plane root (R1).
+ *
+ * Templates + bodies + runtime scripts are SHIPPED package files under
+ * references/ (never inlined TS string literals) and resolved relative to this
+ * module (package install location), never process.cwd().
  */
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, readFileSync, copyFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url))
+/** Package root: <package>/src/.. — references/ sits next to src/. */
+export const PACKAGE_ROOT = join(MODULE_DIR, '..')
+
+/** references/ root (shipped package files). */
+export function referencesRoot(): string {
+  return join(PACKAGE_ROOT, 'references')
+}
 
 export interface BootstrapResult {
   root: string
@@ -23,56 +39,254 @@ export interface StageBResult {
   activeRunId?: string
 }
 
-const CONTROL_PLANE_FILES: Record<string, string> = {
-  'RECURSIVE.md': '# recursive-mode\\n\\nrecursive-mode workflow. The canonical spec is maintained by the installed skill; this scaffold is the repo-local control plane.\\n',
-  'STATE.md': '# STATE\\n\\nRepository state ledger.\\n',
-  'DECISIONS.md': '# DECISIONS\\n\\nDecision ledger.\\n',
+// Marker strings (byte-identical to the canonical installer).
+const M = {
+  recursiveStart: '<!-- RECURSIVE-MODE-CANONICAL:START -->',
+  recursiveEnd: '<!-- RECURSIVE-MODE-CANONICAL:END -->',
+  memoryStart: '<!-- RECURSIVE-MODE-MEMORY:START -->',
+  memoryEnd: '<!-- RECURSIVE-MODE-MEMORY:END -->',
+  agentsStart: '<!-- RECURSIVE-MODE-AGENTS:START -->',
+  agentsEnd: '<!-- RECURSIVE-MODE-AGENTS:END -->',
+  plansStart: '<!-- RECURSIVE-MODE-PLANS-BRIDGE:START -->',
+  plansEnd: '<!-- RECURSIVE-MODE-PLANS-BRIDGE:END -->',
+  cursorrulesStart: '# RECURSIVE-MODE-MEMORY-POINTERS:START',
+  cursorrulesEnd: '# RECURSIVE-MODE-MEMORY-POINTERS:END',
+  repoMdStart: '<!-- RECURSIVE-MODE-MEMORY-POINTERS:START -->',
+  repoMdEnd: '<!-- RECURSIVE-MODE-MEMORY-POINTERS:END -->',
+}
+
+/** write_utf8_no_bom: LF newlines, no BOM. */
+export function writeUtf8NoBom(path: string, content: string): void {
+  writeFileSync(path, content, { encoding: 'utf8' })
+}
+
+/** ensure_gitignore_line: add the line when absent (preserving existing). */
+function ensureGitignoreLine(repoRoot: string, line: string): void {
+  const gitignorePath = join(repoRoot, '.gitignore')
+  const normalized = line.trim()
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : ''
+  const existingLines = existing.split(/\r?\n/)
+  if (existingLines.some(c => c.trim() === normalized)) return
+  let updated = existing
+  if (updated && !updated.endsWith('\n')) updated += '\n'
+  updated += normalized + '\n'
+  writeUtf8NoBom(gitignorePath, updated)
+}
+
+/** upsert_marked_block: replace the START..END block, else append after existing. */
+function upsertMarkedBlock(filePath: string, startMarker: string, endMarker: string, blockBody: string): void {
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  const block = startMarker + '\n' + blockBody + '\n' + endMarker
+  const pattern = new RegExp(escapeRegExp(startMarker) + '[\\s\\S]*?' + escapeRegExp(endMarker))
+  let updated: string
+  if (pattern.test(existing)) {
+    updated = existing.replace(pattern, block)
+  } else if (existing.trim() !== '') {
+    updated = existing.replace(/\s+$/, '') + '\n\n' + block + '\n'
+  } else {
+    updated = block + '\n'
+  }
+  if (updated !== existing) writeUtf8NoBom(filePath, updated)
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** normalize_plain_or_wrapped_content: strip markers; return plain body when wrapped. */
+function normalizePlainOrWrappedContent(content: string, startMarker: string, endMarker: string): string {
+  const startIndex = content.indexOf(startMarker)
+  const endIndex = content.lastIndexOf(endMarker)
+  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+    return content.replace(/\r?\n+$/, '')
+  }
+  const prefix = content.slice(0, startIndex).replace(/\r?\n+$/, '')
+  if (prefix.trim() !== '') return prefix
+  const bodyStart = startIndex + startMarker.length
+  return content.slice(bodyStart, endIndex).replace(/^\r?\n+|\r?\n+$/g, '')
+}
+
+/** upsert_or_migrate_canonical: canonical block upsert with plain-file migration. */
+function upsertOrMigrateCanonical(filePath: string, startMarker: string, endMarker: string, canonicalBody: string): void {
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  const block = startMarker + '\n' + canonicalBody.replace(/\r?\n+$/, '') + '\n' + endMarker
+  const pattern = new RegExp(escapeRegExp(startMarker) + '[\\s\\S]*?' + escapeRegExp(endMarker))
+  let updated: string
+  if (pattern.test(existing)) {
+    updated = existing.replace(pattern, block)
+  } else if (existing.trim() === '') {
+    updated = block + '\n'
+  } else if (existing.replace(/\r?\n+$/, '') === canonicalBody.replace(/\r?\n+$/, '')) {
+    updated = block + '\n'
+  } else {
+    updated = existing.replace(/\s+$/, '') + '\n\n' + block + '\n'
+  }
+  if (updated !== existing) writeUtf8NoBom(filePath, updated)
+}
+
+/** Read a shipped body file (references/bodies/<name>) — CRLF-normalized. */
+function body(name: string): string {
+  return readFileSync(join(referencesRoot(), 'bodies', name), 'utf8').replace(/\r\n/g, '\n')
+}
+
+/** Read the canonical RECURSIVE.md template from shipped references/bootstrap/ — CRLF-normalized. */
+function canonicalWorkflowContent(): string {
+  return readFileSync(join(referencesRoot(), 'bootstrap', 'RECURSIVE.md'), 'utf8').replace(/\r\n/g, '\n')
+}
+
+/** Read the agents bridge block from shipped references/ — CRLF-normalized. */
+function agentsBlockContent(): string {
+  return readFileSync(join(referencesRoot(), 'agents-block.md'), 'utf8').replace(/\r\n/g, '\n').replace(/\r?\n+$/, '')
+}
+
+/** default_router_policy(): byte-identical to recursive_router_lib.default_router_policy + pretty_json. */
+function defaultRouterPolicy(): string {
+  const roleRoutes: Record<string, Record<string, unknown>> = {
+    orchestrator: { enabled: true, mode: 'local-only', cli: null, model: null, fallback: 'local-controller' },
+    analyst: { enabled: true, mode: 'external-cli', cli: null, model: null, fallback: 'self-audit' },
+    planner: { enabled: true, mode: 'external-cli', cli: null, model: null, fallback: 'self-audit' },
+    implementer: { enabled: false, mode: 'external-cli', cli: null, model: null, fallback: 'local-controller' },
+    'code-reviewer': { enabled: true, mode: 'external-cli', cli: null, model: null, fallback: 'self-audit' },
+    tester: { enabled: true, mode: 'external-cli', cli: null, model: null, fallback: 'self-audit' },
+    'memory-auditor': { enabled: true, mode: 'external-cli', cli: null, model: null, fallback: 'self-audit' },
+  }
+  const policy = {
+    version: 1,
+    defaults: {
+      when_role_unconfigured: 'ask',
+      when_cli_unavailable: 'fallback-local',
+      when_model_unknown: 'ask',
+      allow_auto_assign_if_single_cli: false,
+      probe_timeout_ms: 50000,
+      invoke_timeout_ms: 180000,
+    },
+    role_routes: roleRoutes,
+    cli_overrides: {},
+    custom_clis: [],
+  }
+  return JSON.stringify(policy, null, 2) + '\n'
 }
 
-const MEMORY_FILES: Record<string, string> = {
-  'memory/MEMORY.md': '# MEMORY\\n\\nDurable memory router.\\n',
-  'memory/skills/SKILLS.md': '# SKILLS\\n\\nSkill memory router.\\n',
+/** ensure_router_scaffold: write config/recursive-router.json when missing. */
+function ensureRouterScaffold(repoRoot: string): void {
+  const configDir = join(repoRoot, '.recursive', 'config')
+  const policyPath = join(configDir, 'recursive-router.json')
+  if (!existsSync(policyPath)) {
+    mkdirSync(configDir, { recursive: true })
+    writeUtf8NoBom(policyPath, defaultRouterPolicy())
+  }
 }
 
 /**
- * Idempotent scaffold install: creates the /.recursive/ control plane when
- * missing. Never overwrites existing files; preserves unrelated content.
+ * Idempotent scaffold install: reproduce the canonical installer's 82-file
+ * tree byte-for-byte. Never overwrites existing user content; marked blocks
+ * are re-upserted in place.
  */
 export function bootstrapScaffold(root: string): BootstrapResult {
-  const recursiveRoot = join(root, '.recursive')
   const created: string[] = []
   const existing: string[] = []
 
-  const writeIfMissing = (rel: string, content: string) => {
-    const path = join(recursiveRoot, rel)
-    if (existsSync(path)) {
-      existing.push(rel)
-      return
+  const noteDir = (rel: string) => {
+    const p = join(root, rel)
+    if (existsSync(p)) existing.push(rel + '/')
+    else { mkdirSync(p, { recursive: true }); created.push(rel + '/') }
+  }
+  const noteFile = (rel: string, content?: string) => {
+    const p = join(root, rel)
+    if (existsSync(p)) { existing.push(rel); return }
+    if (content !== undefined) {
+      mkdirSync(dirname(p), { recursive: true })
+      writeUtf8NoBom(p, content)
+    } else {
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, '')
     }
-    mkdirSync(join(path, '..'), { recursive: true })
-    writeFileSync(path, content, 'utf8')
     created.push(rel)
   }
 
-  for (const [rel, content] of Object.entries(CONTROL_PLANE_FILES)) writeIfMissing(rel, content)
-  for (const [rel, content] of Object.entries(MEMORY_FILES)) writeIfMissing(rel, content)
-  // run/ + config/ + memory/ dirs (empty dirs for the scaffold)
-  for (const dir of ['run', 'config', 'memory/training']) {
-    const path = join(recursiveRoot, dir)
-    if (!existsSync(path)) {
-      mkdirSync(path, { recursive: true })
-      created.push(dir + '/')
+  const recursiveRoot = join(root, '.recursive')
+  const memoryRoot = join(recursiveRoot, 'memory')
+  const skillMemoryRoot = join(memoryRoot, 'skills')
+
+  // Directories.
+  for (const rel of [
+    '.recursive', '.codex', '.agent', '.github',
+    '.recursive/memory', '.recursive/memory/training', '.recursive/memory/skills', '.recursive/run', '.recursive/config',
+  ]) noteDir(rel)
+  for (const sub of ['domains', 'patterns', 'incidents', 'episodes', 'archive']) noteDir(join('.recursive/memory', sub))
+  for (const sub of ['availability', 'usage', 'issues', 'patterns']) noteDir(join('.recursive/memory/skills', sub))
+
+  // .gitkeeps.
+  for (const rel of [
+    '.recursive/memory/domains/.gitkeep', '.recursive/memory/patterns/.gitkeep', '.recursive/memory/incidents/.gitkeep',
+    '.recursive/memory/episodes/.gitkeep', '.recursive/memory/archive/.gitkeep', '.recursive/memory/training/.gitkeep',
+    '.recursive/memory/skills/availability/.gitkeep', '.recursive/memory/skills/usage/.gitkeep',
+    '.recursive/memory/skills/issues/.gitkeep', '.recursive/memory/skills/patterns/.gitkeep', '.recursive/run/.gitkeep',
+  ]) noteFile(rel, '')
+
+  // Runtime scripts: copy vendored references/scripts/* into .recursive/scripts/.
+  const scriptsSrc = join(referencesRoot(), 'scripts')
+  const scriptsDst = join(recursiveRoot, 'scripts')
+  mkdirSync(scriptsDst, { recursive: true })
+  for (const name of readdirSync(scriptsSrc)) {
+    const src = join(scriptsSrc, name)
+    if (!statSync(src).isFile()) continue
+    const dst = join(scriptsDst, name)
+    if (!existsSync(dst) || !buffersEqual(src, dst)) {
+      copyFileSync(src, dst)
+      created.push('.recursive/scripts/' + name)
     } else {
-      existing.push(dir + '/')
+      existing.push('.recursive/scripts/' + name)
     }
   }
 
-  return {
-    root,
-    bootstrapped: created.length > 0,
-    created,
-    existing,
+  // Plain control-plane files (trailing newline).
+  noteFile('.recursive/RECURSIVE.md', '# RECURSIVE.md\n')
+  noteFile('.recursive/AGENTS.md', '# AGENTS.md\n')
+  noteFile('.recursive/STATE.md', body('state.md') + '\n')
+  noteFile('.recursive/DECISIONS.md', body('decisions.md') + '\n')
+  noteFile('.recursive/memory/MEMORY.md', '# MEMORY.md\n')
+  noteFile('.recursive/memory/skills/SKILLS.md', '# SKILLS.md\n')
+  noteFile('.recursive/memory/skills/usage/skill-discovery-and-evaluation.md', body('skill-discovery.md') + '\n')
+  noteFile('.recursive/memory/skills/patterns/delegated-verification-and-refresh.md', body('delegated-verification.md') + '\n')
+  noteFile('.recursive/memory/skills/patterns/phase8-skill-memory-promotion.md', body('phase8-skill-memory.md') + '\n')
+  noteFile('.codex/AGENTS.md', '# AGENTS.md\n')
+  noteFile('.agent/PLANS.md', '# PLANS.md\n')
+  noteFile('.cursorrules', '')
+  noteFile('CLAUDE.md', '')
+  noteFile('.github/copilot-instructions.md', '')
+
+  // .gitignore.
+  ensureGitignoreLine(root, '/.recursive/config/recursive-router-discovered.json')
+
+  // Router config.
+  ensureRouterScaffold(root)
+
+  // Marked blocks.
+  upsertMarkedBlock(join(recursiveRoot, 'AGENTS.md'), M.agentsStart, M.agentsEnd, body('recursive-agents-router.md'))
+  upsertMarkedBlock(join(memoryRoot, 'MEMORY.md'), M.memoryStart, M.memoryEnd, body('memory-router.md'))
+  upsertMarkedBlock(join(skillMemoryRoot, 'SKILLS.md'), M.memoryStart, M.memoryEnd, body('skill-memory-router.md'))
+  upsertMarkedBlock(join(root, '.cursorrules'), M.cursorrulesStart, M.cursorrulesEnd, body('cursorrules.md'))
+  upsertMarkedBlock(join(root, 'CLAUDE.md'), M.repoMdStart, M.repoMdEnd, body('claude.md'))
+  upsertMarkedBlock(join(root, '.github', 'copilot-instructions.md'), M.repoMdStart, M.repoMdEnd, body('copilot.md'))
+  upsertMarkedBlock(join(root, '.codex', 'AGENTS.md'), M.agentsStart, M.agentsEnd, body('codex-agents.md'))
+  const rootAgents = join(root, 'AGENTS.md')
+  if (existsSync(rootAgents)) {
+    upsertMarkedBlock(rootAgents, M.agentsStart, M.agentsEnd, agentsBlockContent())
   }
+  upsertMarkedBlock(join(root, '.agent', 'PLANS.md'), M.plansStart, M.plansEnd, body('plans-bridge.md'))
+
+  // Canonical RECURSIVE.md (marker-wrapped, migrate plain installs).
+  const canonicalBody = normalizePlainOrWrappedContent(canonicalWorkflowContent(), M.recursiveStart, M.recursiveEnd)
+  upsertOrMigrateCanonical(join(recursiveRoot, 'RECURSIVE.md'), M.recursiveStart, M.recursiveEnd, canonicalBody)
+
+  return { root, bootstrapped: created.length > 0, created, existing }
+}
+
+function buffersEqual(a: string, b: string): boolean {
+  const ab = readFileSync(a)
+  const bb = readFileSync(b)
+  return ab.length === bb.length && ab.equals(bb)
 }
 
 /**
@@ -115,4 +329,4 @@ export function stageBWorkflowInit(input: StageBInput): StageBResult {
     runs,
     activeRunId,
   }
-}
+}

package/src/client/apply-guard.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-module-instance apply guard for the recursive client bundle (mirrors
+ * the dsh-task-board apply-guard). The client factory can run more than once in
+ * a single page lifetime (a stale bundle mixed with a rebuilt one); without a
+ * guard every factory run mounts its own board/strip. First claim wins; later
+ * claims no-op until the claim is released (fiber unload / hot-reload).
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __dshRecursiveModeClientApplied: boolean | undefined
+}
+
+/** Claims the client apply slot. Returns true when this call won the slot. */
+export function claimClientApply(): boolean {
+  if (globalThis.__dshRecursiveModeClientApplied === true) return false
+  globalThis.__dshRecursiveModeClientApplied = true
+  return true
+}
+
+/** Releases the claim (called from the client fiber cleanup on unload/hot-reload). */
+export function releaseClientApply(): void {
+  globalThis.__dshRecursiveModeClientApplied = undefined
+}

package/src/client/contract.ts

@@ -1,17 +1,18 @@
 /**
  * Structural client seams (self-contained). The real @deepseek-ai/dsh-client-*
  * packages are HOST-INJECTED at bundle time via dsh.client.inject (never
- * installed in this package's dependency tree — they depend on workspace:^
- * peers that resolve only inside the DSH workspace). We declare the minimal
- * shapes we consume so the pure client modules type-check and bundle in
- * isolation; the DSH loader links them to the real runtime identities at
- * compose time.
+ * installed in this package's dependency tree). We declare the minimal shapes
+ * we consume so the pure client modules type-check and bundle in isolation;
+ * the DSH loader links them to the real runtime identities at compose time.
  *
- * One deliberate narrowing: the client only READS (R9 read-only). It never
- * calls back into the host; every host fact arrives through the projection.
+ * SP2 R1 (live route): the client now CALLS the host route (read-only GET
+ * state + SSE events) instead of reading a session projection. The host serves
+ * the per-workspace filesystem fold; this module never mutates the host and
+ * never touches the filesystem (R9).
  */
+import type { RecursiveProjection } from '../types.ts'
 
-/** SessionEvent-like carrier (the projection/node fold reads events by shape). */
+/** SessionEvent-like carrier (kept for the pure derive surface; the live route replaces the fold). */
 export interface ClientSessionEvent {
   type: string
   seq?: number
@@ -19,24 +20,44 @@ export interface ClientSessionEvent {
   data?: Record<string, unknown>
 }
 
-/** A session header (cwd is the control-plane root). */
+/** A session header (cwd is the session's canonical cwd). */
 export interface ClientSessionHeader {
   cwd?: string
 }
 
-/** Minimal appendable session (log-only write seam). */
-export interface ClientSession {
-  header: ClientSessionHeader
-  append(type: string, data: unknown): unknown
+/** A session-list row (mirrors SessionSummary — cwd + agentPreset are the gate inputs). */
+export interface SessionSummaryRow {
+  id: string
+  cwd?: string
+  /** Agent preset this session was composed from; absent when the deployment has none. */
+  agentPreset?: string
 }
 
-/** The client root context the bundle receives from the module loader. */
-export interface ClientContext {
-  slots: ClientSlots
-  get(name: string): unknown
+/** The session-list snapshot (mirrors SessionListState). */
+export interface SessionListStateLike {
+  ids: string[]
+  byId: Record<string, SessionSummaryRow>
+  current: string | undefined
+}
+
+/** A snapshot store the client runtime hands out (mirrors SnapshotStore<T>). */
+export interface SnapshotStoreLike<T> {
+  getSnapshot(): T
+  subscribe(fn: () => void): () => void
+}
+
+/** The sessions service surface (mirrors ISessions.list). */
+export interface ISessionsLike {
+  list: SnapshotStoreLike<SessionListStateLike>
+}
+
+/** The slots registry surface the client injects into. */
+export interface ClientSlots {
+  inject(seat: string, factory: (ctx: unknown) => () => void): () => void
+  register(options: SlotOptions, component: unknown): () => void
 }
 
-/** A registered slot's options (list/keyed entries carry id/order/label). */
+/** A registered slot's options. */
 export interface SlotOptions {
   name: string
   id?: string
@@ -48,11 +69,38 @@ export interface SlotOptions {
   registrant?: unknown
 }
 
-/** The slot registry surface the client injects into. */
-export interface ClientSlots {
-  inject(seat: string, factory: (ctx: unknown) => () => void): () => void
-  register(options: SlotOptions, component: unknown): () => void
+/** The client root context the bundle receives from the module loader. */
+export interface ClientContext {
+  slots: ClientSlots
+  get(name: string): unknown
+  /** Cordis effect: registers a disposer; returns a disposer. */
+  effect(fn: () => () => void, label?: string): () => void
 }
 
-/** useProjection('recursive') reader — undefined = capability absent. */
-export type RecursiveProjectionReader = (key: 'recursive') => unknown
+/** The live state payload the host route serves (mirrors host-api.ts). */
+export interface LiveProjectionValue {
+  root: string | null
+  projection: RecursiveProjection
+  revision: number
+}
+
+/**
+ * The client-side preset gate (acceptance #3): the board/strip render ONLY when
+ * the CURRENT session's row reports agentPreset === 'recursive'. A non-recursive
+ * session (or a session whose preset is undefined) shows NOTHING — not an empty
+ * board, not a spinner.
+ */
+export function isRecursivePreset(sessions: ISessionsLike): boolean {
+  const snapshot = sessions.list.getSnapshot()
+  const current = snapshot.current
+  if (current === undefined) return false
+  return snapshot.byId[current]?.agentPreset === 'recursive'
+}
+
+/** The current session's cwd (the client passes it as a fallback hint; the host resolves the root). */
+export function currentSessionCwd(sessions: ISessionsLike): string {
+  const snapshot = sessions.list.getSnapshot()
+  const current = snapshot.current
+  if (current === undefined) return ''
+  return snapshot.byId[current]?.cwd ?? ''
+}

package/src/client/host-api.ts

@@ -0,0 +1,90 @@
+/**
+ * Live recursive board/strip feed (SP2 R1): the browser half of the host
+ * HTTP/SSE route. Replaces useProjection('recursive') — the board reads the
+ * FILESYSTEM FOLD served by the host, keyed per-WORKSPACE. The client passes
+ * its sessionId (PRIMARY — the host resolves the cwd from the attached
+ * session header) plus cwd as a fallback hint while hydrating; the host
+ * resolves the recursive root server-side, never trusting a client path.
+ *
+ * READ-ONLY (R9): GET state + GET events only; this module never mutates the
+ * host and never touches the filesystem.
+ *
+ * Mirrors the dsh-web-ui task-board + DSH-better-sidebar host-api pattern:
+ * fetch /state with no-store, EventSource /events with a visibilitychange
+ * re-listener, and an AbortController timeout on the initial fetch.
+ */
+import { RECURSIVE_API_PREFIX } from '../live-route.ts'
+import type { RecursiveProjection } from '../types.ts'
+
+/** The state payload the host serves. */
+export interface LiveRecursiveState {
+  root: string | null
+  projection: RecursiveProjection
+  revision: number
+}
+
+/** A single SSE frame. */
+export interface LiveRecursiveFrame extends LiveRecursiveState {}
+
+/** The client scope the host keys on: sessionId PRIMARY, cwd fallback hint. */
+export interface LiveScope {
+  sessionId?: string
+  cwd?: string
+}
+
+const FETCH_TIMEOUT_MS = 15_000
+
+/** Query-string encoder for the two params. */
+function scopeQuery(scope: LiveScope): string {
+  const parts: string[] = []
+  if (scope.sessionId) parts.push('sessionId=' + encodeURIComponent(scope.sessionId))
+  if (scope.cwd) parts.push('cwd=' + encodeURIComponent(scope.cwd))
+  return parts.length === 0 ? '' : '?' + parts.join('&')
+}
+
+/** Fetch the current state for one session scope (host resolves the workspace root). */
+export async function fetchLiveState(scope: LiveScope, signal?: AbortSignal): Promise<LiveRecursiveState> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const res = await fetch(RECURSIVE_API_PREFIX + '/state' + scopeQuery(scope), { signal: controller.signal, cache: 'no-store' })
+    if (!res.ok) throw new Error('recursive live state: HTTP ' + res.status)
+    return (await res.json()) as LiveRecursiveState
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Subscribe to the SSE events feed. Returns a disposer. The host pushes a full
+ * {revision, root, projection} frame on every fs change + a 15s heartbeat.
+ *
+ * @param scope - sessionId primary + cwd fallback (host resolves the root).
+ * @param onFrame - called per data frame.
+ * @param onError - called when the stream fails/ends (the caller re-subscribes).
+ */
+export function subscribeLiveEvents(scope: LiveScope, onFrame: (frame: LiveRecursiveFrame) => void, onError?: () => void): () => void {
+  const url = RECURSIVE_API_PREFIX + '/events' + scopeQuery(scope)
+  const es = new EventSource(url)
+  const onMessage = (event: MessageEvent) => {
+    try {
+      const frame = JSON.parse(event.data as string) as LiveRecursiveFrame
+      onFrame(frame)
+    } catch { /* malformed frame — ignore */ }
+  }
+  es.addEventListener('message', onMessage)
+  es.onerror = () => { es.close(); onError?.() }
+  const onVisible = () => {
+    if (document.visibilityState === 'visible') {
+      // Re-open the stream after the tab slept (the host heartbeat is the only
+      // liveness signal; a sleeping tab drops it).
+      es.close()
+      onError?.()
+    }
+  }
+  document.addEventListener('visibilitychange', onVisible)
+  return () => {
+    document.removeEventListener('visibilitychange', onVisible)
+    es.close()
+  }
+}

package/src/client/index.ts

@@ -1,28 +1,39 @@
 /**
- * Client entry (Phase D R4): the browser half of dsh-recursive-mode. Receives
- * the client root context from the DSH loader and registers the board,
- * inspector, conversation node, status strip, and settings page (§11.8).
- * READ-ONLY (R9): every host fact arrives through the recursive projection;
- * this module never touches the filesystem.
+ * Client entry (SP2 R1): the browser half of dsh-recursive-mode. Receives the
+ * client root context from the DSH loader and registers the board, inspector,
+ * status strip, and settings page. The board/strip read the LIVE host route
+ * (per-workspace filesystem fold) — not a session projection — and render ONLY
+ * for the recursive preset (acceptance #3). READ-ONLY (R9): the client never
+ * mutates the host.
  *
  * The apply(ctx) surface mirrors the shipped dsh-client-ui-* packages; the
  * dsh.client.inject list in package.json names the host packages the loader
  * must provide (they are injected at compose time, never installed here).
+ * The apply-guard prevents a stale+rebuilt bundle from double-mounting.
  */
 import type { ClientContext } from './contract.ts'
 import { registerSlots } from './slots.ts'
+import { claimClientApply, releaseClientApply } from './apply-guard.ts'
 
-export { recursiveNodeDefinition, RECURSIVE_NODE_KIND, matchRecursiveNode, foldRecursiveNode } from './node.ts'
-export type { RecursiveNodeData, RecursiveNodeState } from './node.ts'
 export { Board, listRuns } from './board.tsx'
 export { Inspector } from './inspector.tsx'
 export { StatusStrip } from './strip.tsx'
 export { RecursiveSettings } from './settings.tsx'
-export type { RecursiveProjectionReader } from './contract.ts'
+export { useLiveProjection } from './use-live.ts'
+export type { LiveProjectionSnapshot } from './use-live.ts'
+export { fetchLiveState, subscribeLiveEvents } from './host-api.ts'
+export type { LiveRecursiveState, LiveRecursiveFrame, LiveScope } from './host-api.ts'
+export { isRecursivePreset, currentSessionCwd } from './contract.ts'
+export type { SessionSummaryRow, SessionListStateLike, ISessionsLike, ClientContext } from './contract.ts'
 
-/** Browser-half plugin entry (R4). */
+/** Required services (fiber inject waiting — the runtime must be up first). */
+export const inject = ['slots', 'sessions', 'workspaces', 'connection']
+
+/** Browser-half plugin entry (R4 + SP2 R1). */
 export function apply(ctx: ClientContext): void {
-  // The conversation node is registered through the node-inject seam; the
-  // other surfaces through the slot registry.
+  // First application wins; a duplicated client injection would mount a second
+  // board/strip. Release on unload so a hot-reloaded bundle can claim again.
+  if (!claimClientApply()) return
+  ctx.effect(() => releaseClientApply, 'recursive: client apply claim')
   registerSlots(ctx)
 }