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

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/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,11 @@
-import type { ClientContext } from './contract.ts';
+import type { ClientContext, ISessionsLike } 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: ISessionsLike): OverlayContent;
 export declare function registerSlots(ctx: ClientContext): () => void;
 /** Export the gate helpers for tests. */
 export { isRecursivePreset, currentSessionCwd };

package/lib/client.js

@@ -224,13 +224,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 +243,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 +263,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 +276,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 +438,90 @@ 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.
-		*
-		* 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).
+		* 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 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 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). The strip reads its sessionId from the session-scope
+		* standard prop.
 		*
 		* 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";
+		}
 		function registerSlots(ctx) {
 			const disposers = [];
 			disposers.push(ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
@@ -434,7 +531,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 +541,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,23 +566,33 @@ 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).
 		*/
-		function RecursiveBoardGate({ useSessions }) {
+		function RecursiveBoardOverlay({ useSessions }) {
+			const board = useBoardState();
 			const list = useSessions();
 			const sessions = { list: {
 				getSnapshot: () => list,
 				subscribe: () => () => {}
 			} };
-			if (!isRecursivePreset(sessions)) return null;
+			const content = overlayContent(board, sessions);
+			if (content === "hidden") return null;
 			const cwd = currentSessionCwd(sessions);
 			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
@@ -516,26 +624,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 = [

package/lib/fs-intent.d.ts

@@ -0,0 +1,34 @@
+import type { WorkspaceRegistryLike } from './workspace.ts';
+export interface FsPolicyIntent {
+    worktreeRoot: string;
+    runId: string;
+    /** The current phase doc file name (e.g. 03-implementation-summary.md), when determinable. */
+    currentPhaseFile: string | null;
+}
+/**
+ * Resolve the recursive policy intent for one agent from the FILESYSTEM.
+ * Returns null when no control-plane root or run is present (callers defer,
+ * never fail hard). The registry path is async-only in the harness, so when a
+ * registry is present this resolves the session cwd directly (B4: the session
+ * cwd IS the workspace root when unregistered; a registered workspace resolves
+ * to the same cwd via resolveControlPlaneRoot's sync fallback).
+ */
+export declare function fsPolicyIntent(agent: {
+    session?: {
+        header?: {
+            cwd?: string;
+        };
+    };
+} | null | undefined, registry?: WorkspaceRegistryLike | null, cwdFallback?: string): FsPolicyIntent | null;
+/**
+ * Async variant for callers that CAN await (pre-step listener, routes): uses
+ * resolveControlPlaneRoot for registry canonicalization when a registry is
+ * present, falling back to the session cwd (B4).
+ */
+export declare function fsPolicyIntentAsync(agent: {
+    session?: {
+        header?: {
+            cwd?: string;
+        };
+    };
+} | null | undefined, registry?: WorkspaceRegistryLike | null, cwdFallback?: string): Promise<FsPolicyIntent | null>;

package/lib/index.d.ts

@@ -37,4 +37,5 @@ export declare const inject: string[];
  */
 export declare function apply(ctx: Context, config?: {
     shellOnly?: boolean;
+    repoRoot?: string;
 }): void;