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

package/lib/index.js

@@ -1490,14 +1490,22 @@ function lockOrderRule(artifact, runDir) {
 /**
 * Locked-artifact write rule: a denial when the target carries
 * `Status: LOCKED`, `null` otherwise. Only a run-tree `*.md` is a candidate —
-* the same admission test the pre-T16 branch used.
+* the same admission test the pre-T16 branch used, now asked of the RESOLVED
+* path as well (see the ADMISSION note below).
+*
+* A caller with no `worktreeRoot` still gets `null` for every target, absolute
+* ones included: that is the pre-existing behaviour and it is left alone here —
+* the guard always carries a root, so nothing that reaches it changes.
 */
 function lockedWriteRule(target, worktreeRoot) {
 	if (!target || !worktreeRoot) return null;
 	const normalized = target.replace(/\\/g, "/");
-	if (!normalized.endsWith(".md") || !normalized.includes("/.recursive/run/")) return null;
+	if (!normalized.endsWith(".md")) return null;
 	const abs = resolveFrom(worktreeRoot, normalized);
-	if (!abs || getLockStatus(abs) !== "LOCKED") return null;
+	if (!abs) return null;
+	const resolved = abs.replace(/\\/g, "/");
+	if (!normalized.includes("/.recursive/run/") && !resolved.includes("/.recursive/run/")) return null;
+	if (getLockStatus(abs) !== "LOCKED") return null;
 	return {
 		verdict: "deny",
 		detail: normalized + " carries Status: LOCKED (reopen explicitly to edit)"
@@ -2123,7 +2131,7 @@ function resolveFrom(worktreeRoot, target) {
 	const normalized = target.replace(/\\/g, "/").trim();
 	if (!normalized) return null;
 	if (/^[A-Za-z]:\//.test(normalized) || normalized.startsWith("/")) return resolve(normalized);
-	return resolve(join(worktreeRoot, normalized.replace(/^\.?\/?/, "")));
+	return resolve(join(worktreeRoot, normalized.replace(/^\.\//, "")));
 }
 /** The tool-target path of a call (same key order enforcement.ts uses). */
 function policyTargetPath(args) {
@@ -5993,13 +6001,41 @@ function reviewBundleDir(root, runId) {
 * discipline the lock receipts, the closeout receipts and the selection output all follow.
 */
 /** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
-const FEEDBACK_FILE = "memory/.feedback.json";
+const FEEDBACK_FILE = ".recursive/memory/.feedback.json";
+/**
+* WHERE THE COUNTERS LIVED BEFORE the constant above carried its `.recursive/` prefix.
+*
+* ⚠ READ, BUT DELIBERATELY NEITHER MOVED NOR DELETED. Read, because evidence a previous run recorded is
+* not the plugin's to discard, and without the fallback the first settle after the move would start the
+* new file from an empty book — a counter lost silently, which is the one outcome ruled out. NOT moved,
+* because a delete is the single action that could re-create the very defect the prefix fixes: a legacy
+* file that is TRACKED and COMMITTED is absent from the run's diff while it is clean, so removing it
+* mid-run puts `D memory/.feedback.json` into the diff of every diff-audited phase authored before the
+* delete, which is the same retro-invalidation. Left alone, an untracked legacy file is in the diff from
+* the run's first phase (and is therefore accounted for), while a committed one stays invisible.
+* `readFeedback` prefers {@link FEEDBACK_FILE}, so the legacy counters are folded forward by the next
+* settle and this file then only sits there; it is machine-owned and disposable, so delete it by hand.
+*/
+const LEGACY_FEEDBACK_FILE = "memory/.feedback.json";
 /** Where a run records what it was shown. */
 const INJECTIONS_FILE = "memory-injections.json";
-/** Read the counters. A missing or unreadable file is an empty book, never an error. */
+/**
+* Read the counters. A missing or unreadable file is an empty book, never an error.
+*
+* ⚠ THE LEGACY PATH IS A FALLBACK AND ONLY A FALLBACK: it is consulted when — and only when — there is
+* no usable file at {@link FEEDBACK_FILE} yet, which is exactly the first run after the path moved. The
+* two are never merged, because they are two SNAPSHOTS of one counter and adding them would count a run
+* twice. A file that exists at the current path but does not parse stays an empty book, which is what
+* this function has always promised: a corrupt sidecar is not an invitation to read a different file.
+*/
 function readFeedback(root, readFile = defaultRead$1) {
-	const text = readFile(join(root, FEEDBACK_FILE));
-	if (text === null || text.trim() === "") return {};
+	const current = readFile(join(root, FEEDBACK_FILE));
+	if (current !== null && current.trim() !== "") return parseBook(current);
+	const legacy = readFile(join(root, LEGACY_FEEDBACK_FILE));
+	return legacy === null ? {} : parseBook(legacy);
+}
+/** One counters file as a book: anything unreadable or unshaped is `{}`, never an error. */
+function parseBook(text) {
 	try {
 		const parsed = JSON.parse(text);
 		if (typeof parsed !== "object" || parsed === null) return {};
@@ -6075,7 +6111,9 @@ function settleInjections(root, runDir, lockedPhases, write = defaultWrite, read
 		counter.applied += 1;
 		book[record.source] = counter;
 	}
-	write(join(root, FEEDBACK_FILE), JSON.stringify(sortBook(book), null, 2) + "\n");
+	const feedbackPath = join(root, FEEDBACK_FILE);
+	mkdirSync(dirname(feedbackPath), { recursive: true });
+	write(feedbackPath, JSON.stringify(sortBook(book), null, 2) + "\n");
 	return book;
 }
 /**
@@ -7234,7 +7272,20 @@ function currentPhaseArtifact(worktreeRoot, runId) {
 			best = name;
 		}
 	}
-	return best;
+	let inForce = "";
+	let inForcePhase = Number.POSITIVE_INFINITY;
+	for (const name of names) {
+		if (!name.endsWith(".md")) continue;
+		const phase = phaseNumberForArtifact(name);
+		if (!phase) continue;
+		const value = Number(phase);
+		if (getLockStatus(join(runDir, name)) === "LOCKED") continue;
+		if (value < inForcePhase) {
+			inForcePhase = value;
+			inForce = name;
+		}
+	}
+	return inForce !== "" ? inForce : best;
 }
 function evaluateToolGuard(exec, worktreeRoot, activeRunId, mode = "advisory") {
 	const name = exec.name;
@@ -7359,14 +7410,58 @@ function resolveTargetPath(target, worktreeRoot) {
 	return abs;
 }
 /**
+* The ADMISSION test for the tamper path: the resolved absolute path when
+* `targetPath` names a run-tree `*.md` — a tamper CANDIDATE — and `null`
+* otherwise. Pure path arithmetic on every branch (no filesystem work), so a
+* caller may use it as a cheap shape check before paying for `existsSync`.
+*
+* ⚠ THE BLIND SPOT THIS FUNCTION EXISTS TO CLOSE. The admission test used to be a
+* substring test on the target STRING alone, looking for `/.recursive/run/`. A
+* repo-relative path has no separator before `.recursive`, so
+* `.recursive/run/<id>/00-requirements.md` — the spelling a model actually types,
+* and its backslash form — was rejected before ANYTHING was examined, and
+* tampering with a locked artifact through that spelling was invisible
+* (measured: `detectTamper` returned a record for the absolute path and `null`
+* for the relative one, on the same file). The identical defect, in the identical
+* spelling, was fixed one module over in `policy-globs.ts` `lockedWriteRule`; this
+* is that fix's shape, reused rather than reinvented.
+*
+* So the marker is looked for on the path the target RESOLVES to as well as on
+* the string as written. The `||` is load-bearing and the string test is KEPT
+* rather than replaced, because a resolved-only test would SHRINK the admitted
+* set: an absolute target that literally carries the marker but resolves away
+* from it (`…/.recursive/run/../…`) was caught before and must stay caught. The
+* net effect is a strict SUPERSET of the previous behaviour, so no tamper that
+* was visible before can become invisible.
+*
+* EXPORTED because `src/index.ts`'s `fs/observed` listener must apply the SAME
+* admission test before calling `detectTamper`. That listener used to carry a
+* hand-copied mirror of this test, and a mirror is exactly what leaves half the
+* defect behind: widening `detectTamper` alone changes nothing, because the
+* listener rejects the spelling first. One function cannot disagree with itself.
+*/
+function tamperCandidatePath(targetPath, worktreeRoot) {
+	const normalized = targetPath.replace(/\\/g, "/");
+	if (!normalized.endsWith(".md")) return null;
+	const abs = resolveTargetPath(normalized, worktreeRoot);
+	if (!abs) return null;
+	const resolved = abs.replace(/\\/g, "/");
+	if (!normalized.includes("/.recursive/run/") && !resolved.includes("/.recursive/run/")) return null;
+	return abs;
+}
+/**
 * Layer 8 - fs/observed lock-tamper detection.
 * A locked *.md whose observed version differs from the stored LockHash is
 * a tamper. Returns a tamper reason (or null when clean/not-applicable).
+*
+* The admission test lives in `tamperCandidatePath` (above), shared with the
+* `fs/observed` listener in `src/index.ts` — see the note there for why sharing
+* it is the point and not a tidiness preference. What this function reports is
+* unchanged: the same record shape, carrying the target AS WRITTEN.
 */
 function detectTamper(targetPath, worktreeRoot, activeRunId) {
 	const normalized = targetPath.replace(/\\/g, "/");
-	if (!normalized.endsWith(".md") || !normalized.includes("/.recursive/run/")) return null;
-	const abs = resolveTargetPath(normalized, worktreeRoot);
+	const abs = tamperCandidatePath(normalized, worktreeRoot);
 	if (!abs || !existsSync(abs)) return null;
 	if (getLockStatus(abs) === "STALE_LOCK") return {
 		runId: activeRunId,
@@ -10443,6 +10538,8 @@ var RecursiveRuntime = class extends Service {
 		}
 		const inFlight = pendingWork(runDir);
 		if (inFlight.length > 0) throw new Error(toolError("PENDING_WORK", inFlight.map((p) => p.detail).join("; ")));
+		const lint = await this.lintArtifact(runId, artifact, agent);
+		if (!lint.passed) throw new Error("Artifact " + artifact + " does not meet the phase standard, so it was not locked: " + lint.errors.join("; "));
 		let content = readFileSync(artifactPath, "utf8");
 		const lockedAt = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 		content = setOrInsertField(content, "Status", "LOCKED", ["Phase"]);
@@ -12526,7 +12623,7 @@ function renderExplained(entries) {
 *    present-but-empty value would stop the deferral and pin the choice to nothing, which is a different state
 *    from "unconfigured" and not one a user can see. Absence is the honest representation of "I have no opinion".
 *
-* 3. **WRITE ATOMICALLY.** A temp file and a rename, the same pattern the preset installer uses. A policy file
+* 3. **WRITE ATOMICALLY.** A temp file and a rename, the same pattern the preset installer used, before it was retired. A policy file
 *    half-written because a process died mid-write would make `loadRouterPolicy` fall back to the built-in
 *    self-audit policy — and it does that SILENTLY, on purpose (it never throws). So a torn write here would look
 *    exactly like "the user configured nothing", for every role, until someone read the file.
@@ -13614,9 +13711,17 @@ function apply(ctx, config) {
 			ctx.tools.register(createRecursiveReviewTool(recursive, subagentsSeam)),
 			ctx.tools.register(createRecursiveDelegateTool(recursive, subagentsSeam)),
 			ctx.tools.register(createRecursiveAskTool(recursive)),
-			ctx.tools.register(createRecursivePreviewTool(recursive)),
-			...agentTeams ? [ctx.tools.register(createRecursiveAuditTeamTool(agentTeams))] : []
+			ctx.tools.register(createRecursivePreviewTool(recursive))
 		];
+		let auditTeamRegistered = agentTeams !== void 0 && agentTeams !== null;
+		if (auditTeamRegistered) disposers.push(ctx.tools.register(createRecursiveAuditTeamTool(agentTeams ?? null)));
+		ctx.inject(["agentTeams"], (teamCtx) => {
+			if (auditTeamRegistered) return;
+			const late = teamCtx.get("agentTeams");
+			if (late === void 0 || late === null) return;
+			auditTeamRegistered = true;
+			ctx.tools.register(createRecursiveAuditTeamTool(late));
+		});
 		const commands = ctx.get("commands");
 		if (commands) disposers.push(registerRecursiveCommand({ commands }, recursive));
 		const systemPrompt = ctx.get("systemPrompt");
@@ -13715,10 +13820,10 @@ function apply(ctx, config) {
 				if (observation?.kind !== "present") return;
 				const displayPath = target?.displayPath ?? "";
 				if (!displayPath) return;
-				const normalized = displayPath.replace(/\\/g, "/");
-				if (!normalized.endsWith(".md") || !normalized.includes("/.recursive/run/")) return;
 				const cwd = actor?.agent?.session?.header?.cwd ?? "";
 				if (!cwd) return;
+				const normalized = displayPath.replace(/\\/g, "/");
+				if (!tamperCandidatePath(normalized, cwd)) return;
 				const runId = resolveRunDir(cwd)?.runId ?? "";
 				const tamper = recursive.detectTamper(normalized, cwd, runId);
 				if (!tamper) return;
@@ -13823,4 +13928,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_POSITIONS, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, buildWorkSlice, builtInToolPolicy, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, contractDigest, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, currentPhaseArtifact, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldDiagnostics, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, parseReplyVerdict, pendingWork, phaseIndex, phasePosition, probeCapabilities, readReceipt, readRepairFromReply, readRepairFromStructured, readVerdictFromReply, readVerdictFromStructured, receiptPath, referencesFromResult, registerRecursiveSkill, remainingDepthFor, renderPhaseTail, renderRecursivePolicy, renderStableContract, renderTaskHistory, replyPath, resetFoldCache, resolveEnforcementConfig, resolveRole, resolveRunDir, resolveToolPolicyForGuard, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_POSITIONS, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, buildWorkSlice, builtInToolPolicy, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, contractDigest, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, currentPhaseArtifact, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldDiagnostics, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, parseReplyVerdict, pendingWork, phaseIndex, phasePosition, probeCapabilities, readReceipt, readRepairFromReply, readRepairFromStructured, readVerdictFromReply, readVerdictFromStructured, receiptPath, referencesFromResult, registerRecursiveSkill, remainingDepthFor, renderPhaseTail, renderRecursivePolicy, renderStableContract, renderTaskHistory, replyPath, resetFoldCache, resolveEnforcementConfig, resolveRole, resolveRunDir, resolveToolPolicyForGuard, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, tamperCandidatePath, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };

package/lib/memory-feedback.d.ts

@@ -1,5 +1,20 @@
 /** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
-export declare const FEEDBACK_FILE = "memory/.feedback.json";
+export declare const FEEDBACK_FILE = ".recursive/memory/.feedback.json";
+/**
+ * WHERE THE COUNTERS LIVED BEFORE the constant above carried its `.recursive/` prefix.
+ *
+ * ⚠ READ, BUT DELIBERATELY NEITHER MOVED NOR DELETED. Read, because evidence a previous run recorded is
+ * not the plugin's to discard, and without the fallback the first settle after the move would start the
+ * new file from an empty book — a counter lost silently, which is the one outcome ruled out. NOT moved,
+ * because a delete is the single action that could re-create the very defect the prefix fixes: a legacy
+ * file that is TRACKED and COMMITTED is absent from the run's diff while it is clean, so removing it
+ * mid-run puts `D memory/.feedback.json` into the diff of every diff-audited phase authored before the
+ * delete, which is the same retro-invalidation. Left alone, an untracked legacy file is in the diff from
+ * the run's first phase (and is therefore accounted for), while a committed one stays invisible.
+ * `readFeedback` prefers {@link FEEDBACK_FILE}, so the legacy counters are folded forward by the next
+ * settle and this file then only sits there; it is machine-owned and disposable, so delete it by hand.
+ */
+export declare const LEGACY_FEEDBACK_FILE = "memory/.feedback.json";
 /** Where a run records what it was shown. */
 export declare const INJECTIONS_FILE = "memory-injections.json";
 /** One entry the agent was shown, as the run recorded it. */
@@ -18,7 +33,15 @@ export interface FeedbackCounter {
     contradicted: number;
 }
 export type FeedbackBook = Record<string, FeedbackCounter>;
-/** Read the counters. A missing or unreadable file is an empty book, never an error. */
+/**
+ * Read the counters. A missing or unreadable file is an empty book, never an error.
+ *
+ * ⚠ THE LEGACY PATH IS A FALLBACK AND ONLY A FALLBACK: it is consulted when — and only when — there is
+ * no usable file at {@link FEEDBACK_FILE} yet, which is exactly the first run after the path moved. The
+ * two are never merged, because they are two SNAPSHOTS of one counter and adding them would count a run
+ * twice. A file that exists at the current path but does not parse stays an empty book, which is what
+ * this function has always promised: a corrupt sidecar is not an invitation to read a different file.
+ */
 export declare function readFeedback(root: string, readFile?: (path: string) => string | null): FeedbackBook;
 /** Read what a run recorded being shown. */
 export declare function readInjections(runDir: string, readFile?: (path: string) => string | null): InjectionRecord[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + 13 recursive_* tools (recursive_status, recursive_init, recursive_lock, recursive_lint, recursive_closeout, recursive_scratch, recursive_worktree, recursive_phase, recursive_audit_team, recursive_review, recursive_delegate, recursive_ask, recursive_preview)",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/client/index.ts

@@ -19,7 +19,9 @@ export { Board, listRuns } from './board.tsx'
 export { Inspector } from './inspector.tsx'
 export { DocViewer, parseDoc, parseInline } from './doc-viewer.tsx'
 export { RecursiveView } from './slots.ts'
-export { RecursiveSettings } from './settings.tsx'
+export { RecursiveSettings, RecursiveSettingsLive } from './settings.tsx'
+export { settingsView } from './settings-view.ts'
+export type { SettingsView, SettingsRunView, SettingsRow } from './settings-view.ts'
 export { useLiveProjection } from './use-live.ts'
 export type { LiveProjectionSnapshot } from './use-live.ts'
 export { fetchLiveState, subscribeLiveEvents } from './host-api.ts'

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],
+  }
+}