@try-works/dsh-recursive-mode 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# 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).
+
+- insert:
+    - id: recursive-realm
+      name: cordis:group
+      isolate:
+        recursive: true
+      config:
+        - id: recursive
+          name: @try-works/dsh-recursive-mode/src/index.ts

package/lib/bootstrap.d.ts

@@ -0,0 +1,35 @@
+export interface BootstrapResult {
+    root: string;
+    bootstrapped: boolean;
+    created: string[];
+    existing: string[];
+}
+export interface StageBResult {
+    root: string;
+    source: 'new' | 'resume';
+    bootstrapped: boolean;
+    runs: string[];
+    activeRunId?: string;
+}
+/**
+ * Idempotent scaffold install: creates the /.recursive/ control plane when
+ * missing. Never overwrites existing files; preserves unrelated content.
+ */
+export declare function bootstrapScaffold(root: string): BootstrapResult;
+/**
+ * Enumerate runs as directory names only (bounded O(#dirs)). Never reads
+ * run docs; never returns file paths.
+ */
+export declare function enumerateRuns(root: string): string[];
+export interface StageBInput {
+    root: string;
+    source: 'new' | 'resume';
+    activeRunId?: string;
+}
+/**
+ * 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.
+ */
+export declare function stageBWorkflowInit(input: StageBInput): StageBResult;

package/lib/client/board.d.ts

@@ -0,0 +1,10 @@
+import type { RecursiveProjection, RecursiveRunCard } from '../types.ts';
+import type { RecursiveProjectionReader } 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;
+}
+export declare function Board({ useProjection }: BoardProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;

package/lib/client/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ *
+ * One deliberate narrowing: the client only READS (R9 read-only). It never
+ * calls back into the host; every host fact arrives through the projection.
+ */
+/** SessionEvent-like carrier (the projection/node fold reads events by shape). */
+export interface ClientSessionEvent {
+    type: string;
+    seq?: number;
+    time?: number;
+    data?: Record<string, unknown>;
+}
+/** A session header (cwd is the control-plane root). */
+export interface ClientSessionHeader {
+    cwd?: string;
+}
+/** Minimal appendable session (log-only write seam). */
+export interface ClientSession {
+    header: ClientSessionHeader;
+    append(type: string, data: unknown): unknown;
+}
+/** The client root context the bundle receives from the module loader. */
+export interface ClientContext {
+    slots: ClientSlots;
+    get(name: string): unknown;
+}
+/** A registered slot's options (list/keyed entries carry id/order/label). */
+export interface SlotOptions {
+    name: string;
+    id?: string;
+    order?: number;
+    label?: string;
+    children?: unknown;
+    store?: unknown;
+    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;
+}
+/** useProjection('recursive') reader — undefined = capability absent. */
+export type RecursiveProjectionReader = (key: 'recursive') => unknown;

package/lib/client/derive.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Pure derivation over the projected RecursiveRunCard (Phase D R5/R6/R7):
+ * kanban lane mapping, card facts, conversation-node keying, and inspector
+ * phase-row expansion. EVERYTHING here is a pure function over the wire card
+ * — no React, no fs, no session window, no /.recursive/run/ scraping (the
+ * read-only-client + projection-over-files invariant, 00-requirements R9).
+ *
+ * The card arrives from the 'recursive' session projection (whole value,
+ * host-computed); this module only derives presentation from it.
+ */
+import type { RecursiveRunCard, RecursiveRunState } from '../types.ts';
+/** The ordered kanban lanes (§11.4): one lane per phase group. */
+export interface RecursiveLane {
+    /** Stable lane id. */
+    id: string;
+    /** Human label. */
+    label: string;
+    /** Phase-group keys folded into this lane. */
+    groups: readonly string[];
+}
+export declare const KANBAN_LANES: readonly RecursiveLane[];
+/** Group id for a phase filename (e.g. '03.5-code-review.md' -> '03.5'); null for non-phase names. */
+export declare function phaseGroupOf(phase: string): string | null;
+/** Kanban lane id for a phase filename. */
+export declare function laneOf(phase: string): string | null;
+/**
+ * The run's current-phase lane: the highest-ordered phase group present in the
+ * card wins (a run is "at" its furthest phase). No phases -> lane 0.
+ */
+export declare function columnForRun(card: RecursiveRunCard): string;
+/** Subagent chip (one per childId, latest status). */
+export interface RecursiveSubagentChip {
+    childId: string;
+    role: string;
+    provider: string;
+    status: 'running' | 'done' | 'failed';
+}
+/** Presentation facts derived from one card (§11.4). */
+export interface RecursiveCardFacts {
+    runId: string;
+    worktreeRoot: string;
+    repo?: string;
+    template?: string;
+    state: RecursiveRunState;
+    stateReason?: string;
+    /** Phases locked so far. */
+    lockedCount: number;
+    /** Distinct phase groups present (progress denominator). */
+    totalPhases: number;
+    /** lockedCount / totalPhases (0 when totalPhases is 0). */
+    progress: number;
+    /** Any tamper fact present. */
+    tampered: boolean;
+    /** Latest gate block present. */
+    gateBlocked: boolean;
+    gateKind?: string;
+    /** Run was merged to a repo root. */
+    merged: boolean;
+    mergedToRepoRoot?: string;
+    /** Lock validity: tampered | locked | in-progress. */
+    lockValidity: 'tampered' | 'locked' | 'in-progress';
+    /** Latest current-phase label (or null). */
+    currentPhase: string | null;
+    /** Subagent chips, latest status per child. */
+    subagents: RecursiveSubagentChip[];
+}
+/** Derive §11.4 presentation facts from one card (no fs, no session). */
+export declare function cardFacts(card: RecursiveRunCard): RecursiveCardFacts;
+/**
+ * Stable conversation-node business id: runId + worktreeRoot (§11.6). The
+ * worktree root is part of the id so two runs with the same runId in
+ * different worktrees never collide — never "latest unfinished".
+ */
+export declare function nodeKeyOf(runId: string, worktreeRoot: string): string;
+/** One expanded inspector phase row (§11.5). */
+export interface RecursivePhaseInspectorRow {
+    /** Normalized phase key (group only, e.g. '03.5'). */
+    phase: string;
+    /** Full filename if present, else null (a mandatory-empty row). */
+    fileName: string | null;
+    status: string;
+    lockedAt?: string;
+    lockHash?: string;
+    /** Whether the row is present in the card (vs a mandatory-empty slot). */
+    present: boolean;
+}
+/**
+ * Expand a card's phase chain into full inspector rows: the always-shown
+ * '03.5' slot (§11.10 mandatory deviation) plus 01.5 when present, and
+ * 06/07/08 as three distinct rows (never one merged lane).
+ */
+export declare function expandPhaseRows(card: RecursiveRunCard): RecursivePhaseInspectorRow[];

package/lib/client/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ *
+ * 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).
+ */
+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 declare function apply(ctx: ClientContext): void;

package/lib/client/inspector.d.ts

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

package/lib/client/node.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Conversation run node (Phase D R7, §11.6): a structural ConversationNodeDefinition
+ * over the recursive/* event family, keyed by runId + worktreeRoot. One compact,
+ * live node per run in the Chat view. PURE fold (no React) — the renderer lives
+ * in slots.ts.
+ *
+ * The real ConversationNodeDefinition contract arrives from
+ * @deepseek-ai/dsh-client-runtime/client at compose time; the structural shape
+ * here is type-compatible with the cookbook surface (match/start/update/
+ * buildViewNode + target/kind). The host links the bundle's exports to the real
+ * runtime identities.
+ */
+import type { ClientSessionEvent } from './contract.ts';
+export declare const RECURSIVE_NODE_KIND = "recursive/run";
+/** The chat-node payload the renderer receives (pure derived state). */
+export interface RecursiveNodeData {
+    readonly runId: string;
+    readonly worktreeRoot: string;
+    readonly state: string;
+    readonly currentPhase: string | null;
+    readonly lockedCount: number;
+    readonly totalPhases: number;
+    readonly tampered: boolean;
+    readonly gateBlocked: boolean;
+    readonly mergedToRepoRoot?: string;
+}
+/** Pure fold state for one run node. */
+export interface RecursiveNodeState {
+    runId: string;
+    worktreeRoot: string;
+    state: string;
+    phases: Record<string, {
+        phase: string;
+        status: string;
+    }>;
+    tampered: boolean;
+    gateBlocked: boolean;
+    mergedToRepoRoot?: string;
+}
+/** Extract a stable (runId, worktreeRoot) business id + lifecycle role from one event. */
+export declare function matchRecursiveNode(event: ClientSessionEvent): {
+    id: string;
+    role: 'start' | 'update';
+} | null;
+/** Fold one recursive/* event into the node state. */
+export declare function foldRecursiveNode(s: RecursiveNodeState | undefined, event: ClientSessionEvent): RecursiveNodeState;
+/** The structural ConversationNodeDefinition (host links to the real contract). */
+export declare const recursiveNodeDefinition: {
+    kind: string;
+    target: string;
+    match: typeof matchRecursiveNode;
+    start: (_ctx: unknown, match: {
+        event: ClientSessionEvent;
+    }) => RecursiveNodeState;
+    update: (ctx: {
+        state: RecursiveNodeState;
+    }, match: {
+        event: ClientSessionEvent;
+    }) => RecursiveNodeState;
+    buildViewNode: (ctx: {
+        key: string;
+        id: string;
+        state?: RecursiveNodeState;
+    }) => {
+        key: string;
+        kind: string;
+        id: string;
+        target: string;
+        data: RecursiveNodeData;
+    } | null;
+};

package/lib/client/settings.d.ts

@@ -0,0 +1,6 @@
+export interface RecursiveSettingsProps {
+    close: () => void;
+}
+export declare function RecursiveSettings({ close }: RecursiveSettingsProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;

package/lib/client/slots.d.ts

@@ -0,0 +1,7 @@
+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;
+export declare function registerSlots(ctx: ClientContext): () => void;
+/** Export the projection reader narrow for the board/inspector/strip. */
+export { projectionOf };

package/lib/client/strip.d.ts

@@ -0,0 +1,7 @@
+import type { RecursiveProjectionReader } from './contract.ts';
+export interface StripProps {
+    useProjection: RecursiveProjectionReader;
+}
+export declare function StatusStrip({ useProjection }: StripProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement> | null;

package/lib/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the recursive domain (Phase D R3): a pure
+ * re-export of the package's types outlet. Client code imports ONLY the
+ * client namespace (repo discipline), so ./client projects the same
+ * single-source content ./types serves to host consumers — zero duplication
+ * (the goal client.ts pattern).
+ *
+ * @module dsh-recursive-mode/client
+ */
+export type * from './types.ts';