@evoclock/pi-agentic-driver 0.10.1 → 1.1.0

package/scripts/enforcement/nudge_validate_pi.js

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// `nudge validate` (NUDGE §7, rule 30): a read-only setup-time validator in
+// the shape of router_validate_pi.js. It loads the merged nudge config
+// exactly as the runtime would (repo defaults + optional profile overlay,
+// same merge semantics: profile sections replace wholesale), then reports
+// findings with paths. Exit 0 only when the config is valid AND operational
+// — a valid schema with a missing required N1 capability (the upstream herdr
+// nudge verb has not shipped) is reported non-operational and exits nonzero.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+import {
+  validateNudgeConfig, NUDGE_CONFIG_SCHEMA, NUDGE_REMOVED_KEYS,
+  probeNudgeUpstreamCapability,
+} from "./nudge_config_pi.js";
+import { TRUSTED_HERDR_EXECUTABLE } from "./herdr_communication_pi.js";
+
+export const NUDGE_DEFAULTS_RELATIVE_PATH = ".agentic-driver/nudge.defaults.json";
+export const NUDGE_PROFILE_DEFAULT_PATH = join(homedir(), ".config", "agentic-driver", "nudge", "profile.json");
+
+// Optional cross-surface inputs: the dispatch config's poll bound and
+// stallPolls. When a dispatch config exists, the validator cross-checks
+// (SEAM §7); when it does not, those checks are skipped and reported as
+// such — the runtime re-checks at enablement.
+export const DISPATCH_DEFAULTS_RELATIVE_PATH = ".agentic-driver/dispatch.defaults.json";
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; }
+}
+
+function mergeConfigs(defaults, profile) {
+  if (profile === null || profile === undefined) return defaults;
+  if (defaults === null || defaults === undefined) return profile;
+  return {
+    ...defaults,
+    ...profile,
+    nudge: profile.nudge !== undefined ? profile.nudge : defaults.nudge,
+  };
+}
+
+export function validateNudgeSetup({
+  repoRoot = process.cwd(),
+  defaultsPath = null,
+  profilePath = null,
+  dispatchPath = null,
+  upstreamCapabilityVerified = false,
+  capabilityProbe = null,
+} = {}) {
+  // Part 2.11: `upstreamCapabilityVerified` may be asserted by the caller, or
+  // resolved through the probe seam when one is SUPPLIED. When a probe is
+  // given it must be a synchronous verdict provider (or an already-resolved
+  // {verified}); async probing is the caller's job — see
+  // resolveNudgeSetupWithProbe below. An unverified capability remains the
+  // expected fail-closed state until the upstream herdr nudge verb ships.
+  // The manual assertion is never a substitute for the probe: it only lets a
+  // caller that has already run the probe fold the verdict into this report.
+  let capabilityVerified = upstreamCapabilityVerified === true;
+  let capabilityProbeReason = null;
+  if (!capabilityVerified && capabilityProbe !== null && typeof capabilityProbe === "object" && typeof capabilityProbe.then !== "function") {
+    capabilityVerified = capabilityProbe.verified === true;
+    capabilityProbeReason = capabilityProbe.reason ?? null;
+  } else if (!capabilityVerified && capabilityProbe !== null) {
+    throw Object.assign(new Error("an async capabilityProbe must be resolved before validateNudgeSetup — use resolveNudgeSetupWithProbe"), { code: "invalid_parameters" });
+  }
+  const resolvedDefaults = resolve(defaultsPath ?? join(repoRoot, NUDGE_DEFAULTS_RELATIVE_PATH));
+  const resolvedProfile = resolve(profilePath ?? process.env.AGENTIC_DRIVER_NUDGE_PROFILE ?? NUDGE_PROFILE_DEFAULT_PATH);
+  const resolvedDispatch = resolve(dispatchPath ?? join(repoRoot, DISPATCH_DEFAULTS_RELATIVE_PATH));
+  const errors = [];
+  const warnings = [];
+
+  const defaults = readJsonIfExists(resolvedDefaults);
+  if (defaults === null) {
+    errors.push(`defaults: nudge defaults file is missing: ${resolvedDefaults}`);
+  } else if (defaults === undefined) {
+    errors.push(`defaults: nudge defaults file is not valid JSON: ${resolvedDefaults}`);
+  }
+  let profile = null;
+  if (existsSync(resolvedProfile)) {
+    profile = readJsonIfExists(resolvedProfile);
+    if (profile === undefined) errors.push(`profile: nudge profile file is not valid JSON: ${resolvedProfile}`);
+    else if (profile !== null) warnings.push(`profile loaded: ${resolvedProfile}`);
+  } else {
+    warnings.push(`no profile at ${resolvedProfile} — defaults only`);
+  }
+
+  const config = mergeConfigs(defaults, profile);
+  if (config !== null && config !== undefined) {
+    // Cross-surface inputs from the dispatch config when present.
+    let maxPollsPerSubmit = null;
+    let stallPolls = null;
+    const dispatch = readJsonIfExists(resolvedDispatch);
+    if (dispatch !== null && dispatch !== undefined) {
+      const poll = dispatch.poll;
+      if (poll !== null && typeof poll === "object" && !Array.isArray(poll)) {
+        maxPollsPerSubmit = typeof poll.maxPollsPerSubmit === "number" ? poll.maxPollsPerSubmit : null;
+        stallPolls = typeof poll.stallPolls === "number" ? poll.stallPolls : null;
+      }
+      if (poll === null || typeof poll !== "object" || Array.isArray(poll)) {
+        warnings.push(`dispatch: no poll section found at ${resolvedDispatch} — cross-surface window checks skipped (the runtime re-checks at enablement)`);
+      }
+      // Single-owner check for stallPolls (§7): if the nudge config somehow
+      // carries it, the closed validator already rejects the unknown key;
+      // here we name the ownership rule explicitly.
+      if (config.nudge && Object.prototype.hasOwnProperty.call(config.nudge, "stallPolls")) {
+        errors.push("nudge.stallPolls: stallPolls is owned solely by the dispatch config — duplicate ownership is invalid");
+      }
+    } else if (defaults !== null) {
+      warnings.push(`no dispatch config at ${resolvedDispatch} — cross-surface window checks skipped (the runtime re-checks at enablement)`);
+    }
+
+    const validation = validateNudgeConfig(config, { upstreamCapabilityVerified: capabilityVerified, maxPollsPerSubmit, stallPolls });
+    for (const error of validation.errors) errors.push(`config: ${error}`);
+    if (validation.ok && !validation.operational) {
+      if (capabilityVerified !== true) {
+        // §7: a valid schema with a missing required N1 capability is
+        // reported non-operational and exits nonzero — but it is a finding,
+        // not a config error, so it lands in warnings when the config itself
+        // is valid.
+        warnings.push("operational: the required N1 upstream capability (herdr agent nudge with modal-isolation fixtures) is not verified — the ladder is configured but non-operational (§7)");
+      } else if (config.nudge?.enabled !== true) {
+        warnings.push("operational: nudge.enabled is false — the ladder is configured but not activated");
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    operational: errors.length === 0 && capabilityVerified === true && config?.nudge?.enabled === true,
+    capabilityVerified: capabilityVerified === true,
+    ...(capabilityProbeReason !== null ? { capabilityProbeReason } : {}),
+    defaultsPath: resolvedDefaults,
+    profilePath: resolvedProfile,
+    dispatchPath: resolvedDispatch,
+    errors,
+    warnings,
+    removedKeysRejected: NUDGE_REMOVED_KEYS,
+    schema: NUDGE_CONFIG_SCHEMA,
+  };
+}
+
+// Part 2.11: async-capable setup resolution. Runs the supplied probe (or the
+// default trusted-executable probe) and folds its verdict into the setup
+// report. The probe is the seam: when the upstream herdr nudge verb ships and
+// its modal-isolation fixtures pass, the probe verifies and `nudge validate`
+// reports operational (with enabled:true). Until then every probe outcome is
+// verified:false and the validator stays non-operational — fail closed.
+export async function resolveNudgeSetupWithProbe({
+  repoRoot = process.cwd(),
+  defaultsPath = null,
+  profilePath = null,
+  dispatchPath = null,
+  upstreamCapabilityVerified = false,
+  probe = null,
+} = {}) {
+  let capabilityProbeReason = null;
+  let capabilityVerified = upstreamCapabilityVerified === true;
+  if (!capabilityVerified) {
+    const runProbe = typeof probe === "function" ? probe : () => probeNudgeUpstreamCapability({ executable: TRUSTED_HERDR_EXECUTABLE });
+    try {
+      const verdict = await runProbe();
+      capabilityVerified = verdict?.verified === true;
+      capabilityProbeReason = verdict?.reason ?? null;
+    } catch (error) {
+      capabilityVerified = false;
+      capabilityProbeReason = `the nudge-capability probe failed: ${String(error?.message || error).slice(0, 200)}`;
+    }
+  }
+  const report = validateNudgeSetup({
+    repoRoot,
+    defaultsPath,
+    profilePath,
+    dispatchPath,
+    upstreamCapabilityVerified: capabilityVerified,
+    ...(capabilityProbeReason !== null ? { capabilityProbe: { verified: capabilityVerified, reason: capabilityProbeReason } } : {}),
+  });
+  return report;
+}
+
+export function formatNudgeValidateReport(report) {
+  const lines = [];
+  lines.push(report.valid ? "nudge config is valid" : "nudge config is NOT valid");
+  lines.push(report.operational ? "nudge ladder is operational" : "nudge ladder is NOT operational");
+  lines.push(`defaults: ${report.defaultsPath}`);
+  lines.push(`profile: ${report.profilePath}`);
+  lines.push(`dispatch cross-check: ${report.dispatchPath}`);
+  for (const error of report.errors) lines.push(`ERROR: ${error}`);
+  for (const warning of report.warnings) lines.push(`warn: ${warning}`);
+  return lines.join("\n");
+}
+
+function isEntrypoint() {
+  if (typeof process === "undefined" || !Array.isArray(process.argv) || process.argv[1] === undefined) return false;
+  return pathToFileURL(process.argv[1]).href === import.meta.url;
+}
+
+if (isEntrypoint()) {
+  const args = process.argv.slice(2);
+  const take = (flag) => {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : null;
+  };
+  const capabilityFlag = args.includes("--upstream-capability-verified");
+  const report = await resolveNudgeSetupWithProbe({
+    repoRoot: process.cwd(),
+    defaultsPath: take("--defaults"),
+    profilePath: take("--profile"),
+    dispatchPath: take("--dispatch"),
+    upstreamCapabilityVerified: capabilityFlag,
+  });
+  process.stdout.write(`${formatNudgeValidateReport(report)}\n`);
+  if (!report.valid || !report.operational) {
+    process.stderr.write(`${JSON.stringify({
+      valid: report.valid, operational: report.operational,
+      errors: report.errors, warnings: report.warnings,
+    }, null, 2)}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}

package/scripts/enforcement/pulse_scheduler_pi.js

@@ -24,7 +24,7 @@ import {
 import { scanBoard } from "./pulse_core_pi.js";
 import { routeDecision } from "./router_engine_pi.js";
 import { createReservation, claimReservation, renewReservationLease, consumeReservation, releaseReservation, insertRouteDecision } from "./router_store_pi.js";
-import { isNativeTuiContext } from "./native_tui_context.js";
+import { isAttendedElectronContext, isNativeTuiContext } from "./native_tui_context.js";
 
 // ---------------------------------------------------------------------------
 // Board resolution and observation
@@ -571,7 +571,7 @@ export function validateSpawnMatchesEnvelope({ envelope, model, provider = null,
   return { ok: true, code: null, reason: null };
 }
 
-export function pulseWorkerSpawnSeam({ executeHerdrSpawnWorker } = {}) {
+export function pulseWorkerSpawnSeam({ executeHerdrSpawnWorker, executeHerdrSpawnWorkerAttendedElectron = null, spawnOptions = {} } = {}) {
   if (typeof executeHerdrSpawnWorker !== "function") {
     throw new Error("pulseWorkerSpawnSeam requires the guarded herdr-lifecycle executeHerdrSpawnWorker");
   }
@@ -595,7 +595,19 @@ export function pulseWorkerSpawnSeam({ executeHerdrSpawnWorker } = {}) {
         || resolve(repository) !== resolve(coordinator, "..", repositoryName)) {
       return { ok: false, code: "repository-mismatch", reason: "the assignment repository is not a canonical sibling of the coordinator repository" };
     }
-    return executeHerdrSpawnWorker({ placement: "tab", role, model, repository: repositoryName }, context, {}, signal);
+    // Explicit context dispatch. A native Pi TUI context keeps the existing
+    // guarded lifecycle unchanged. An explicit attended-Electron context (a
+    // separate class that never satisfies the TUI predicate) routes to the
+    // attended Electron boundary when the trusted host bound it; without a
+    // bound boundary the spawn fails closed here. No other context class is
+    // dispatched: the TUI predicate itself is not weakened for any caller.
+    if (isAttendedElectronContext(context)) {
+      if (typeof executeHerdrSpawnWorkerAttendedElectron !== "function") {
+        return { ok: false, code: "attended-electron-seam-required", reason: "an attended Electron context was supplied but the attended Electron spawn boundary was not bound (fails closed)" };
+      }
+      return executeHerdrSpawnWorkerAttendedElectron({ placement: "tab", role, model, repository: repositoryName }, context, spawnOptions, signal);
+    }
+    return executeHerdrSpawnWorker({ placement: "tab", role, model, repository: repositoryName }, context, spawnOptions, signal);
   };
 }
 

package/scripts/enforcement/recovery_evidence_review_pi.js

@@ -0,0 +1,269 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Owner-only review access to recorded recovery evidence (first host
+// binding/review-access slice). The trusted Pi host derives the explicit
+// owner-private storage root itself — never from model or worker input — and
+// the single owner-initiated command is native-TUI-only. The TUI modality is
+// a privacy-confinement boundary, not authentication: it confines the full
+// evidence to a transient terminal overlay so it never reaches the model
+// transcript, tool content, or any public output; it does not verify who the
+// viewer is or add owner identity to the evidence store's own checks. RPC,
+// JSON, and print modes are refused fail-closed for that confinement reason.
+// Read-only review never creates storage, and no model-callable raw-evidence
+// tool exists here or anywhere else.
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import {
+  RECOVERY_EVIDENCE_SCHEMA,
+  openRecoveryEvidenceStore,
+  closeRecoveryEvidenceStore,
+  readRecoveryEvidence,
+  listRecoveryEvidenceReferences,
+} from "./recovery_evidence_store_pi.js";
+import { isNativeTuiContext } from "./native_tui_context.js";
+
+export const RECOVERY_EVIDENCE_REVIEW_SCHEMA = "agentic-driver.recovery-evidence-review.v1";
+export const RECOVERY_EVIDENCE_REVIEW_COMMAND = "agentic-recovery-evidence";
+// Matches the store's default per-record bound; a reference claiming more
+// bytes than this is refused before any store is opened.
+export const MAX_REVIEW_BYTES = 128 * 1024;
+export const REVIEW_LIST_LIMIT = 50;
+const MAX_ID_LENGTH = 256;
+const SHA256 = /^[a-f0-9]{64}$/;
+const CLOSED_REFERENCE_FIELDS = Object.freeze(["bytes", "entryId", "journeyId", "phase", "schema", "sha256"]);
+const REGISTRATIONS = new WeakSet();
+// Width-safe rendering comes from Pi's own terminal-width helpers when the
+// installed runtime exposes them; the offline test environment falls back to
+// a plain-length approximation so the review logic stays testable.
+let widthHelpers = null;
+async function loadWidthHelpers() {
+  if (widthHelpers) return widthHelpers;
+  try {
+    const tui = await import("@earendil-works/pi-tui");
+    if (typeof tui.visibleWidth === "function" && typeof tui.truncateToWidth === "function") {
+      widthHelpers = { visibleWidth: tui.visibleWidth, truncateToWidth: tui.truncateToWidth };
+    }
+  } catch { /* offline test environment: fallback below */ }
+  if (!widthHelpers) {
+    widthHelpers = {
+      visibleWidth: (text) => text.length,
+      truncateToWidth: (text, width) => (text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`),
+    };
+  }
+  return widthHelpers;
+}
+
+function refuse(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function result(code, reason) {
+  return { ok: false, schema: RECOVERY_EVIDENCE_REVIEW_SCHEMA, code, reason };
+}
+
+function commandArgumentsPresent(args) {
+  if (args === undefined || args === null) return false;
+  if (typeof args === "string") return args.trim().length > 0;
+  if (Array.isArray(args)) return args.some((value) => String(value).trim().length > 0);
+  return Object.keys(args).length > 0;
+}
+
+/**
+ * Host-derived owner-private root. The explicit root comes from trusted host
+ * environment configuration and must be an absolute path; it is canonicalized
+ * (trailing slashes and redundant separators removed) but never silently
+ * expanded: a leading `~` is rejected because expanding it would guess at the
+ * owner's intent instead of following an explicit host contract. The fallback
+ * is the Pi coding-agent config directory. Command arguments and model/worker
+ * input can never supply the root.
+ */
+export function resolveReviewEvidenceRoot(env = process.env) {
+  const explicit = typeof env.AGENTIC_DRIVER_RECOVERY_EVIDENCE_ROOT === "string"
+    ? env.AGENTIC_DRIVER_RECOVERY_EVIDENCE_ROOT.trim()
+    : "";
+  if (explicit) {
+    if (!isAbsolute(explicit) || explicit.startsWith("~")) {
+      throw refuse("invalid-root", "AGENTIC_DRIVER_RECOVERY_EVIDENCE_ROOT must be an absolute path from the trusted host; relative and ~ paths are refused");
+    }
+    return resolve(explicit);
+  }
+  const agentDir = typeof env.PI_CODING_AGENT_DIR === "string" && env.PI_CODING_AGENT_DIR.trim()
+    ? env.PI_CODING_AGENT_DIR.trim()
+    : join(homedir(), ".pi", "agent");
+  return join(agentDir, "recovery-evidence");
+}
+
+/** Closed reference fields only; an oversized reference is refused unread. */
+export function parseReviewReference(input, { maxBytes = MAX_REVIEW_BYTES } = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw refuse("invalid-bound", "maxBytes must be a positive safe integer");
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw refuse("invalid-reference", "a recovery evidence reference object is required");
+  }
+  const keys = Object.keys(input).sort();
+  if (keys.length !== CLOSED_REFERENCE_FIELDS.length || keys.some((key, index) => key !== CLOSED_REFERENCE_FIELDS[index])) {
+    throw refuse("invalid-reference", `reference must contain exactly the closed fields: ${CLOSED_REFERENCE_FIELDS.join(", ")}`);
+  }
+  if (input.schema !== RECOVERY_EVIDENCE_SCHEMA) throw refuse("invalid-reference", "reference schema does not match the recovery evidence schema");
+  if (typeof input.journeyId !== "string" || !input.journeyId || input.journeyId.length > MAX_ID_LENGTH
+    || typeof input.entryId !== "string" || !input.entryId || input.entryId.length > MAX_ID_LENGTH) {
+    throw refuse("invalid-reference", "reference journeyId and entryId must be bounded non-empty strings");
+  }
+  if (!["requested", "terminal"].includes(input.phase)) throw refuse("invalid-reference", "reference phase must be 'requested' or 'terminal'");
+  if (typeof input.sha256 !== "string" || !SHA256.test(input.sha256)) throw refuse("invalid-reference", "reference sha256 must be lowercase 64-hex");
+  if (!Number.isSafeInteger(input.bytes) || input.bytes < 1) throw refuse("invalid-reference", "reference bytes must be a positive safe integer");
+  if (input.bytes > maxBytes) throw refuse("reference-too-large", `reference bytes exceed the ${maxBytes}-byte review bound`);
+  return Object.freeze({ ...input });
+}
+
+function openReadOnly(root) {
+  try {
+    return { store: openRecoveryEvidenceStore({ root, readOnly: true }) };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { failure: result("evidence-store-missing", "no recovery evidence store exists at the host-derived owner-private root; nothing was created") };
+    if (typeof error?.code === "string" && error.code !== "") return { failure: result(error.code, `the recovery evidence store refused read-only review (${error.code})`) };
+    return { failure: result("evidence-store-unavailable", "the recovery evidence store could not be opened read-only") };
+  }
+}
+
+/** Bounded, read-only listing of closed retrieval references; never bodies. */
+export function listReviewableReferences({ root, limit = REVIEW_LIST_LIMIT } = {}) {
+  const opened = openReadOnly(root);
+  if (opened.failure) return opened.failure;
+  try {
+    return { ok: true, schema: RECOVERY_EVIDENCE_REVIEW_SCHEMA, references: listRecoveryEvidenceReferences(opened.store, { limit }) };
+  } catch (error) {
+    const code = typeof error?.code === "string" && error.code !== "" ? error.code : "invalid-bound";
+    return result(code, String(error?.message || error));
+  } finally {
+    closeRecoveryEvidenceStore(opened.store);
+  }
+}
+
+/** Retrieve and verify one reference read-only; returns the full entry for owner display only. */
+export function reviewRecoveryEvidence({ root, reference, maxBytes = MAX_REVIEW_BYTES } = {}) {
+  let ref;
+  try {
+    ref = parseReviewReference(reference, { maxBytes });
+  } catch (error) {
+    return result(error?.code ?? "invalid-reference", String(error?.message || error));
+  }
+  const opened = openReadOnly(root);
+  if (opened.failure) return opened.failure;
+  try {
+    const verified = readRecoveryEvidence(opened.store, ref);
+    return { ok: true, schema: RECOVERY_EVIDENCE_REVIEW_SCHEMA, reference: verified.reference, entry: verified.entry };
+  } catch (error) {
+    return result(error?.code ?? "evidence-corrupt", String(error?.message || error));
+  } finally {
+    closeRecoveryEvidenceStore(opened.store);
+  }
+}
+
+/** Full evidence lines for the owner-only overlay; never sent through notify or any model surface. */
+export function evidenceDisplayLines(reviewed) {
+  const { reference, entry } = reviewed;
+  return [
+    `schema:   ${reference.schema}`,
+    `journey:  ${reference.journeyId}`,
+    `entry:    ${reference.entryId}`,
+    `phase:    ${reference.phase}`,
+    `sha256:   ${reference.sha256}`,
+    `bytes:    ${reference.bytes} (verified against the store)`,
+    "",
+    "--- recorded entry (exact owner-private content) ---",
+    ...JSON.stringify(entry, null, 2).split("\n"),
+  ];
+}
+
+const VIEW_LINES = 24;
+
+/** Minimal terminal-only overlay component for the interactive TUI. */
+export async function createEvidenceOverlay({ done, lines, tui }) {
+  const { visibleWidth, truncateToWidth } = await loadWidthHelpers();
+  let offset = 0;
+  const maxOffset = () => Math.max(0, lines.length - VIEW_LINES);
+  return {
+    render(width) {
+      const w = Math.max(20, Number(width) || 80);
+      const fit = (line) => (visibleWidth(line) <= w ? line : truncateToWidth(line, w));
+      const body = lines.slice(offset, offset + VIEW_LINES).map(fit);
+      while (body.length < VIEW_LINES) body.push("");
+      return [
+        fit(`Recovery evidence (owner-only) — ${lines.length} lines; up/down or space scrolls; Enter/Esc closes`),
+        "",
+        ...body,
+      ];
+    },
+    handleInput(data) {
+      const previous = offset;
+      if (data === "\x1b[A") offset = Math.max(0, offset - 1);
+      else if (data === "\x1b[B") offset = Math.min(maxOffset(), offset + 1);
+      else if (data === " ") offset = Math.min(maxOffset(), offset + VIEW_LINES);
+      else if (data === "\x1b" || data === "q" || data === "\r" || data === "\n") done(undefined);
+      // Only an actual scroll change redraws; unrelated keys request nothing.
+      if (offset !== previous && typeof tui?.requestRender === "function") tui.requestRender();
+    },
+  };
+}
+
+/**
+ * Registers ONLY the owner-initiated slash command. No model-callable tool is
+ * registered here, and no raw-evidence tool may be added later: the full
+ * evidence travels exclusively through the native TUI overlay. The trusted
+ * root is snapshotted once at registration so a later in-process environment
+ * mutation cannot redirect review to a different store mid-session; the
+ * snapshot still honors the trusted host context that existed at load time.
+ */
+export async function registerRecoveryEvidenceReview(pi, _options = {}) {
+  if (typeof pi?.registerCommand !== "function" || REGISTRATIONS.has(pi)) return;
+  REGISTRATIONS.add(pi);
+  const registeredRoot = resolveReviewEvidenceRoot();
+  const notify = (context, message, type) => {
+    if (typeof context?.ui?.notify === "function") context.ui.notify(message, type);
+  };
+  pi.registerCommand(RECOVERY_EVIDENCE_REVIEW_COMMAND, {
+    description: "Review recorded recovery evidence (owner-only, interactive TUI; evidence is never shown to the model)",
+    argumentHint: "",
+    handler: async (args, context) => {
+      // The handler always returns undefined: nothing it does may become
+      // model-visible content or transcript output.
+      if (commandArgumentsPresent(args)) {
+        notify(context, "Recovery evidence review accepts no command arguments; the trusted host derives the owner-private root.", "warning");
+        return undefined;
+      }
+      // Fail closed outside the interactive native TUI: RPC forwards dialogs
+      // but custom() is undefined there, and JSON/print have no UI at all.
+      if (!isNativeTuiContext(context) || typeof context?.ui?.custom !== "function" || typeof context?.ui?.select !== "function") {
+        notify(context, "Recovery evidence review requires the interactive native Pi TUI; RPC, JSON, and print modes are refused so evidence can never enter a transcript.", "warning");
+        return undefined;
+      }
+      const root = registeredRoot;
+      const listing = listReviewableReferences({ root, limit: REVIEW_LIST_LIMIT });
+      if (!listing.ok) {
+        notify(context, `Recovery evidence review: ${listing.code} — ${listing.reason}`, listing.code === "evidence-store-missing" ? "info" : "error");
+        return undefined;
+      }
+      if (listing.references.length === 0) {
+        notify(context, "No recovery evidence is recorded yet.", "info");
+        return undefined;
+      }
+      const labels = listing.references.map((ref) =>
+        `${ref.phase} · ${ref.journeyId} · ${ref.entryId} · ${ref.sha256.slice(0, 12)} · ${ref.bytes} B`);
+      const selected = await context.ui.select("Recovery evidence (owner-only review)", labels);
+      const selectedIndex = typeof selected === "string" ? labels.indexOf(selected) : -1;
+      if (selectedIndex < 0) return undefined;
+      const reviewed = reviewRecoveryEvidence({ root, reference: listing.references[selectedIndex] });
+      if (!reviewed.ok) {
+        notify(context, `Recovery evidence review: ${reviewed.code} — ${reviewed.reason}`, "error");
+        return undefined;
+      }
+      // The only full-evidence surface: a transient terminal overlay that
+      // never reaches the session transcript, tool results, or the model.
+      // The injected tui handle is captured so scrolling can request renders.
+      await context.ui.custom((tui, _theme, _keybindings, done) =>
+        createEvidenceOverlay({ done, lines: evidenceDisplayLines(reviewed), tui }));
+      return undefined;
+    },
+  });
+}