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

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/slots.d.ts

@@ -1,11 +1,46 @@
-import type { ClientContext, ISessionsLike } from './contract.ts';
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 { type ReactNode } from 'react';
+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: ISessionsLike): OverlayContent;
+}, 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;
+/**
+ * Run 11 (UX gate): the ⧉ launcher renders ONLY in recursive sessions. The seat
+ * is root-scoped (the icon shows in every session otherwise), while the board it
+ * opens is recursive-preset-gated — in a code/other session the click was a dead
+ * no-op. Gating the launcher itself removes the trap: the icon appears exactly
+ * where clicking it opens the board.
+ */
+export declare function RecursiveLauncherGate({ useSessions }: {
+    useSessions: SnapshotSelectorHook<SessionListStateLike>;
+}): ReactNode;
 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
@@ -507,11 +502,14 @@ window.__ModuleLoader__.load({
 		*
 		* 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.
+		* preset, swapping to the drill-down inspector when a run is selected.
+		*
+		* 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.
 		*/
@@ -522,6 +520,29 @@ window.__ModuleLoader__.load({
 			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);
+		}
+		/**
+		* Run 11 (UX gate): the ⧉ launcher renders ONLY in recursive sessions. The seat
+		* is root-scoped (the icon shows in every session otherwise), while the board it
+		* opens is recursive-preset-gated — in a code/other session the click was a dead
+		* no-op. Gating the launcher itself removes the trap: the icon appears exactly
+		* where clicking it opens the board.
+		*/
+		function RecursiveLauncherGate({ useSessions }) {
+			if (!isRecursivePreset(useRecursiveSessions(useSessions))) return null;
+			return (0, react.createElement)("button", {
+				className: "rec-launcher",
+				title: "Recursive runs",
+				onClick: () => boardState.openBoard()
+			}, "⧉");
+		}
 		function registerSlots(ctx) {
 			const disposers = [];
 			disposers.push(ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
@@ -529,11 +550,11 @@ window.__ModuleLoader__.load({
 				id: "recursive",
 				order: 50,
 				label: "Recursive runs"
-			}, () => (0, react.createElement)("button", {
-				className: "rec-launcher",
-				title: "Recursive runs",
-				onClick: () => boardState.openBoard()
-			}, "⧉"))));
+			}, (props) => {
+				const useSessions = props?.useSessions;
+				if (useSessions === void 0) return null;
+				return (0, react.createElement)(RecursiveLauncherGate, { useSessions });
+			})));
 			disposers.push(ctx.slots.inject("shell.overlay", () => ctx.slots.register({
 				name: "shell.overlay",
 				id: "recursive-board",
@@ -568,17 +589,16 @@ window.__ModuleLoader__.load({
 		/**
 		* 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 RecursiveBoardOverlay({ useSessions }) {
 			const board = useBoardState();
-			const list = useSessions();
-			const sessions = { list: {
-				getSnapshot: () => list,
-				subscribe: () => () => {}
-			} };
-			const content = overlayContent(board, sessions);
+			const list = useRecursiveSessions(useSessions);
+			const content = overlayContent(board, list);
 			if (content === "hidden") return null;
-			const cwd = currentSessionCwd(sessions);
+			const cwd = currentSessionCwd(list);
 			const snapshot = useLiveProjection({
 				sessionId: list.current,
 				cwd
@@ -596,18 +616,14 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* 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 });
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + recursive_status tool",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

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/slots.ts

@@ -5,16 +5,19 @@
  *
  * 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.
+ * preset, swapping to the drill-down inspector when a run is selected.
+ *
+ * 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'
@@ -23,39 +26,68 @@ 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: ISessionsLike): OverlayContent {
+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)
+}
+
+/**
+ * Run 11 (UX gate): the ⧉ launcher renders ONLY in recursive sessions. The seat
+ * is root-scoped (the icon shows in every session otherwise), while the board it
+ * opens is recursive-preset-gated — in a code/other session the click was a dead
+ * no-op. Gating the launcher itself removes the trap: the icon appears exactly
+ * where clicking it opens the board.
+ */
+export function RecursiveLauncherGate({ useSessions }: { useSessions: SnapshotSelectorHook<SessionListStateLike> }): ReactNode {
+  const list = useRecursiveSessions(useSessions)
+  if (!isRecursivePreset(list)) return null
+  return createElement('button', { className: 'rec-launcher', title: 'Recursive runs', onClick: () => boardState.openBoard() }, '⧉')
+}
+
 export function registerSlots(ctx: ClientContext): () => void {
   const disposers: (() => void)[] = []
 
   // Board launcher in the sidebar footer action list — OPENS the shared board store (run 08 R1).
+  // Run 11 (UX gate): the seat is root-scoped (visible in every session), but the board it
+  // opens is recursive-preset-gated. In a code/other session the icon was a dead click — a
+  // trap. The launcher itself now renders ONLY in recursive sessions, where it works.
   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', onClick: () => boardState.openBoard() }, '⧉'))))
+  }, (props: RootSlotProps) => {
+    const useSessions = props?.useSessions
+    if (useSessions === undefined) return null
+    return createElement(RecursiveLauncherGate, { useSessions })
+  })))
 
   // 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({
@@ -93,14 +125,16 @@ export function registerSlots(ctx: ClientContext): () => void {
 /**
  * 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 RecursiveBoardOverlay({ useSessions }: { useSessions: () => SessionListStateLike }): ReactNode {
+function RecursiveBoardOverlay({ useSessions }: { useSessions: SnapshotSelectorHook<SessionListStateLike> }): ReactNode {
   const board = useBoardState()
-  const list = useSessions()
-  const sessions: ISessionsLike = { list: { getSnapshot: () => list, subscribe: () => () => {} } as SnapshotStoreLike<SessionListStateLike> }
-  const content = overlayContent(board, sessions)
+  const list = useRecursiveSessions(useSessions)
+  const content = overlayContent(board, list)
   if (content === 'hidden') return null
-  const cwd = currentSessionCwd(sessions)
+  const cwd = currentSessionCwd(list)
   const scope = { sessionId: list.current, cwd }
   const snapshot = useLiveProjection(scope)
   if (content === 'inspector' && board.selection !== null) {
@@ -116,13 +150,12 @@ function RecursiveBoardOverlay({ useSessions }: { useSessions: () => SessionList
 
 /**
  * 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 })