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

package/src/client/contract.ts

@@ -33,23 +33,25 @@ export interface SessionSummaryRow {
   agentPreset?: string
 }
 
-/** The session-list snapshot (mirrors SessionListState). */
+/**
+ * The session-list snapshot (mirrors the REAL SessionListState). useSessions is
+ * a SnapshotSelectorHook over this state; the identity selector `(s) => s`
+ * yields the full value, which the gate reads directly (ids/byId/current).
+ */
 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 REAL selector-hook shape (ui-slots store.ts):
+ *   SnapshotSelectorHook<T> = <S>(sel: (s: T) => S, eq?) => S
+ * The selector is REQUIRED — useSyncExternalStoreWithSelector needs it. Calling
+ * the hook with no selector passes sel=undefined and breaks the board mount.
+ * This is the run 10 live bug.
+ */
+export type SnapshotSelectorHook<T> = <S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean) => S
 
 /** The slots registry surface the client injects into. */
 export interface ClientSlots {
@@ -88,19 +90,14 @@ export interface LiveProjectionValue {
  * 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.
+ * board, not a spinner. Consumes the SessionListStateLike DIRECTLY (run 10 fix).
  */
-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'
+export function isRecursivePreset(state: SessionListStateLike): boolean {
+  if (state.current === undefined) return false
+  return state.byId[state.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 ?? ''
+export function currentSessionCwd(state: SessionListStateLike): string {
+  return state.current === undefined ? '' : (state.byId[state.current]?.cwd ?? '')
 }

package/src/client/index.ts

@@ -24,7 +24,7 @@ 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'
+export type { SessionSummaryRow, SessionListStateLike, SnapshotSelectorHook, ClientContext } from './contract.ts'
 
 /** Required services (fiber inject waiting — the runtime must be up first). */
 export const inject = ['slots', 'sessions', 'workspaces', 'connection']

package/src/client/open-state.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared board open-state (run 08 R1): module-level store behind the launcher,
+ * the shell.overlay entry, and the board<->inspector swap. Zero session events,
+ * zero host mutation — the client remains a read-only projection (R5/R9).
+ */
+import { useSyncExternalStore } from 'react'
+
+export interface BoardSelection {
+  worktreeRoot: string;
+  runId: string;
+}
+
+export interface BoardState {
+  open: boolean;
+  selection: BoardSelection | null;
+}
+
+export interface BoardOpenState {
+  get(): BoardState;
+  openBoard(): void;
+  close(): void;
+  openInspector(selection: BoardSelection): void;
+  backToBoard(): void;
+  subscribe(fn: () => void): () => void;
+}
+
+export function createBoardState(initial: BoardState = { open: false, selection: null }): BoardOpenState {
+  let state: BoardState = initial;
+  const listeners = new Set<() => void>();
+  const emit = (): void => { for (const fn of listeners) fn() };
+  return {
+    get: () => state,
+    openBoard: () => { state = { ...state, open: true }; emit(); },
+    close: () => { state = { ...state, open: false, selection: null }; emit(); },
+    openInspector: (selection) => { state = { ...state, open: true, selection }; emit(); },
+    backToBoard: () => { state = { ...state, selection: null }; emit(); },
+    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) }; },
+  };
+}
+
+/** App-wide singleton shared by the launcher, overlay, board, and inspector. */
+export const boardState = createBoardState();
+
+export function useBoardState(store: BoardOpenState = boardState): BoardState {
+  return useSyncExternalStore(store.subscribe, store.get, store.get);
+}

package/src/client/slots.ts

@@ -1,51 +1,75 @@
 /**
- * Slot registrations (SP2 R1): the sidebar launcher, the shell.overlay board,
- * the conversation.input.dock status strip, and the settings.section page.
+ * Slot registrations (SP2 R1 + run 08 R1/R3/R4): the sidebar launcher, the
+ * shell.overlay board, the conversation.input.dock status strip, and the
+ * settings.section page.
  *
- * The board (root scope) and strip (session scope) render ONLY for the
- * recursive preset — the gate reads the CURRENT session's agentPreset from the
- * sessions list snapshot (acceptance #3: a non-recursive session shows NOTHING).
+ * Run 08: the launcher now OPENS the shared board store (onClick), and the
+ * shell.overlay entry renders the board gated on that store + the recursive
+ * preset, swapping to the drill-down inspector when a run is selected.
  *
- * The board reads cwd from the ROOT-scope standard prop useSessions (the
- * scoped-slots root branch provides ONLY useSessions/useWorkspaces — useProjection
- * is session-scope-only, which is why the board never reads it). The strip reads
- * its sessionId from the session-scope standard prop.
+ * Run 10 (LIVE BUG FIX): useSessions is a SnapshotSelectorHook (NOT a zero-arg
+ * thunk) — it is called WITH a selector, e.g. useSessions((s) => s) for the
+ * full SessionListStateLike. The old code called useSessions() with NO selector
+ * and wrapped the garbage in a fake {list:{getSnapshot}} — so the preset gate
+ * never saw the recursive preset and the board never mounted (launcher click
+ * did nothing). The board/strip now consume the SessionListStateLike directly.
  *
  * READ-ONLY (R9): the client only GETs the live host route; no mutation.
  */
 import { createElement, type ReactNode } from 'react'
-import type { ClientContext, ISessionsLike, SnapshotStoreLike, SessionListStateLike } from './contract.ts'
+import type { ClientContext, SessionListStateLike, SnapshotSelectorHook } from './contract.ts'
 import { isRecursivePreset, currentSessionCwd } from './contract.ts'
 import { Board } from './board.tsx'
+import { Inspector } from './inspector.tsx'
 import { StatusStrip } from './strip.tsx'
 import { RecursiveSettings } from './settings.tsx'
 import { useLiveProjection } from './use-live.ts'
+import { boardState, useBoardState } from './open-state.ts'
 
-/** Structural standard-prop face for the root scope (useSessions only). */
+/** Structural standard-prop face for the root scope (useSessions/useWorkspaces). */
 interface RootSlotProps {
-  useSessions?: () => SessionListStateLike
-  useWorkspaces?: () => unknown
+  useSessions?: SnapshotSelectorHook<SessionListStateLike>
+  useWorkspaces?: SnapshotSelectorHook<unknown>
 }
 
 /** Structural standard-prop face for the session scope (sessionId + useSessions). */
 interface SessionSlotProps {
   sessionId?: string
-  useSessions?: () => SessionListStateLike
+  useSessions?: SnapshotSelectorHook<SessionListStateLike>
   useProjection?: unknown
 }
 
+export type OverlayContent = 'hidden' | 'board' | 'inspector'
+
+/** Gate: hidden unless open AND recursive preset; inspector when a run is selected. */
+export function overlayContent(state: { open: boolean; selection: unknown }, sessions: SessionListStateLike): OverlayContent {
+  if (!state.open) return 'hidden'
+  if (!isRecursivePreset(sessions)) return 'hidden'
+  if (state.selection !== null) return 'inspector'
+  return 'board'
+}
+
+/**
+ * THE FIX (run 10): useSessions is a SELECTOR hook — always call it WITH a
+ * selector. The identity selector `(s) => s` yields the full SessionListStateLike.
+ * Exported so the spec can assert the selector is actually passed.
+ */
+export function useRecursiveSessions(useSessions: SnapshotSelectorHook<SessionListStateLike>): SessionListStateLike {
+  return useSessions((s) => s)
+}
+
 export function registerSlots(ctx: ClientContext): () => void {
   const disposers: (() => void)[] = []
 
-  // Board launcher in the sidebar footer action list (always visible; opens the board).
+  // Board launcher in the sidebar footer action list — OPENS the shared board store (run 08 R1).
   disposers.push(ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
     name: 'sidebar.footer.action',
     id: 'recursive',
     order: 50,
     label: 'Recursive runs',
-  }, () => createElement('button', { className: 'rec-launcher', title: 'Recursive runs' }, '⧉'))))
+  }, () => createElement('button', { className: 'rec-launcher', title: 'Recursive runs', onClick: () => boardState.openBoard() }, '⧉'))))
 
-  // Board panel overlay (root scope, cross-session read) — gated on the recursive preset.
+  // Board panel overlay (root scope, cross-session read) — gated on the recursive preset + shared store.
   disposers.push(ctx.slots.inject('shell.overlay', () => ctx.slots.register({
     name: 'shell.overlay',
     id: 'recursive-board',
@@ -53,7 +77,7 @@ export function registerSlots(ctx: ClientContext): () => void {
   }, (props: RootSlotProps) => {
     const useSessions = props?.useSessions
     if (useSessions === undefined) return null
-    return createElement(RecursiveBoardGate, { useSessions })
+    return createElement(RecursiveBoardOverlay, { useSessions })
   })))
 
   // Status strip in the composer input dock (session scope) — gated the same way.
@@ -79,29 +103,39 @@ export function registerSlots(ctx: ClientContext): () => void {
 }
 
 /**
- * Board gate: renders the board ONLY when the current session is on the
- * recursive preset. The gate itself reads the live sessions snapshot via the
- * standard useSessions hook and re-renders on change.
+ * Board overlay: subscribes to the shared board store, gates on open + recursive
+ * preset, and swaps board <-> inspector (run 08 R1/R3).
+ *
+ * Run 10: consumes the full SessionListStateLike through the identity selector
+ * (useSessions((s) => s)); no fake {list:{getSnapshot}} wrapper.
  */
-function RecursiveBoardGate({ useSessions }: { useSessions: () => SessionListStateLike }): ReactNode {
-  const list = useSessions()
-  const sessions: ISessionsLike = { list: { getSnapshot: () => list, subscribe: () => () => {} } as SnapshotStoreLike<SessionListStateLike> }
-  if (!isRecursivePreset(sessions)) return null
-  const cwd = currentSessionCwd(sessions)
+function RecursiveBoardOverlay({ useSessions }: { useSessions: SnapshotSelectorHook<SessionListStateLike> }): ReactNode {
+  const board = useBoardState()
+  const list = useRecursiveSessions(useSessions)
+  const content = overlayContent(board, list)
+  if (content === 'hidden') return null
+  const cwd = currentSessionCwd(list)
   const scope = { sessionId: list.current, cwd }
   const snapshot = useLiveProjection(scope)
-  return createElement(Board, { snapshot })
+  if (content === 'inspector' && board.selection !== null) {
+    return createElement(Inspector, {
+      runId: board.selection.runId,
+      worktreeRoot: board.selection.worktreeRoot,
+      snapshot,
+      onBackToToolDetails: () => boardState.backToBoard(),
+    })
+  }
+  return createElement(Board, { snapshot, onOpenInspector: (sel) => boardState.openInspector(sel) })
 }
 
 /**
  * Strip gate: same preset gate, session-scoped sessionId; the strip renders
- * nothing for a non-recursive session.
+ * nothing for a non-recursive session. Run 10: useSessions((s) => s) selector.
  */
-function RecursiveStripGate({ useSessions, sessionId }: { useSessions: () => SessionListStateLike; sessionId?: string }): ReactNode {
-  const list = useSessions()
-  const sessions: ISessionsLike = { list: { getSnapshot: () => list, subscribe: () => () => {} } as SnapshotStoreLike<SessionListStateLike> }
-  if (!isRecursivePreset(sessions)) return null
-  const cwd = currentSessionCwd(sessions)
+function RecursiveStripGate({ useSessions, sessionId }: { useSessions: SnapshotSelectorHook<SessionListStateLike>; sessionId?: string }): ReactNode {
+  const list = useRecursiveSessions(useSessions)
+  if (!isRecursivePreset(list)) return null
+  const cwd = currentSessionCwd(list)
   const scope = { sessionId, cwd }
   const snapshot = useLiveProjection(scope)
   return createElement(StatusStrip, { snapshot })

package/src/commands.ts

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import type { RecursiveRuntime } from './runtime.ts'
 import { resolveControlPlaneRoot } from './workspace.ts'
+import { bootstrapScaffold } from './bootstrap.ts'
 
 export type RecursiveVerb = 'status' | 'spec' | 'worktree' | 'init' | 'lock' | 'qa' | 'closeout' | 'addendum' | 'review' | 'scratch' | 'bootstrap' | 'list' | 'help'
 
@@ -65,6 +66,16 @@ export function executeRecursiveCommand(root: string, rawInput: string): Recursi
     case 'help': {
       return { kind: 'success', text: HELP_TEXT + ' — see /.recursive/RECURSIVE.md' }
     }
+    case 'bootstrap': {
+      // R6 (run 09): manual repair path — idempotent upsert scaffold repair.
+      // Adds missing control-plane files/dirs + re-upserts marked blocks;
+      // never overwrites user content or touches run/ artifacts.
+      const result = bootstrapScaffold(root)
+      const summary = result.created.length === 0
+        ? 'scaffold already complete (no changes)'
+        : 'created ' + result.created.length + ' item(s), ' + result.existing.length + ' existing'
+      return { kind: 'success', text: 'recursive-mode scaffold repair: ' + summary + ' — root ' + root }
+    }
     case 'closeout': {
       const phaseMatch = arg.match(/--phase\s+(\d{2})/)
       const phase = phaseMatch?.[1] ?? ''