@try-works/dsh-recursive-mode 0.4.3 → 0.4.5

package/src/client/settings-view.ts

@@ -0,0 +1,211 @@
+/**
+ * Pure display model for the Recursive settings panel (read-only report).
+ *
+ * WHY THIS MODULE EXISTS. The old panel rendered one sentence and no values — it
+ * claimed to report the host's configuration while reporting nothing. The data
+ * was already arriving: `host-api.ts` serves {root, projection, revision} on
+ * every fs change plus a 15s heartbeat, and `derive.ts` already derives board
+ * facts from the same projection. This module adds no data path; it is the same
+ * projection read for a different surface, and it is PURE (no React, no fs, no
+ * session window — the read-only-client + projection-over-files invariant, §11.9).
+ *
+ * THE ABSENCE RULE (`text()` + `SettingsRow.value === null`): a value is printed
+ * only when the projection carried it. A missing/blank value renders as
+ * `not reported` — never an empty row and never a plausible default. Note that
+ * `derive.cardFacts()` deliberately defaults a subagent's absent `status` to
+ * 'done'; this model does NOT, because a report that invents "done" is a report
+ * that lies. Required collection fields (`tampers`, `subagents`) that are present
+ * but empty print `none` — that IS their value; fields the card omits print
+ * `not reported`.
+ */
+import type { PhasePosition, RecursiveRunCard } from '../types.ts'
+import type { LiveProjectionValue } from './contract.ts'
+import { listRuns } from './board.tsx'
+import { cardFacts, cardPill, expandPhaseRows, phaseStatusPill, type PillKind } from './derive.ts'
+
+/** A label/value line. `value === null` means the projection carried NO value. */
+export interface SettingsRow {
+  id: string
+  label: string
+  value: string | null
+}
+
+/** One folded phase row, with the T21 single derived position printed verbatim. */
+export interface SettingsPhaseRow {
+  phase: string
+  /** The phase doc filename, or null for a slot this run does not have (03.5). */
+  fileName: string | null
+  /** The raw folded status ('LOCKED' / 'DRAFT' / '—'). */
+  status: string
+  /** T21 single derived position; null when the producer carried none. */
+  position: PhasePosition | null
+  lockedAt: string | null
+  lockHash: string | null
+  present: boolean
+  pill: PillKind
+}
+
+/** One subagent record: role/provider exactly as the host fold recorded them. */
+export interface SettingsSubagentRow {
+  childId: string
+  role: string | null
+  provider: string | null
+  status: string | null
+}
+
+/** One unresolved in-flight work item (T18). */
+export interface SettingsPendingRow {
+  kind: string
+  delegationId: string
+  detail: string
+}
+
+/** One run's report. */
+export interface SettingsRunView {
+  runId: string
+  worktreeRoot: string
+  state: string
+  pill: PillKind
+  /** Scalar facts; a null value means the card did not carry that field. */
+  rows: SettingsRow[]
+  phases: SettingsPhaseRow[]
+  /** null when the card carried no `subagents` key; [] when it carried an empty one. */
+  subagents: SettingsSubagentRow[] | null
+  /** null when the card carried no `pendingWork` key; [] when it carried an empty one. */
+  pendingWork: SettingsPendingRow[] | null
+}
+
+/** Whether the route has answered, and whether it resolved a recursive root. */
+export type SettingsStatus = 'no-frame' | 'no-root' | 'connected'
+
+/** The whole panel model. */
+export interface SettingsView {
+  status: SettingsStatus
+  root: string | null
+  revision: number | null
+  runs: SettingsRunView[]
+  /**
+   * Route-level facts the payload does not carry AT ALL — the panel names them
+   * so a reader is never left to assume the client is hiding them.
+   */
+  notCarried: SettingsRow[]
+}
+
+/**
+ * The `/state` payload is {root, projection, revision} (host-api.ts /
+ * live-route.ts, both typed by LiveProjectionValue). Nothing else rides it, so
+ * anything else is reported as not carried rather than guessed.
+ */
+export const NOT_CARRIED: readonly SettingsRow[] = [
+  { id: 'enforcement', label: 'Enforcement modes (preStep / toolGuards / tamper)', value: null },
+  { id: 'router-defaults', label: 'Router defaults (defaults.subagent) and per-role routes', value: null },
+  { id: 'scratch-format', label: 'Scratch format', value: null },
+]
+
+/** A carried string, or null when the producer carried nothing to print. */
+function text(value: string | undefined | null): string | null {
+  if (value === undefined || value === null) return null
+  return value.trim() === '' ? null : value
+}
+
+/**
+ * Read a field the WIRE may omit even where the type calls it required (an
+ * older or partial producer). The comparison itself has to happen here: with
+ * `strict`, `card.subagents === undefined` is a no-overlap error at the call
+ * site, but a missing field must still read as "not reported", not crash.
+ */
+function carried<T>(value: T | undefined): T | undefined {
+  return value
+}
+
+/** `none` for a present-but-empty map, null for a map the card did not carry. */
+function tamperValue(card: RecursiveRunCard): string | null {
+  const tampers = carried(card.tampers)
+  if (tampers === undefined) return null
+  const facts = Object.values(tampers)
+  if (facts.length === 0) return 'none'
+  return facts.map((f) => (text(f.path) ?? '') + ': ' + (text(f.reason) ?? 'no reason carried')).join(' · ')
+}
+
+/** Scalar facts for one run, in a fixed order. */
+function runRows(card: RecursiveRunCard): SettingsRow[] {
+  const facts = cardFacts(card)
+  const gate = card.gateBlocked
+  return [
+    { id: 'state', label: 'run state', value: text(card.state) },
+    { id: 'state-reason', label: 'state reason', value: text(card.stateReason) },
+    { id: 'lock', label: 'lock position', value: facts.lockValidity },
+    { id: 'locked', label: 'locked phase groups', value: String(facts.lockedCount) + ' of ' + String(facts.totalPhases) + ' present' },
+    { id: 'current-phase', label: 'current phase', value: text(facts.currentPhase) },
+    {
+      id: 'gate',
+      label: 'gate block',
+      value: gate === undefined
+        ? null
+        : (text(gate.kind) ?? 'kind not carried') + ': ' + (gate.failures.length === 0 ? 'no failures listed' : gate.failures.join('; ')),
+    },
+    { id: 'tampers', label: 'tamper facts', value: tamperValue(card) },
+    { id: 'repo', label: 'repo', value: text(card.repo) },
+    { id: 'template', label: 'template', value: text(card.template) },
+    { id: 'merged', label: 'merged to repo root', value: text(card.mergedToRepoRoot) },
+  ]
+}
+
+/** The folded phase chain, with the card's own `position` read off the wire row. */
+function phaseRows(card: RecursiveRunCard): SettingsPhaseRow[] {
+  return expandPhaseRows(card).map((row) => {
+    const wired = row.fileName === null ? undefined : card.phases[row.fileName]
+    return {
+      phase: row.phase,
+      fileName: row.fileName,
+      status: row.status,
+      position: wired?.position ?? null,
+      lockedAt: text(row.lockedAt),
+      lockHash: text(row.lockHash),
+      present: row.present,
+      pill: phaseStatusPill(row.status),
+    }
+  })
+}
+
+/** One run card -> its report. */
+export function settingsRunView(card: RecursiveRunCard): SettingsRunView {
+  const subagents = carried(card.subagents)
+  const pendingWork = carried(card.pendingWork)
+  return {
+    runId: card.runId,
+    worktreeRoot: card.worktreeRoot,
+    state: card.state,
+    pill: cardPill(card),
+    rows: runRows(card),
+    phases: phaseRows(card),
+    subagents: subagents === undefined
+      ? null
+      : Object.values(subagents).map((s) => ({
+        childId: s.childId,
+        role: text(s.role),
+        provider: text(s.provider),
+        status: text(s.status),
+      })),
+    pendingWork: pendingWork === undefined
+      ? null
+      : pendingWork.map((p) => ({ kind: p.kind, delegationId: p.delegationId, detail: p.detail })),
+  }
+}
+
+/**
+ * The panel model for one live snapshot (null = the route has not answered yet).
+ * Every run in the projection is reported; nothing is filtered or defaulted.
+ */
+export function settingsView(snapshot: LiveProjectionValue | null): SettingsView {
+  if (snapshot === null) {
+    return { status: 'no-frame', root: null, revision: null, runs: [], notCarried: [...NOT_CARRIED] }
+  }
+  return {
+    status: snapshot.root === null ? 'no-root' : 'connected',
+    root: text(snapshot.root),
+    revision: typeof snapshot.revision === 'number' ? snapshot.revision : null,
+    runs: listRuns(snapshot.projection).map(settingsRunView),
+    notCarried: [...NOT_CARRIED],
+  }
+}

package/src/client/settings.tsx

@@ -1,18 +1,204 @@
 /**
- * Recursive settings page (Phase D R8, §11.8): a settings.section list entry
- * surfacing the host-owned enforcement config. The client is read-mostly; all
- * writes ride the host config path (never run files).
+ * Recursive settings page (§11.8): a settings.section list entry that REPORTS the
+ * live projection the host route serves — the enforcement-free facts the wire
+ * actually carries (run state + lock position, the folded phase chain with its
+ * T21 position, tamper/gate/pending facts, subagent role+provider records).
+ *
+ * WHAT THIS PANEL IS NOT: it is not a config editor and not a second board. The
+ * client is read-only (§11.9): it GETs the host route and reads no files. Every
+ * value is printed verbatim from the projection; a field the payload does not
+ * carry is printed as `not reported`, and the route-level fields the payload can
+ * never carry (enforcement modes, router defaults, scratch format) are listed by
+ * name at the bottom so a reader is never left guessing what is missing.
+ *
+ * `RecursiveSettings` is the pure renderer (props in, tree out). The live seat is
+ * `RecursiveSettingsLive`, which resolves the workspace scope exactly like the
+ * board seats and hands the snapshot down — the same shape board.tsx and
+ * inspector.tsx consume.
  */
-import { createElement } from 'react'
+import { createElement, type ReactElement, type ReactNode } from 'react'
+import { RECURSIVE_API_PREFIX } from '../live-route.ts'
+import {
+  currentSessionCwd,
+  currentWorkspacePath,
+  type LiveProjectionValue,
+  type SessionListStateLike,
+  type SnapshotSelectorHook,
+  type WorkspaceListStateLike,
+} from './contract.ts'
+import { PILL_LABELS } from './derive.ts'
+import { useLiveProjection } from './use-live.ts'
+import {
+  settingsView,
+  type SettingsPendingRow,
+  type SettingsPhaseRow,
+  type SettingsRow,
+  type SettingsRunView,
+  type SettingsStatus,
+  type SettingsSubagentRow,
+  type SettingsView,
+} from './settings-view.ts'
+
+/** Rendered in place of every value the projection did not carry. */
+export const ABSENT_LABEL = 'not reported'
 
 export interface RecursiveSettingsProps {
   close: () => void
+  /** The live host-route frame, or null while the first fetch is in flight. */
+  snapshot?: LiveProjectionValue | null
+}
+
+/** The route-answer states, each said plainly instead of implied by an empty panel. */
+const STATUS_TEXT: Record<SettingsStatus, string> = {
+  'no-frame': 'The host route has not answered for this workspace yet. Every value below is unknown — not a default.',
+  'no-root': 'The host route answered, but resolved no recursive root for this workspace (no .recursive/ run layer found).',
+  connected: 'Live.',
+}
+
+const STATUS_VALUE: Record<SettingsStatus, string> = {
+  'no-frame': 'no frame yet',
+  'no-root': 'answered · no recursive root',
+  connected: 'connected',
+}
+
+/** A label/value report block (`dl` — the semantics of a definition list). */
+function rows(className: string, items: readonly SettingsRow[]): ReactElement {
+  return createElement('dl', { className },
+    items.flatMap((row) => [
+      createElement('dt', { key: row.id + '-k', className: 'rec-settings-label' }, row.label),
+      createElement('dd', {
+        key: row.id + '-v',
+        className: row.value === null ? 'rec-settings-value rec-settings-absent' : 'rec-settings-value',
+      }, row.value ?? ABSENT_LABEL),
+    ]),
+  )
+}
+
+/** The frame's own facts: what the route answered, and how much it carried. */
+function sourceRows(view: SettingsView): SettingsRow[] {
+  return [
+    { id: 'status', label: 'route status', value: STATUS_VALUE[view.status] },
+    { id: 'root', label: 'workspace root', value: view.root },
+    { id: 'revision', label: 'revision', value: view.revision === null ? null : String(view.revision) },
+    { id: 'runs', label: 'runs in the projection', value: view.status === 'no-frame' ? null : String(view.runs.length) },
+  ]
+}
+
+function phaseNode(row: SettingsPhaseRow): ReactElement {
+  const lock: ReactNode[] = []
+  if (row.lockedAt !== null) lock.push(createElement('span', { key: 'at' }, 'locked at ' + row.lockedAt))
+  if (row.lockHash !== null) lock.push(createElement('code', { key: 'hash', className: 'rec-lockhash' }, '#' + row.lockHash.slice(0, 8)))
+  return createElement('div', { key: row.phase, className: 'rec-settings-phase' },
+    createElement('span', { className: 'rec-settings-phase-id' }, row.phase),
+    createElement('span', { className: 'rec-settings-phase-name' }, row.fileName ?? 'not present in this run'),
+    createElement('span', { className: 'rec-settings-phase-status' }, row.status),
+    createElement('span', {
+      className: row.position === null ? 'rec-settings-phase-pos rec-settings-absent' : 'rec-settings-phase-pos',
+    }, row.position ?? ABSENT_LABEL),
+    lock.length > 0 && createElement('span', { className: 'rec-settings-phase-lock' }, lock),
+  )
+}
+
+function subagentNode(s: SettingsSubagentRow): ReactElement {
+  return createElement('div', { key: s.childId, className: 'rec-settings-item' },
+    createElement('span', { className: 'rec-settings-item-id' }, s.childId),
+    createElement('span', { className: 'rec-settings-item-text' },
+      'role ' + (s.role ?? ABSENT_LABEL) + ' · provider ' + (s.provider ?? ABSENT_LABEL) + ' · status ' + (s.status ?? ABSENT_LABEL)),
+  )
+}
+
+function pendingNode(p: SettingsPendingRow): ReactElement {
+  return createElement('div', { key: p.kind + '\u0000' + p.delegationId, className: 'rec-settings-item' },
+    createElement('span', { className: 'rec-settings-item-id' }, p.kind),
+    createElement('span', { className: 'rec-settings-item-text' }, p.delegationId + ' — ' + p.detail),
+  )
+}
+
+/**
+ * A collection field: null = the card carried no such key (not reported),
+ * [] = the card carried an empty one (that empty value IS the report).
+ */
+function collection<T>(items: readonly T[] | null, render: (item: T) => ReactElement, none: string): ReactElement {
+  if (items === null) {
+    return createElement('p', { className: 'rec-settings-value rec-settings-absent' }, ABSENT_LABEL + ' — the card carries no such field')
+  }
+  if (items.length === 0) return createElement('p', { className: 'rec-settings-value rec-settings-none' }, none)
+  return createElement('div', { className: 'rec-settings-items' }, items.map(render))
 }
 
-export function RecursiveSettings({ close }: RecursiveSettingsProps) {
+function runSection(run: SettingsRunView): ReactElement {
+  const present = run.phases.filter((p) => p.present).length
+  return createElement('section', { key: run.worktreeRoot + '\u0000' + run.runId, className: 'rec-settings-run' },
+    createElement('div', { className: 'rec-settings-run-header' },
+      createElement('h3', { className: 'rec-settings-run-title' }, run.runId),
+      createElement('span', { className: 'rec-settings-pill', 'data-pill': run.pill }, PILL_LABELS[run.pill]),
+      createElement('span', { className: 'rec-settings-run-root' }, run.worktreeRoot),
+    ),
+    rows('rec-settings-rows', run.rows),
+    createElement('h4', { className: 'rec-settings-h4' }, 'Phases (' + String(present) + ' present)'),
+    createElement('p', { className: 'rec-settings-hint' },
+      'status is the folded artifact status; position is the host\'s single derived phase position (T21).'),
+    run.phases.length === 0
+      ? createElement('p', { className: 'rec-settings-value rec-settings-none' }, 'none — the card carries no phase rows')
+      : createElement('div', { className: 'rec-settings-phases' }, run.phases.map(phaseNode)),
+    createElement('h4', { className: 'rec-settings-h4' }, 'Subagents (role and provider as the host recorded them)'),
+    collection(run.subagents, subagentNode, 'none — the card carries an empty subagent map'),
+    createElement('h4', { className: 'rec-settings-h4' }, 'Pending work (unresolved in-flight delegations)'),
+    collection(run.pendingWork, pendingNode, 'none — the card carries an empty pending set'),
+  )
+}
+
+/** The panel: a report of one live frame. Pure — snapshot in, tree out. */
+export function RecursiveSettings({ close, snapshot = null }: RecursiveSettingsProps) {
+  const view = settingsView(snapshot)
   return createElement('div', { className: 'rec-settings' },
-    createElement('h2', {}, 'Recursive'),
-    createElement('p', {}, 'Enforcement policy, scratch format, provider defaults, and preset install path are configured on the host. The client is read-only (§11.9).'),
-    createElement('button', { onClick: close }, 'Close'),
+    createElement('header', { className: 'rec-settings-header' },
+      createElement('h2', { className: 'rec-settings-title' }, 'Recursive'),
+      createElement('span', { className: 'rec-settings-tag' }, 'live projection · read-only'),
+      createElement('button', { type: 'button', className: 'rec-settings-close', onClick: close }, 'Close'),
+    ),
+    createElement('p', { className: 'rec-settings-lede' },
+      'Read verbatim from the host route (GET ' + RECURSIVE_API_PREFIX + '/state + GET ' + RECURSIVE_API_PREFIX
+      + '/events). This client writes nothing and reads no files; anything the projection does not carry is printed as "'
+      + ABSENT_LABEL + '".'),
+    rows('rec-settings-source', sourceRows(view)),
+    view.status !== 'connected' && createElement('p', { className: 'rec-settings-hint' }, STATUS_TEXT[view.status]),
+    view.status === 'connected' && view.runs.length === 0
+      && createElement('p', { className: 'rec-settings-value rec-settings-none' }, 'none — the projection carries no runs in this workspace'),
+    view.runs.map(runSection),
+    createElement('section', { className: 'rec-settings-notcarried' },
+      createElement('h3', { className: 'rec-settings-h3' }, 'Not carried by this route'),
+      createElement('p', { className: 'rec-settings-hint' },
+        'Configured on the host, but the payload carries only {root, projection, revision} — so this panel reports them as unknown rather than guessing.'),
+      rows('rec-settings-rows', view.notCarried),
+    ),
   )
 }
+
+/** The settings seat props: the root standard kit plus the shell's close affordance. */
+export interface RecursiveSettingsSeatProps {
+  close: () => void
+  useSessions?: SnapshotSelectorHook<SessionListStateLike>
+  useWorkspaces?: SnapshotSelectorHook<WorkspaceListStateLike>
+}
+
+export interface RecursiveSettingsLiveProps {
+  close: () => void
+  useSessions: SnapshotSelectorHook<SessionListStateLike>
+  useWorkspaces: SnapshotSelectorHook<WorkspaceListStateLike>
+}
+
+/**
+ * The live seat: same scope resolution as the board seats (sessionId PRIMARY,
+ * workspace path as the cwd hint, session cwd while workspaces hydrate). Hooks
+ * are called unconditionally — the seat only renders this component when both
+ * selector hooks are present (slots.ts), so the hook order is fixed.
+ */
+export function RecursiveSettingsLive({ close, useSessions, useWorkspaces }: RecursiveSettingsLiveProps) {
+  const sessions = useSessions((s) => s)
+  const workspaces: WorkspaceListStateLike = useWorkspaces((s) => s) ?? { items: [], recentWorkspaceId: undefined }
+  const wsPath = currentWorkspacePath(workspaces, sessions)
+  const cwd = wsPath !== '' ? wsPath : currentSessionCwd(sessions)
+  const snapshot = useLiveProjection({ sessionId: sessions.current, cwd })
+  return createElement(RecursiveSettings, { close, snapshot })
+}

package/src/client/slots.ts

@@ -21,7 +21,7 @@ import type { ClientContext, SessionListStateLike, SnapshotSelectorHook, Workspa
 import { isRecursivePreset, currentWorkspacePath } from './contract.ts'
 import { Board } from './board.tsx'
 import { Inspector } from './inspector.tsx'
-import { RecursiveSettings } from './settings.tsx'
+import { RecursiveSettings, RecursiveSettingsLive, type RecursiveSettingsSeatProps } from './settings.tsx'
 import { useLiveProjection } from './use-live.ts'
 import { boardState, useBoardState } from './open-state.ts'
 import { injectBoardStyles } from './styles.ts'
@@ -139,12 +139,25 @@ export function registerSlots(ctx: ClientContext): () => void {
   })))
 
   // Settings section (root scope, always present; no gate — configuration is always available).
+  // The seat receives the shell's `close` PLUS the root standard kit (useSessions/useWorkspaces,
+  // scoped-slots standardProps), so the panel can subscribe to the SAME live route the board
+  // reads and report the projection. Without the kit the panel still renders — with every value
+  // reported as absent (never guessed), which is the honest degradation.
   disposers.push(ctx.slots.inject('settings.section', () => ctx.slots.register({
     name: 'settings.section',
     id: 'recursive',
     order: 90,
     label: 'Recursive',
-  }, (props: { close: () => void }) => createElement(RecursiveSettings, { close: props.close }))))
+  }, (props: RecursiveSettingsSeatProps) => {
+    if (props.useSessions === undefined || props.useWorkspaces === undefined) {
+      return createElement(RecursiveSettings, { close: props.close })
+    }
+    return createElement(RecursiveSettingsLive, {
+      close: props.close,
+      useSessions: props.useSessions,
+      useWorkspaces: props.useWorkspaces,
+    })
+  })))
 
   return () => { for (const d of disposers) d() }
 }