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

package/lib/bootstrap.d.ts

@@ -35,8 +35,11 @@ export interface StageBInput {
 }
 /**
  * Stage B workflow init at agent/session-start. New: bootstrap if missing +
- * enumerate runs. Resume: never re-bootstrap; enumerate + note the active run
- * (the caller re-reads only that run's current phase doc). Always scoped to
- * the given control-plane root.
+ * enumerate runs. Resume: idempotent REPAIR (not a full re-bootstrap) — the
+ * upsert-only bootstrapScaffold adds missing control-plane files/dirs and
+ * re-upserts marked blocks WITHOUT overwriting user content or touching run/
+ * artifacts, then enumerates + notes the active run. The repair is safe on
+ * fresh, partial, AND complete scaffolds (run 09 R3/R6). Always scoped to the
+ * given control-plane root.
  */
 export declare function stageBWorkflowInit(input: StageBInput): StageBResult;

package/lib/client/board.d.ts

@@ -1,11 +1,14 @@
 import type { RecursiveProjection, RecursiveRunCard } from '../types.ts';
 import type { LiveProjectionValue } from './contract.ts';
+import type { BoardSelection } from './open-state.ts';
 /** Flatten the worktree-grouped projection into a stable run list. */
 export declare function listRuns(projection: RecursiveProjection | undefined): RecursiveRunCard[];
 export interface BoardProps {
     /** The live host-route snapshot (null = not loaded / no recursive root). */
     snapshot: LiveProjectionValue | null;
+    /** Opens the drill-down inspector for a run (R3). */
+    onOpenInspector?: (selection: BoardSelection) => void;
 }
-export declare function Board({ snapshot }: BoardProps): import("react").DetailedReactHTMLElement<{
+export declare function Board({ snapshot, onOpenInspector }: BoardProps): import("react").DetailedReactHTMLElement<{
     className: string;
 }, HTMLElement> | null;

package/lib/client/contract.d.ts

@@ -29,21 +29,24 @@ export interface SessionSummaryRow {
     /** Agent preset this session was composed from; absent when the deployment has none. */
     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 {
     inject(seat: string, factory: (ctx: unknown) => () => void): () => void;
@@ -77,8 +80,8 @@ 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 declare function isRecursivePreset(sessions: ISessionsLike): boolean;
+export declare function isRecursivePreset(state: SessionListStateLike): boolean;
 /** The current session's cwd (the client passes it as a fallback hint; the host resolves the root). */
-export declare function currentSessionCwd(sessions: ISessionsLike): string;
+export declare function currentSessionCwd(state: SessionListStateLike): string;

package/lib/client/index.d.ts

@@ -21,7 +21,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 declare const inject: string[];
 /** Browser-half plugin entry (R4 + SP2 R1). */

package/lib/client/open-state.d.ts

@@ -0,0 +1,20 @@
+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 declare function createBoardState(initial?: BoardState): BoardOpenState;
+/** App-wide singleton shared by the launcher, overlay, board, and inspector. */
+export declare const boardState: BoardOpenState;
+export declare function useBoardState(store?: BoardOpenState): BoardState;

package/lib/client/slots.d.ts

@@ -1,5 +1,17 @@
-import type { ClientContext } from './contract.ts';
+import type { ClientContext, SessionListStateLike, SnapshotSelectorHook } from './contract.ts';
 import { isRecursivePreset, currentSessionCwd } from './contract.ts';
+export type OverlayContent = 'hidden' | 'board' | 'inspector';
+/** Gate: hidden unless open AND recursive preset; inspector when a run is selected. */
+export declare function overlayContent(state: {
+    open: boolean;
+    selection: unknown;
+}, sessions: SessionListStateLike): OverlayContent;
+/**
+ * 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 declare function useRecursiveSessions(useSessions: SnapshotSelectorHook<SessionListStateLike>): SessionListStateLike;
 export declare function registerSlots(ctx: ClientContext): () => void;
 /** Export the gate helpers for tests. */
 export { isRecursivePreset, currentSessionCwd };

package/lib/client.js

@@ -10,20 +10,15 @@ window.__ModuleLoader__.load({
 		* 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).
 		*/
-		function isRecursivePreset(sessions) {
-			const snapshot = sessions.list.getSnapshot();
-			const current = snapshot.current;
-			if (current === void 0) return false;
-			return snapshot.byId[current]?.agentPreset === "recursive";
+		function isRecursivePreset(state) {
+			if (state.current === void 0) 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). */
-		function currentSessionCwd(sessions) {
-			const snapshot = sessions.list.getSnapshot();
-			const current = snapshot.current;
-			if (current === void 0) return "";
-			return snapshot.byId[current]?.cwd ?? "";
+		function currentSessionCwd(state) {
+			return state.current === void 0 ? "" : state.byId[state.current]?.cwd ?? "";
 		}
 		//#endregion
 		//#region src/client/derive.ts
@@ -224,13 +219,17 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region src/client/board.tsx
 		/**
-		* Board overlay (SP2 R1): the kanban view over the live host-route projection.
-		* Pure read-only renderer — no filesystem, no run-file scraping. Cards are
-		* grouped by worktree root (the projection's outer key) and mapped to their
-		* current-phase lane via derive.columnForRun. Renders NOTHING when the snapshot
-		* is null (no recursive root / not loaded) or the current session is not on the
-		* recursive preset (the gate lives in slots.ts — here an empty projection with
-		* a null root is a no-op, not an "empty board").
+		* Board overlay (SP2 R1 + run 08 R3): the kanban view over the live host-route
+		* projection. Pure read-only renderer — no filesystem, no run-file scraping.
+		* Cards are grouped by worktree root (the projection's outer key) and mapped to
+		* their current-phase lane via derive.columnForRun. Renders NOTHING when the
+		* snapshot is null (no recursive root / not loaded) or the current session is
+		* not on the recursive preset (the gate lives in slots.ts — here an empty
+		* projection with a null root is a no-op, not an "empty board").
+		*
+		* Run 08 R3: a card click opens the drill-down inspector via onOpenInspector
+		* (the overlay swaps board <-> inspector in slots.ts). Read-only still: the
+		* callback only selects a run for display; no mutation.
 		*/
 		/** Flatten the worktree-grouped projection into a stable run list. */
 		function listRuns(projection) {
@@ -239,13 +238,17 @@ window.__ModuleLoader__.load({
 			for (const worktreeRoot of Object.keys(projection)) for (const runId of Object.keys(projection[worktreeRoot])) runs.push(projection[worktreeRoot][runId]);
 			return runs;
 		}
-		function Board({ snapshot }) {
+		function Board({ snapshot, onOpenInspector }) {
 			if (snapshot === null || snapshot.root === null) return null;
 			const runs = listRuns(snapshot.projection);
 			if (runs.length === 0) return (0, react.createElement)("div", {
 				className: "rec-board",
 				"data-empty": true
 			}, (0, react.createElement)("p", { className: "rec-board-empty" }, "No recursive runs in this workspace yet."));
+			const open = (run) => () => onOpenInspector?.({
+				worktreeRoot: run.worktreeRoot,
+				runId: run.runId
+			});
 			return (0, react.createElement)("div", { className: "rec-board" }, KANBAN_LANES.map((lane) => {
 				const laneRuns = runs.filter((r) => columnForRun(r) === lane.id);
 				return (0, react.createElement)("section", {
@@ -255,7 +258,8 @@ window.__ModuleLoader__.load({
 					const facts = cardFacts(run);
 					return (0, react.createElement)("article", {
 						key: run.worktreeRoot + "\0" + run.runId,
-						className: "rec-card"
+						className: "rec-card",
+						onClick: open(run)
 					}, (0, react.createElement)("div", { className: "rec-card-head" }, (0, react.createElement)("strong", {}, run.runId), facts.tampered && (0, react.createElement)("span", {
 						className: "rec-badge rec-badge-tamper",
 						title: "tampered"
@@ -267,6 +271,26 @@ window.__ModuleLoader__.load({
 			}));
 		}
 		//#endregion
+		//#region src/client/inspector.tsx
+		/**
+		* Drill-down inspector (SP2 R1): the details-seat swap rendering one run's
+		* phase chain (with the always-shown 3.5 row + full 6/7/8 rows), lock badges,
+		* and tamper/gate facts — all from the live host-route snapshot, never disk.
+		*/
+		function Inspector({ runId, worktreeRoot, snapshot, onBackToToolDetails }) {
+			const card = snapshot?.projection?.[worktreeRoot]?.[runId];
+			if (card === void 0) return (0, react.createElement)("div", { className: "rec-inspector" }, (0, react.createElement)("p", {}, "Run not found: " + runId));
+			const facts = cardFacts(card);
+			const rows = expandPhaseRows(card);
+			return (0, react.createElement)("div", { className: "rec-inspector" }, (0, react.createElement)("div", { className: "rec-inspector-head" }, (0, react.createElement)("button", {
+				onClick: onBackToToolDetails,
+				className: "rec-back"
+			}, "← back to tool details"), (0, react.createElement)("h2", {}, runId), (0, react.createElement)("span", { className: "rec-badge" }, facts.state), facts.tampered && (0, react.createElement)("span", { className: "rec-badge rec-badge-tamper" }, "tampered")), (0, react.createElement)("section", { className: "rec-inspector-section" }, (0, react.createElement)("h3", {}, "Phases"), rows.map((row) => (0, react.createElement)("div", {
+				key: row.phase,
+				className: "rec-phase-row"
+			}, (0, react.createElement)("span", { className: "rec-phase-id" }, row.phase), (0, react.createElement)("span", { className: "rec-phase-name" }, row.fileName ?? "—"), (0, react.createElement)("span", { className: "rec-badge" }, row.status), row.lockHash !== void 0 && (0, react.createElement)("code", { className: "rec-lockhash" }, "#" + row.lockHash.slice(0, 8))))), facts.gateBlocked && (0, react.createElement)("section", { className: "rec-inspector-section" }, (0, react.createElement)("h3", {}, "Gate"), (0, react.createElement)("p", {}, "Blocked (" + (facts.gateKind ?? "") + ")")));
+		}
+		//#endregion
 		//#region src/client/strip.tsx
 		/**
 		* Status strip (SP2 R1): a thin glance at the active run's phase, gate state,
@@ -409,22 +433,101 @@ window.__ModuleLoader__.load({
 			return state;
 		}
 		//#endregion
+		//#region src/client/open-state.ts
+		/**
+		* 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).
+		*/
+		function createBoardState(initial = {
+			open: false,
+			selection: null
+		}) {
+			let state = initial;
+			const listeners = /* @__PURE__ */ new Set();
+			const emit = () => {
+				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. */
+		const boardState = createBoardState();
+		function useBoardState(store = boardState) {
+			return (0, react.useSyncExternalStore)(store.subscribe, store.get, store.get);
+		}
+		//#endregion
 		//#region src/client/slots.ts
 		/**
-		* 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.
 		*/
+		/** Gate: hidden unless open AND recursive preset; inspector when a run is selected. */
+		function overlayContent(state, sessions) {
+			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.
+		*/
+		function useRecursiveSessions(useSessions) {
+			return useSessions((s) => s);
+		}
 		function registerSlots(ctx) {
 			const disposers = [];
 			disposers.push(ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
@@ -434,7 +537,8 @@ window.__ModuleLoader__.load({
 				label: "Recursive runs"
 			}, () => (0, react.createElement)("button", {
 				className: "rec-launcher",
-				title: "Recursive runs"
+				title: "Recursive runs",
+				onClick: () => boardState.openBoard()
 			}, "⧉"))));
 			disposers.push(ctx.slots.inject("shell.overlay", () => ctx.slots.register({
 				name: "shell.overlay",
@@ -443,7 +547,7 @@ window.__ModuleLoader__.load({
 			}, (props) => {
 				const useSessions = props?.useSessions;
 				if (useSessions === void 0) return null;
-				return (0, react.createElement)(RecursiveBoardGate, { useSessions });
+				return (0, react.createElement)(RecursiveBoardOverlay, { useSessions });
 			})));
 			disposers.push(ctx.slots.inject("conversation.input.dock", () => ctx.slots.register({
 				name: "conversation.input.dock",
@@ -468,38 +572,43 @@ window.__ModuleLoader__.load({
 			};
 		}
 		/**
-		* 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 }) {
-			const list = useSessions();
-			const sessions = { list: {
-				getSnapshot: () => list,
-				subscribe: () => () => {}
-			} };
-			if (!isRecursivePreset(sessions)) return null;
-			const cwd = currentSessionCwd(sessions);
+		function RecursiveBoardOverlay({ useSessions }) {
+			const board = useBoardState();
+			const list = useRecursiveSessions(useSessions);
+			const content = overlayContent(board, list);
+			if (content === "hidden") return null;
+			const cwd = currentSessionCwd(list);
 			const snapshot = useLiveProjection({
 				sessionId: list.current,
 				cwd
 			});
-			return (0, react.createElement)(Board, { snapshot });
+			if (content === "inspector" && board.selection !== null) return (0, react.createElement)(Inspector, {
+				runId: board.selection.runId,
+				worktreeRoot: board.selection.worktreeRoot,
+				snapshot,
+				onBackToToolDetails: () => boardState.backToBoard()
+			});
+			return (0, react.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 }) {
-			const list = useSessions();
-			const sessions = { list: {
-				getSnapshot: () => list,
-				subscribe: () => () => {}
-			} };
-			if (!isRecursivePreset(sessions)) return null;
+			const list = useRecursiveSessions(useSessions);
+			if (!isRecursivePreset(list)) return null;
 			const snapshot = useLiveProjection({
 				sessionId,
-				cwd: currentSessionCwd(sessions)
+				cwd: currentSessionCwd(list)
 			});
 			return (0, react.createElement)(StatusStrip, { snapshot });
 		}
@@ -516,26 +625,6 @@ window.__ModuleLoader__.load({
 			globalThis.__dshRecursiveModeClientApplied = void 0;
 		}
 		//#endregion
-		//#region src/client/inspector.tsx
-		/**
-		* Drill-down inspector (SP2 R1): the details-seat swap rendering one run's
-		* phase chain (with the always-shown 3.5 row + full 6/7/8 rows), lock badges,
-		* and tamper/gate facts — all from the live host-route snapshot, never disk.
-		*/
-		function Inspector({ runId, worktreeRoot, snapshot, onBackToToolDetails }) {
-			const card = snapshot?.projection?.[worktreeRoot]?.[runId];
-			if (card === void 0) return (0, react.createElement)("div", { className: "rec-inspector" }, (0, react.createElement)("p", {}, "Run not found: " + runId));
-			const facts = cardFacts(card);
-			const rows = expandPhaseRows(card);
-			return (0, react.createElement)("div", { className: "rec-inspector" }, (0, react.createElement)("div", { className: "rec-inspector-head" }, (0, react.createElement)("button", {
-				onClick: onBackToToolDetails,
-				className: "rec-back"
-			}, "← back to tool details"), (0, react.createElement)("h2", {}, runId), (0, react.createElement)("span", { className: "rec-badge" }, facts.state), facts.tampered && (0, react.createElement)("span", { className: "rec-badge rec-badge-tamper" }, "tampered")), (0, react.createElement)("section", { className: "rec-inspector-section" }, (0, react.createElement)("h3", {}, "Phases"), rows.map((row) => (0, react.createElement)("div", {
-				key: row.phase,
-				className: "rec-phase-row"
-			}, (0, react.createElement)("span", { className: "rec-phase-id" }, row.phase), (0, react.createElement)("span", { className: "rec-phase-name" }, row.fileName ?? "—"), (0, react.createElement)("span", { className: "rec-badge" }, row.status), row.lockHash !== void 0 && (0, react.createElement)("code", { className: "rec-lockhash" }, "#" + row.lockHash.slice(0, 8))))), facts.gateBlocked && (0, react.createElement)("section", { className: "rec-inspector-section" }, (0, react.createElement)("h3", {}, "Gate"), (0, react.createElement)("p", {}, "Blocked (" + (facts.gateKind ?? "") + ")")));
-		}
-		//#endregion
 		//#region src/client/index.ts
 		/** Required services (fiber inject waiting — the runtime must be up first). */
 		const inject = [