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

package/cordis.patch.yml

@@ -1,12 +1,17 @@
-# dsh-recursive-mode bundle patch: inserts the RecursiveRuntime service realm and the
-# recursive_status tool over the profile root. The cordis:group realm keeps the service
-# out of the root realm (R2: registered exactly once, no collision on double-mount).
-
+# dsh-recursive-mode bundle patch — client-discovery shell (R4, decision 02-to-be-plan.addendum-r4-r2-mount-resolution.md).
+#
+# A single ENABLED bare-name row exists so the host's ClientModuleRegistry can
+# discover this package's client half (dsh.client.inject -> /plugins/<id>/client.js).
+# Client discovery requires an ENABLED bare-name entry (entry.fiber !== undefined &&
+# !entry.disabled); preset-mounted subtrees are absent from ctx.loader.entries().
+#
+# The row's apply() is a NO-OP under config.shellOnly=true (see src/index.ts):
+# it contributes the client bundle and registers NOTHING on the server root —
+# no tools, no /recursive command, no recursive:policy, no projection. The full
+# server surface is mounted ONLY by the `recursive` agent preset's isolated
+# recursive-realm (preset/recursive/agent.cordis.yml).
 - insert:
-    - id: recursive-realm
-      name: cordis:group
-      isolate:
-        recursive: true
+    - id: recursive
+      name: '@try-works/dsh-recursive-mode'
       config:
-        - id: recursive
-          name: '@try-works/dsh-recursive-mode'
+        shellOnly: true

package/lib/bootstrap.d.ts

@@ -1,3 +1,7 @@
+/** Package root: <package>/src/.. — references/ sits next to src/. */
+export declare const PACKAGE_ROOT: string;
+/** references/ root (shipped package files). */
+export declare function referencesRoot(): string;
 export interface BootstrapResult {
     root: string;
     bootstrapped: boolean;
@@ -11,9 +15,12 @@ export interface StageBResult {
     runs: string[];
     activeRunId?: string;
 }
+/** write_utf8_no_bom: LF newlines, no BOM. */
+export declare function writeUtf8NoBom(path: string, content: string): void;
 /**
- * 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 declare function bootstrapScaffold(root: string): BootstrapResult;
 /**

package/lib/client/apply-guard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 {
+    var __dshRecursiveModeClientApplied: boolean | undefined;
+}
+/** Claims the client apply slot. Returns true when this call won the slot. */
+export declare function claimClientApply(): boolean;
+/** Releases the claim (called from the client fiber cleanup on unload/hot-reload). */
+export declare function releaseClientApply(): void;

package/lib/client/board.d.ts

@@ -1,10 +1,11 @@
 import type { RecursiveProjection, RecursiveRunCard } from '../types.ts';
-import type { RecursiveProjectionReader } from './contract.ts';
+import type { LiveProjectionValue } from './contract.ts';
 /** Flatten the worktree-grouped projection into a stable run list. */
 export declare function listRuns(projection: RecursiveProjection | undefined): RecursiveRunCard[];
 export interface BoardProps {
-    useProjection: RecursiveProjectionReader;
+    /** The live host-route snapshot (null = not loaded / no recursive root). */
+    snapshot: LiveProjectionValue | null;
 }
-export declare function Board({ useProjection }: BoardProps): import("react").DetailedReactHTMLElement<{
+export declare function Board({ snapshot }: BoardProps): import("react").DetailedReactHTMLElement<{
     className: string;
-}, HTMLElement>;
+}, HTMLElement> | null;

package/lib/client/contract.d.ts

@@ -1,37 +1,55 @@
 /**
  * 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).
  */
-/** SessionEvent-like carrier (the projection/node fold reads events by shape). */
+import type { RecursiveProjection } from '../types.ts';
+/** SessionEvent-like carrier (kept for the pure derive surface; the live route replaces the fold). */
 export interface ClientSessionEvent {
     type: string;
     seq?: number;
     time?: number;
     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;
@@ -42,10 +60,25 @@ export interface SlotOptions {
     locale?: unknown;
     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;
+}
+/** The live state payload the host route serves (mirrors host-api.ts). */
+export interface LiveProjectionValue {
+    root: string | null;
+    projection: RecursiveProjection;
+    revision: number;
 }
-/** useProjection('recursive') reader — undefined = capability absent. */
-export type RecursiveProjectionReader = (key: 'recursive') => unknown;
+/**
+ * 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 declare function isRecursivePreset(sessions: ISessionsLike): 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;

package/lib/client/host-api.d.ts

@@ -0,0 +1,26 @@
+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;
+}
+/** Fetch the current state for one session scope (host resolves the workspace root). */
+export declare function fetchLiveState(scope: LiveScope, signal?: AbortSignal): Promise<LiveRecursiveState>;
+/**
+ * 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 declare function subscribeLiveEvents(scope: LiveScope, onFrame: (frame: LiveRecursiveFrame) => void, onError?: () => void): () => void;

package/lib/client/index.d.ts

@@ -1,21 +1,28 @@
 /**
- * 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';
-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';
-/** Browser-half plugin entry (R4). */
+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';
+/** Required services (fiber inject waiting — the runtime must be up first). */
+export declare const inject: string[];
+/** Browser-half plugin entry (R4 + SP2 R1). */
 export declare function apply(ctx: ClientContext): void;

package/lib/client/inspector.d.ts

@@ -1,10 +1,10 @@
-import type { RecursiveProjectionReader } from './contract.ts';
+import type { LiveProjectionValue } from './contract.ts';
 export interface InspectorProps {
     runId: string;
     worktreeRoot: string;
-    useProjection: RecursiveProjectionReader;
+    snapshot: LiveProjectionValue | null;
     onBackToToolDetails: () => void;
 }
-export declare function Inspector({ runId, worktreeRoot, useProjection, onBackToToolDetails }: InspectorProps): import("react").DetailedReactHTMLElement<{
+export declare function Inspector({ runId, worktreeRoot, snapshot, onBackToToolDetails }: InspectorProps): import("react").DetailedReactHTMLElement<{
     className: string;
 }, HTMLElement>;

package/lib/client/slots.d.ts

@@ -1,7 +1,5 @@
-import type { ClientContext, RecursiveProjectionReader } from './contract.ts';
-import type { RecursiveProjection } from '../types.ts';
-/** Narrow the projection whole value to the worktree-grouped run map. */
-declare function projectionOf(reader: RecursiveProjectionReader): RecursiveProjection | undefined;
+import type { ClientContext } from './contract.ts';
+import { isRecursivePreset, currentSessionCwd } from './contract.ts';
 export declare function registerSlots(ctx: ClientContext): () => void;
-/** Export the projection reader narrow for the board/inspector/strip. */
-export { projectionOf };
+/** Export the gate helpers for tests. */
+export { isRecursivePreset, currentSessionCwd };

package/lib/client/strip.d.ts

@@ -1,7 +1,8 @@
-import type { RecursiveProjectionReader } from './contract.ts';
+import type { LiveProjectionValue } from './contract.ts';
 export interface StripProps {
-    useProjection: RecursiveProjectionReader;
+    /** The live host-route snapshot (null = not loaded / no recursive root). */
+    snapshot: LiveProjectionValue | null;
 }
-export declare function StatusStrip({ useProjection }: StripProps): import("react").DetailedReactHTMLElement<{
+export declare function StatusStrip({ snapshot }: StripProps): import("react").DetailedReactHTMLElement<{
     className: string;
 }, HTMLElement> | null;

package/lib/client/use-live.d.ts

@@ -0,0 +1,9 @@
+import { type LiveRecursiveState, type LiveScope } from './host-api.ts';
+/** Snapshot shape the board/strip consume (null = not loaded / no recursive root). */
+export type LiveProjectionSnapshot = LiveRecursiveState | null;
+/**
+ * Subscribe to the live route for one scope. Returns the current state. The SSE
+ * feed pushes full frames on every fs change; a dropped stream (sleep/error)
+ * triggers one refetch so the board never serves a stale fold.
+ */
+export declare function useLiveProjection(scope: LiveScope): LiveProjectionSnapshot;