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

package/lib/client.js

@@ -975,16 +975,6 @@ window.__ModuleLoader__.load({
 			}, "View phase"))), facts.gateBlocked && (0, react.createElement)("div", { className: "rec-detail-section" }, (0, react.createElement)("h3", {}, "Gate"), (0, react.createElement)("p", { className: "rec-detail-text" }, "Blocked (" + (facts.gateKind ?? "") + ")"))), theme, toggle);
 		}
 		//#endregion
-		//#region src/client/settings.tsx
-		/**
-		* 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).
-		*/
-		function RecursiveSettings({ close }) {
-			return (0, react.createElement)("div", { className: "rec-settings" }, (0, react.createElement)("h2", {}, "Recursive"), (0, react.createElement)("p", {}, "Enforcement policy, scratch format, provider defaults, and preset install path are configured on the host. The client is read-only (§11.9)."), (0, react.createElement)("button", { onClick: close }, "Close"));
-		}
-		//#endregion
 		//#region src/client/use-live.ts
 		/**
 		* useLiveProjection(scope): the client bridge to the live host route (SP2 R1).
@@ -1032,6 +1022,289 @@ window.__ModuleLoader__.load({
 			return state;
 		}
 		//#endregion
+		//#region src/client/settings-view.ts
+		/**
+		* 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.
+		*/
+		const NOT_CARRIED = [
+			{
+				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) {
+			if (value === void 0 || 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(value) {
+			return value;
+		}
+		/** `none` for a present-but-empty map, null for a map the card did not carry. */
+		function tamperValue(card) {
+			const tampers = carried(card.tampers);
+			if (tampers === void 0) 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) {
+			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 === void 0 ? 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) {
+			return expandPhaseRows(card).map((row) => {
+				const wired = row.fileName === null ? void 0 : 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. */
+		function settingsRunView(card) {
+			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 === void 0 ? null : Object.values(subagents).map((s) => ({
+					childId: s.childId,
+					role: text(s.role),
+					provider: text(s.provider),
+					status: text(s.status)
+				})),
+				pendingWork: pendingWork === void 0 ? 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.
+		*/
+		function settingsView(snapshot) {
+			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]
+			};
+		}
+		/** The route-answer states, each said plainly instead of implied by an empty panel. */
+		const STATUS_TEXT = {
+			"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 = {
+			"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, items) {
+			return (0, react.createElement)("dl", { className }, items.flatMap((row) => [(0, react.createElement)("dt", {
+				key: row.id + "-k",
+				className: "rec-settings-label"
+			}, row.label), (0, react.createElement)("dd", {
+				key: row.id + "-v",
+				className: row.value === null ? "rec-settings-value rec-settings-absent" : "rec-settings-value"
+			}, row.value ?? "not reported")]));
+		}
+		/** The frame's own facts: what the route answered, and how much it carried. */
+		function sourceRows(view) {
+			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) {
+			const lock = [];
+			if (row.lockedAt !== null) lock.push((0, react.createElement)("span", { key: "at" }, "locked at " + row.lockedAt));
+			if (row.lockHash !== null) lock.push((0, react.createElement)("code", {
+				key: "hash",
+				className: "rec-lockhash"
+			}, "#" + row.lockHash.slice(0, 8)));
+			return (0, react.createElement)("div", {
+				key: row.phase,
+				className: "rec-settings-phase"
+			}, (0, react.createElement)("span", { className: "rec-settings-phase-id" }, row.phase), (0, react.createElement)("span", { className: "rec-settings-phase-name" }, row.fileName ?? "not present in this run"), (0, react.createElement)("span", { className: "rec-settings-phase-status" }, row.status), (0, react.createElement)("span", { className: row.position === null ? "rec-settings-phase-pos rec-settings-absent" : "rec-settings-phase-pos" }, row.position ?? "not reported"), lock.length > 0 && (0, react.createElement)("span", { className: "rec-settings-phase-lock" }, lock));
+		}
+		function subagentNode(s) {
+			return (0, react.createElement)("div", {
+				key: s.childId,
+				className: "rec-settings-item"
+			}, (0, react.createElement)("span", { className: "rec-settings-item-id" }, s.childId), (0, react.createElement)("span", { className: "rec-settings-item-text" }, "role " + (s.role ?? "not reported") + " · provider " + (s.provider ?? "not reported") + " · status " + (s.status ?? "not reported")));
+		}
+		function pendingNode(p) {
+			return (0, react.createElement)("div", {
+				key: p.kind + "\0" + p.delegationId,
+				className: "rec-settings-item"
+			}, (0, react.createElement)("span", { className: "rec-settings-item-id" }, p.kind), (0, react.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(items, render, none) {
+			if (items === null) return (0, react.createElement)("p", { className: "rec-settings-value rec-settings-absent" }, "not reported — the card carries no such field");
+			if (items.length === 0) return (0, react.createElement)("p", { className: "rec-settings-value rec-settings-none" }, none);
+			return (0, react.createElement)("div", { className: "rec-settings-items" }, items.map(render));
+		}
+		function runSection(run) {
+			const present = run.phases.filter((p) => p.present).length;
+			return (0, react.createElement)("section", {
+				key: run.worktreeRoot + "\0" + run.runId,
+				className: "rec-settings-run"
+			}, (0, react.createElement)("div", { className: "rec-settings-run-header" }, (0, react.createElement)("h3", { className: "rec-settings-run-title" }, run.runId), (0, react.createElement)("span", {
+				className: "rec-settings-pill",
+				"data-pill": run.pill
+			}, PILL_LABELS[run.pill]), (0, react.createElement)("span", { className: "rec-settings-run-root" }, run.worktreeRoot)), rows("rec-settings-rows", run.rows), (0, react.createElement)("h4", { className: "rec-settings-h4" }, "Phases (" + String(present) + " present)"), (0, react.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 ? (0, react.createElement)("p", { className: "rec-settings-value rec-settings-none" }, "none — the card carries no phase rows") : (0, react.createElement)("div", { className: "rec-settings-phases" }, run.phases.map(phaseNode)), (0, react.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"), (0, react.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. */
+		function RecursiveSettings({ close, snapshot = null }) {
+			const view = settingsView(snapshot);
+			return (0, react.createElement)("div", { className: "rec-settings" }, (0, react.createElement)("header", { className: "rec-settings-header" }, (0, react.createElement)("h2", { className: "rec-settings-title" }, "Recursive"), (0, react.createElement)("span", { className: "rec-settings-tag" }, "live projection · read-only"), (0, react.createElement)("button", {
+				type: "button",
+				className: "rec-settings-close",
+				onClick: close
+			}, "Close")), (0, react.createElement)("p", { className: "rec-settings-lede" }, "Read verbatim from the host route (GET /.recursive/api/state + GET /.recursive/api/events). This client writes nothing and reads no files; anything the projection does not carry is printed as \"not reported\"."), rows("rec-settings-source", sourceRows(view)), view.status !== "connected" && (0, react.createElement)("p", { className: "rec-settings-hint" }, STATUS_TEXT[view.status]), view.status === "connected" && view.runs.length === 0 && (0, react.createElement)("p", { className: "rec-settings-value rec-settings-none" }, "none — the projection carries no runs in this workspace"), view.runs.map(runSection), (0, react.createElement)("section", { className: "rec-settings-notcarried" }, (0, react.createElement)("h3", { className: "rec-settings-h3" }, "Not carried by this route"), (0, react.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 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.
+		*/
+		function RecursiveSettingsLive({ close, useSessions, useWorkspaces }) {
+			const sessions = useSessions((s) => s);
+			const wsPath = currentWorkspacePath(useWorkspaces((s) => s) ?? {
+				items: [],
+				recentWorkspaceId: void 0
+			}, sessions);
+			const cwd = wsPath !== "" ? wsPath : currentSessionCwd(sessions);
+			const snapshot = useLiveProjection({
+				sessionId: sessions.current,
+				cwd
+			});
+			return (0, react.createElement)(RecursiveSettings, {
+				close,
+				snapshot
+			});
+		}
+		//#endregion
 		//#region src/client/open-state.ts
 		/**
 		* Shared board open-state (run 08 R1): module-level store behind the launcher,
@@ -1955,6 +2228,243 @@ window.__ModuleLoader__.load({
   border-color: var(--dsw-alias-state-warn-primary);
 }
 
+/* ===== Settings section (Settings -> Recursive): the live projection report =====
+   This panel lives INSIDE the settings shell, so it consumes the shell's own
+   --dsw-alias-* theme tokens (like .rec-badge above) instead of the board's
+   scoped --board-* paper tokens: no theme toggle, and it follows the app theme. */
+.rec-settings {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-width: 940px;
+  padding: 2px 2px 10px;
+  color: var(--dsw-alias-label-primary);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.rec-settings-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.rec-settings-title {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+.rec-settings-tag {
+  flex: none;
+  padding: 2px 8px;
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+  color: var(--dsw-alias-label-tertiary);
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+}
+
+.rec-settings-close {
+  margin-left: auto;
+  padding: 5px 12px;
+  font: inherit;
+  font-size: 12px;
+  color: var(--dsw-alias-label-primary);
+  background: transparent;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+.rec-settings-close:hover {
+  background: var(--dsw-alias-bg-layer-3);
+}
+
+.rec-settings-lede,
+.rec-settings-hint,
+.rec-settings-none {
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rec-settings-hint,
+.rec-settings-none {
+  font-size: 12px;
+}
+
+.rec-settings-section,
+.rec-settings-notcarried,
+.rec-settings-run {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px 14px;
+  background: var(--dsw-alias-bg-layer-2);
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 10px;
+}
+
+.rec-settings-h3 {
+  margin: 0;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.rec-settings-h4 {
+  margin: 6px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rec-settings-run-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.rec-settings-run-title {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+
+.rec-settings-run-root {
+  flex: 1;
+  min-width: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Solid state pill, same vocabulary as .rec-pill but on the SHELL tokens
+   (the board's --board-* aliases are scoped to .rec-board/.rec-inspector). */
+.rec-settings-pill {
+  flex: none;
+  padding: 3px 10px;
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
+  border-radius: 999px;
+  color: var(--dsw-alias-label-primary-foreground);
+  background: var(--dsw-alias-label-tertiary);
+}
+
+.rec-settings-pill[data-pill='locked']      { background: var(--dsw-alias-state-success-primary); }
+.rec-settings-pill[data-pill='in-progress'] { background: var(--dsw-alias-state-business-primary); }
+.rec-settings-pill[data-pill='paused']      { background: var(--dsw-alias-state-warn-primary); }
+.rec-settings-pill[data-pill='blocked']     { background: var(--dsw-alias-state-error-primary); }
+.rec-settings-pill[data-pill='tampered']    { background: var(--dsw-alias-state-error-primary); }
+.rec-settings-pill[data-pill='advisory']    { background: var(--dsw-alias-state-warn-secondary); }
+.rec-settings-pill[data-pill='neutral']     { background: var(--dsw-alias-label-tertiary); }
+
+dl.rec-settings-source,
+dl.rec-settings-rows {
+  display: grid;
+  grid-template-columns: minmax(160px, 300px) 1fr;
+  gap: 4px 16px;
+  margin: 0;
+}
+
+.rec-settings-label {
+  font-size: 12px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.rec-settings-value {
+  margin: 0;
+  color: var(--dsw-alias-label-primary);
+  overflow-wrap: anywhere;
+}
+
+/* An absent value is a STATEMENT, not an empty row — always visibly marked. */
+.rec-settings-absent {
+  color: var(--dsw-alias-state-warn-label);
+  font-style: italic;
+}
+
+.rec-settings-phases {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.rec-settings-phase {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 10px;
+  padding: 4px 10px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 6px;
+}
+
+.rec-settings-phase-id {
+  flex: none;
+  min-width: 40px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rec-settings-phase-name {
+  flex: 1;
+  min-width: 140px;
+  overflow-wrap: anywhere;
+}
+
+.rec-settings-phase-status,
+.rec-settings-phase-pos {
+  flex: none;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  letter-spacing: 0.02em;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rec-settings-phase-lock {
+  flex: none;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.rec-settings-items {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.rec-settings-item {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  font-size: 12px;
+}
+
+.rec-settings-item-id {
+  flex: none;
+  min-width: 96px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.rec-settings-item-text {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
 @media (prefers-reduced-motion: reduce) {
   .rec-card, .rec-back, .rec-close, .rec-theme-toggle { transition: none; }
 }
@@ -2100,7 +2610,14 @@ window.__ModuleLoader__.load({
 				id: "recursive",
 				order: 90,
 				label: "Recursive"
-			}, (props) => (0, react.createElement)(RecursiveSettings, { close: props.close }))));
+			}, (props) => {
+				if (props.useSessions === void 0 || props.useWorkspaces === void 0) return (0, react.createElement)(RecursiveSettings, { close: props.close });
+				return (0, react.createElement)(RecursiveSettingsLive, {
+					close: props.close,
+					useSessions: props.useSessions,
+					useWorkspaces: props.useWorkspaces
+				});
+			})));
 			return () => {
 				for (const d of disposers) d();
 			};
@@ -2169,6 +2686,7 @@ window.__ModuleLoader__.load({
 		exports.DocViewer = DocViewer;
 		exports.Inspector = Inspector;
 		exports.RecursiveSettings = RecursiveSettings;
+		exports.RecursiveSettingsLive = RecursiveSettingsLive;
 		exports.RecursiveView = RecursiveView;
 		exports.apply = apply;
 		exports.currentSessionCwd = currentSessionCwd;
@@ -2179,6 +2697,7 @@ window.__ModuleLoader__.load({
 		exports.listRuns = listRuns;
 		exports.parseDoc = parseDoc;
 		exports.parseInline = parseInline;
+		exports.settingsView = settingsView;
 		exports.subscribeLiveEvents = subscribeLiveEvents;
 		exports.useLiveProjection = useLiveProjection;
 		return module.exports;

package/lib/enforcement.d.ts

@@ -124,10 +124,47 @@ export declare function evaluateToolGuard(exec: ToolExecLike, worktreeRoot: stri
  * decisions pass through unchanged.
  */
 export declare function coerceAskToDecision(decision: ToolGuardDecision, mode?: EnforcementMode): ToolGuardDecision;
+/**
+ * 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.
+ */
+export declare function tamperCandidatePath(targetPath: string, worktreeRoot: string): string | null;
 /**
  * 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.
  */
 export declare function detectTamper(targetPath: string, worktreeRoot: string, activeRunId: string): {
     runId: string;