@ijfw/memory-server 1.4.4 → 1.5.0

package/src/orchestrator/wave-state.js

@@ -7,11 +7,67 @@
  *
  * Landed in W10-A0 (v1.4.4 prelude). checkpointWave is a stub;
  * N4 (W10-A2) will flesh out the blackboard→STATE rollup logic.
+ *
+ * v1.5.0 T7 (this task): wave.* writes route through the state-SDK
+ * (`query('wave.advance', ...)`) — tmp+rename + locks + intent/commit
+ * journalling happen inside the SDK. STATE.md frontmatter is the single
+ * source of truth; the `blockers_open` key is now derived FROM
+ * `decisions.jsonl` at checkpoint time (the SDK's `blocker.add`/
+ * `blocker.resolve` verbs append there), giving a single writer and a single
+ * representation. `blockers_open` carries the blocker **id** array (machine-
+ * consumed); a separate `blockers_open_summary` carries human-readable text.
+ *
+ * KNOWN SDK GAP (T7-followup-1): the SDK's `wave.advance` verb does NOT
+ * accept a `body` field — its handler always preserves the existing body.
+ * Until a body-write SDK verb lands, `writeWaveState` does a follow-up raw
+ * atomic write to update the body. The body-write itself is still
+ * tmp+rename+lock-protected and the SDK frontmatter write already committed
+ * via the intent journal — so the worst-case partial state (frontmatter
+ * advanced, body stale) is bounded and self-healing on next checkpoint.
  */
 
 import { mkdir, readFile, writeFile, rename, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { withFsLock } from '../fs-lock.js';
+import { readBlackboard } from '../blackboard.js';
+import { query } from './state-sdk.js';
+
+// Lazy S4 loader. Top-level `await import` would break `node:test` (unsettled
+// top-level await). Resolves on first checkpointWave call instead. Missing
+// module is non-fatal (silent fail — populateBlackboardBlock stays null).
+//
+// v1.5.0 audit-MED-work-M9: previously this used a `_s4LoadAttempted` boolean
+// + a sync `_populateBlackboardBlock` mutation. That had a race window: two
+// concurrent callers entering before the `await import` settled would BOTH
+// fire `import()` (cheap on resolved-module cache, but the race-condition
+// taxonomy still flagged it as a singleton smell). Replaced with a Promise
+// singleton: the first caller stores the promise; subsequent callers await
+// the same promise. No double-import, no race on the result variable.
+let _populateBlackboardBlockPromise = null;
+function loadPopulateBlackboardBlock() {
+  if (_populateBlackboardBlockPromise === null) {
+    _populateBlackboardBlockPromise = (async () => {
+      try {
+        const mod = await import('./agents-md-blackboard.js');
+        return mod.populateBlackboardBlock ?? null;
+      } catch {
+        // S4 not landed — advisory only
+        return null;
+      }
+    })();
+  }
+  return _populateBlackboardBlockPromise;
+}
+
+/**
+ * Test-only helper: reset the populateBlackboardBlock promise singleton so a
+ * test can simulate "first call after process start" semantics. Internal.
+ *
+ * @internal
+ */
+export function _resetPopulateBlackboardBlockSingleton() {
+  _populateBlackboardBlockPromise = null;
+}
 
 // ---------------------------------------------------------------------------
 // Internal YAML helpers — flat subset only (string/number/boolean/string[])
@@ -167,23 +223,70 @@ export async function readWaveState(waveId, projectRoot) {
 }
 
 /**
- * Atomically write a wave's STATE.md using withFsLock + tmp+rename.
- * Auto-creates .ijfw/wave-<waveId>/ if missing.
+ * Atomically write a wave's STATE.md.
+ *
+ * v1.5.0 T7: frontmatter writes route through the state-SDK
+ * (`query('wave.advance', {waveId, status, frontmatter}, {projectRoot})`) so
+ * tmp+rename + locks + intent/commit journalling happen inside the SDK. The
+ * body — which the SDK contract does not yet expose a write verb for — is
+ * applied via a follow-up atomic write inside the same wave-STATE lock. The
+ * SDK's `wave.advance` handler preserves the existing body when it rewrites
+ * frontmatter, so the follow-up write only mutates body content and never
+ * loses an in-flight frontmatter update.
+ *
+ * Auto-creates `.ijfw/wave-<waveId>/` if missing (the SDK handler creates it
+ * on first call).
  *
  * @param {string} waveId
- * @param {{frontmatter: object, body: string}} state
+ * @param {{frontmatter: object, body?: string}} state
  * @param {string} projectRoot
  * @returns {Promise<void>}
  */
 export async function writeWaveState(waveId, state, projectRoot) {
-  const { dir, state: statePath, lock, tmp } = wavePaths(waveId, projectRoot);
-  const payload = `---\n${emitYaml(state.frontmatter)}\n---\n\n${state.body}`;
+  const fm = state.frontmatter || {};
+  // SDK's wave.advance requires `status` — supply 'pending' as a safe default
+  // for callers that haven't materialised one yet (matches deriveStatus's
+  // default-on-empty-blackboard behaviour).
+  const status = (typeof fm.status === 'string' && fm.status.length > 0)
+    ? fm.status : 'pending';
+  // wave.advance MERGES payload.frontmatter into the existing frontmatter;
+  // pass the full requested frontmatter so unrelated keys are overwritten
+  // intentionally (writeWaveState semantics: caller supplies the full
+  // frontmatter shape they want persisted).
+  await query(
+    'wave.advance',
+    { waveId, status, frontmatter: { ...fm } },
+    { projectRoot },
+  );
 
-  await withFsLock(lock, async () => {
-    await mkdir(dir, { recursive: true });
-    await writeFile(tmp, payload, 'utf8');
-    await rename(tmp, statePath);
-  });
+  // Body follow-up: SDK-gap T7-followup-1 — wave.advance preserves existing
+  // body and there is no body-write SDK verb yet. Until one lands, do an
+  // atomic in-place body update. Held under the same wave-STATE lock used by
+  // every wave-state writer, so concurrent checkpoints serialise.
+  if (state.body !== undefined && state.body !== null) {
+    const { dir, state: statePath, lock, tmp } = wavePaths(waveId, projectRoot);
+    await withFsLock(lock, async () => {
+      await mkdir(dir, { recursive: true });
+      let frontmatterRaw;
+      try {
+        const raw = await readFile(statePath, 'utf8');
+        const secondDelim = raw.indexOf('\n---', 3);
+        // Defensive: if the SDK-written STATE.md is somehow malformed, fall
+        // back to re-emitting frontmatter from the in-memory shape rather
+        // than refusing the body write.
+        if (raw.startsWith('---') && secondDelim !== -1) {
+          frontmatterRaw = raw.slice(0, secondDelim + 4); // '---\n…\n---\n'
+        } else {
+          frontmatterRaw = `---\n${emitYaml(fm)}\n---\n`;
+        }
+      } catch {
+        frontmatterRaw = `---\n${emitYaml(fm)}\n---\n`;
+      }
+      const payload = `${frontmatterRaw}\n${state.body}`;
+      await writeFile(tmp, payload, 'utf8');
+      await rename(tmp, statePath);
+    });
+  }
 }
 
 /**
@@ -226,9 +329,156 @@ export async function appendSummary(waveId, delta, projectRoot) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Rollup helpers — exported for direct testing (W11-B1 / S5)
+// ---------------------------------------------------------------------------
+
 /**
- * Stub checkpoint — full blackboard→STATE rollup remains v1.5.0 work.
- * Seeds an empty state if missing; updates only frontmatter.checkpoint_at.
+ * Derive the next STATE.md status from the wave-filtered blackboard slice and
+ * the previously-persisted state.
+ *
+ * Rules (R1 §S5):
+ *   1. any open blocker       → 'blocked'
+ *   2. no claims at all       → preserve existing status (default 'pending')
+ *   3. every claim 'released' → 'review'
+ *   4. otherwise              → 'in_progress'
+ *
+ * @param {{claims: object[], findings: object[], blockers: object[]}} filtered
+ * @param {{frontmatter?: object} | null} existing
+ * @returns {'blocked'|'pending'|'review'|'in_progress'}
+ */
+export function deriveStatus(filtered, existing) {
+  if (filtered.blockers && filtered.blockers.length > 0) return 'blocked';
+  if (filtered.claims.length === 0) return existing?.frontmatter?.status ?? 'pending';
+  if (filtered.claims.every((c) => c.status === 'released')) return 'review';
+  return 'in_progress';
+}
+
+/**
+ * Tag a blackboard entry as belonging to a wave by checking, in order:
+ *   - explicit `wave_id` field
+ *   - artifact_id prefixed `<waveId>:`
+ *   - message containing `[<waveId>]`
+ *
+ * @param {{claims?: {data?: {claims?: object[]}}, recent?: {findings?: object[], blockers?: object[]}}} blackboard
+ * @param {string} waveId
+ * @returns {{claims: object[], findings: object[], blockers: object[]}}
+ */
+export function filterByWave(blackboard, waveId) {
+  const tag = (entry) => {
+    if (!entry) return false;
+    if (entry.wave_id === waveId) return true;
+    if (typeof entry.artifact_id === 'string' && entry.artifact_id.startsWith(`${waveId}:`)) return true;
+    if (typeof entry.message === 'string' && entry.message.includes(`[${waveId}]`)) return true;
+    return false;
+  };
+  const claims = (blackboard.claims?.data?.claims ?? []).filter(tag);
+  const findings = (blackboard.recent?.findings ?? []).filter(tag);
+  const blockers = (blackboard.recent?.blockers ?? []).filter(tag);
+  return { claims, findings, blockers };
+}
+
+/**
+ * Quote YAML strings that would otherwise confuse the flat-subset parser/emitter:
+ * presence of `:`, `#`, `[`, `]`, `{`, `}`, `"`, newline, or `<space>-`.
+ *
+ * Fold-in: Trident r13 F6 — emit safety for STATE.md frontmatter strings.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function quoteYamlStr(s) {
+  if (typeof s !== 'string') return String(s);
+  if (/[:#[\]{}"\n]|\s-/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s;
+}
+
+/**
+ * Render the markdown body for STATE.md from the wave-filtered blackboard slice.
+ * Findings are capped to the last 5 (matches frontmatter.findings_recent window).
+ *
+ * @param {{findings: object[], blockers: object[]}} filtered
+ * @param {{body?: string} | null} _existing  (reserved for future merge logic)
+ * @returns {string}
+ */
+export function renderBody(filtered, _existing) {
+  const lines = [];
+  if (filtered.findings.length > 0) {
+    lines.push('## Recent findings');
+    for (const f of filtered.findings.slice(-5)) {
+      lines.push(`- ${f.message ?? '(unspecified)'}`);
+    }
+    lines.push('');
+  }
+  if (filtered.blockers.length > 0) {
+    lines.push('## Open blockers');
+    for (const b of filtered.blockers) {
+      lines.push(`- ${b.message ?? '(unspecified)'}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * v1.5.0 T7: derive the open-blocker set for a wave from `decisions.jsonl`.
+ *
+ * The SDK's `blocker.add` / `blocker.resolve` verbs append `kind:'blocker'` /
+ * `kind:'blocker-resolution'` records to `.ijfw/blackboard/decisions.jsonl`
+ * (T4 contract §7). A blocker is **open** when:
+ *   - a `kind:'blocker'` record exists for the wave (matched by
+ *     record.waveId === waveId), AND
+ *   - no later `kind:'blocker-resolution'` record carries the same
+ *     `blockerId`.
+ *
+ * Returns parallel arrays of stable ids (for `blockers_open`, machine-
+ * consumed) and human messages (for `blockers_open_summary`, optional UI).
+ *
+ * @param {{recent?: {decisions?: object[]}}} blackboard
+ * @param {string} waveId
+ * @returns {{ids: string[], summaries: string[]}}
+ */
+export function deriveOpenBlockers(blackboard, waveId) {
+  const decisions = Array.isArray(blackboard?.recent?.decisions)
+    ? blackboard.recent.decisions : [];
+  const resolvedIds = new Set();
+  for (const r of decisions) {
+    if (r && r.kind === 'blocker-resolution' && typeof r.blockerId === 'string') {
+      resolvedIds.add(r.blockerId);
+    }
+  }
+  const ids = [];
+  const summaries = [];
+  const seen = new Set();
+  for (const r of decisions) {
+    if (!r || r.kind !== 'blocker') continue;
+    if (typeof r.blockerId !== 'string' || !r.blockerId) continue;
+    if (r.waveId !== waveId) continue;
+    if (resolvedIds.has(r.blockerId)) continue;
+    if (seen.has(r.blockerId)) continue;
+    seen.add(r.blockerId);
+    ids.push(r.blockerId);
+    summaries.push(quoteYamlStr(typeof r.text === 'string' ? r.text : ''));
+  }
+  return { ids, summaries };
+}
+
+/**
+ * Roll up the blackboard slice for `waveId` into STATE.md frontmatter+body.
+ *
+ * Steps:
+ *  1. Read existing STATE.md (preserve created_at if present).
+ *  2. Read blackboard.js — defensive: missing/uninitialized blackboard yields
+ *     empty arrays so checkpointing never throws on a clean tree.
+ *  3. Filter blackboard entries by wave tag.
+ *  4. Derive `blockers_open` from `decisions.jsonl` (single source of truth —
+ *     the SDK's blocker.add/blocker.resolve verbs append there). Legacy
+ *     `blackboard.recent.blockers` (from `addBlackboardNote(kind:'blocker')`)
+ *     still drives the `status='blocked'` rule for back-compat.
+ *  5. Derive status + frontmatter; render markdown body.
+ *  6. Persist atomically via writeWaveState (SDK-routed).
+ *  7. Append a SUMMARY.md delta when status transitions.
+ *  8. If S4's populateBlackboardBlock is loaded, refresh AGENTS.md (advisory —
+ *     silent on failure).
  *
  * @param {string} waveId
  * @param {string} projectRoot
@@ -238,18 +488,77 @@ export async function checkpointWave(waveId, projectRoot) {
   const now = new Date().toISOString();
   const existing = await readWaveState(waveId, projectRoot);
 
-  const next = existing
-    ? { frontmatter: { ...existing.frontmatter, checkpoint_at: now }, body: existing.body }
-    : {
-        frontmatter: {
-          wave_id: waveId,
-          status: 'in_progress',
-          created_at: now,
-          checkpoint_at: now,
-        },
-        body: '',
-      };
+  // readBlackboard returns synchronously per blackboard.js; uninitialized
+  // blackboard yields empty arrays so the rollup is safe on a clean tree.
+  let blackboard;
+  try {
+    blackboard = readBlackboard(projectRoot);
+  } catch {
+    blackboard = {
+      claims: { data: { claims: [] } },
+      recent: { findings: [], blockers: [], decisions: [] },
+    };
+  }
+
+  const filtered = filterByWave(blackboard, waveId);
+  // T7: single-writer reconciliation. `blockers_open` is now derived from
+  // decisions.jsonl (the SDK's blocker.add/blocker.resolve target) — an array
+  // of stable blocker ids. The legacy blackboard `blockers.jsonl` slice is
+  // still used to drive `status='blocked'` so existing call sites that emit
+  // blockers via `addBlackboardNote(kind:'blocker')` keep working.
+  const openBlockers = deriveOpenBlockers(blackboard, waveId);
+  // For deriveStatus and renderBody, merge legacy filtered blockers with the
+  // SDK-derived ones so any source of an open blocker still flips status.
+  const sdkBlockerEntries = openBlockers.ids.map((id, i) => ({
+    blockerId: id, message: openBlockers.summaries[i], wave_id: waveId,
+  }));
+  // Deduplicate by message text — a legacy blocker and an SDK blocker with
+  // identical text shouldn't appear twice in the body.
+  const blockerMessages = new Set(filtered.blockers.map((b) => b.message ?? ''));
+  const mergedBlockers = [...filtered.blockers];
+  for (const b of sdkBlockerEntries) {
+    if (!blockerMessages.has(b.message)) mergedBlockers.push(b);
+  }
+  const mergedFiltered = { ...filtered, blockers: mergedBlockers };
+  const status = deriveStatus(mergedFiltered, existing);
+
+  const next = {
+    frontmatter: {
+      wave_id: waveId,
+      status,
+      created_at: existing?.frontmatter?.created_at ?? now,
+      checkpoint_at: now,
+      claims_active: filtered.claims.filter((c) => c.status === 'active').length,
+      findings_recent: filtered.findings.slice(-5).map((f) => quoteYamlStr(f.message ?? '')),
+      // T7: canonical machine-consumed shape — array of stable blocker ids
+      // sourced from decisions.jsonl. Empty when no SDK blockers are open.
+      blockers_open: openBlockers.ids,
+      // Human-readable summary (optional UI), populated from the same SDK
+      // decisions.jsonl records that fed `blockers_open`.
+      blockers_open_summary: openBlockers.summaries,
+      agents: [...new Set(filtered.claims.map((c) => c.agent ?? c.owner).filter(Boolean))],
+    },
+    body: renderBody(mergedFiltered, existing),
+  };
 
   await writeWaveState(waveId, next, projectRoot);
+
+  // Append summary delta when status changes (audit log).
+  const prevStatus = existing?.frontmatter?.status ?? 'new';
+  if (prevStatus !== status) {
+    await appendSummary(
+      waveId,
+      { agent_id: 'checkpointWave', surprises: `status: ${prevStatus} → ${status}` },
+      projectRoot,
+    );
+  }
+
+  // S4 integration: refresh AGENTS.md BLACKBOARD block. Silent on failure —
+  // populating AGENTS.md is advisory and must not block checkpointing.
+  const populateBlackboardBlock = await loadPopulateBlackboardBlock();
+  if (populateBlackboardBlock) {
+    try { await populateBlackboardBlock(waveId, projectRoot); } catch { /* advisory */ }
+  }
+
   return next;
 }

package/src/orchestrator/worktree-provision.js

@@ -0,0 +1,77 @@
+/**
+ * worktree-provision.js — v1.5.0 S2: auto-detect + install deps in a fresh worktree.
+ *
+ * Closes the Step 0 briefing gap: subagents in isolation:worktree get a clean
+ * git checkout but no node_modules/. Without this, every Node-touching subagent
+ * burns its first ~30s npm install-ing.
+ *
+ * Security: uses node:child_process execFile (NO shell, no string concat).
+ * Detector commands + args are frozen literals; cwd is the only per-call
+ * variable and is validated via lstat before invocation. `--ignore-scripts`
+ * is non-negotiable on npm install. A subagent worktree with malicious
+ * package.json {scripts:{preinstall:"..."}} must not execute arbitrary code.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const execFileP = promisify(execFile);
+
+export const DETECTORS = Object.freeze([
+  { name: 'node',   file: 'package.json',   cmd: 'npm',   args: ['install', '--no-audit', '--no-fund', '--ignore-scripts'] },
+  { name: 'python', file: 'pyproject.toml', cmd: 'pip',   args: ['install', '--quiet', '-e', '.'] },
+  { name: 'rust',   file: 'Cargo.toml',     cmd: 'cargo', args: ['fetch'] },
+  { name: 'go',     file: 'go.mod',         cmd: 'go',    args: ['mod', 'download'] },
+]);
+
+export const DEFAULT_PER_INSTALL_MS = 2 * 60 * 1000;
+export const DEFAULT_WALL_MS = 5 * 60 * 1000;
+
+async function firstLevelDirs(root) {
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => join(root, e.name));
+  } catch { return []; }
+}
+
+export async function provisionWorktree(worktreePath, opts = {}) {
+  const detectors = opts.detectors ?? DETECTORS;
+  const perInstallMs = opts.perInstallMs ?? DEFAULT_PER_INSTALL_MS;
+  const wallMs = opts.wallMs ?? DEFAULT_WALL_MS;
+  const deadline = Date.now() + wallMs;
+  const result = { installed: [], skipped: [], failed: [] };
+
+  const candidateDirs = [worktreePath, ...(await firstLevelDirs(worktreePath))];
+
+  for (const det of detectors) {
+    if (Date.now() >= deadline) {
+      result.skipped.push({ name: det.name, reason: 'wall-deadline' });
+      continue;
+    }
+    for (const dir of candidateDirs) {
+      const manifest = join(dir, det.file);
+      if (!existsSync(manifest)) continue;
+      try {
+        const st = await lstat(manifest);
+        if (!st.isFile()) { result.skipped.push({ name: det.name, path: dir, reason: 'not-regular-file' }); continue; }
+      } catch { result.skipped.push({ name: det.name, path: dir, reason: 'lstat-failed' }); continue; }
+
+      const t0 = Date.now();
+      try {
+        await execFileP(det.cmd, det.args, { cwd: dir, timeout: perInstallMs, maxBuffer: 16 * 1024 * 1024 });
+        result.installed.push({ name: det.name, path: dir, ms: Date.now() - t0 });
+      } catch (err) {
+        // execFile timeout surfaces as either err.code === 'ETIMEDOUT' OR
+        // (err.killed && err.signal === 'SIGTERM'/'SIGKILL') depending on
+        // platform/Node version. Detect both to give callers a stable signal.
+        const timedOut = err.code === 'ETIMEDOUT'
+          || (err.killed && (err.signal === 'SIGTERM' || err.signal === 'SIGKILL'));
+        result.failed.push({ name: det.name, path: dir, reason: timedOut ? 'timeout' : (err.code || err.message) });
+      }
+    }
+  }
+  return result;
+}

package/src/override-use-registry.js

@@ -36,6 +36,92 @@ import os from 'node:os';
 
 const SCHEMA_VERSION = '1.0';
 
+// Maximum path length the registry will accept. Practical limits across the
+// supported platforms are PATH_MAX=4096 (Linux), 1024 (macOS), 32767 (Windows
+// long-path). 4096 is a comfortable cap that won't reject any real path but
+// will reject a flood-of-bytes prompt-injection payload.
+const MAX_PROJECT_ROOT_LEN = 4096;
+
+// Unicode tag-block range (U+E0000–U+E007F) — invisible "ASCII Smuggler" code
+// points historically used to hide prompt-injection payloads inside text the
+// model sees but the human doesn't. Closed at the prelude in H1.4; we also
+// reject at registry-write time to prevent contamination at the source.
+// eslint-disable-next-line security/detect-unsafe-regex -- single-char Unicode range class; no quantifier; not backtrack-exploitable
+const UNICODE_TAG_BLOCK_RE = /[\u{E0000}-\u{E007F}]/u;
+
+// ASCII control characters (excluding nothing — \n \r \t \0 etc are ALL
+// rejected when present in a path key).
+// eslint-disable-next-line no-control-regex -- this regex EXISTS to reject control chars; lint hit is a false positive on the gate itself
+const CONTROL_CHAR_RE = /[\x00-\x1F\x7F]/;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * F-SEC-4 (HIGH, update-install-trust audit v1.5.0):
+ * recordOverrideUse persisted any non-empty string as a project key and that
+ * value flows verbatim into the cross-project promote suggestion that lands
+ * in the prelude the model reads — a prompt-injection vector.
+ *
+ * Validate projectRoot is shaped like a real absolute filesystem path with
+ * no `..` segments, no control characters, no Unicode tag-block smuggling
+ * code points, and within a sane length cap. Returns `{ ok: true }` on pass
+ * or `{ ok: false, reason }` on fail. We do NOT throw — the caller in
+ * override-resolver.js wraps the registry write in a non-fatal try/catch
+ * and we want a structured signal instead of a thrown Error so future
+ * callers can surface a clean rejection without try/catch noise.
+ *
+ * @param {unknown} projectRoot
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function validateProjectRoot(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return { ok: false, reason: 'projectRoot must be a non-empty string' };
+  }
+  if (projectRoot.length > MAX_PROJECT_ROOT_LEN) {
+    return {
+      ok: false,
+      reason: `projectRoot exceeds max length ${MAX_PROJECT_ROOT_LEN}`,
+    };
+  }
+  if (!path.isAbsolute(projectRoot)) {
+    return { ok: false, reason: 'projectRoot must be an absolute path' };
+  }
+  // Reject any `..` segment in the RAW path before normalization. path.normalize
+  // would collapse interior `..` (e.g. `/a/../b` -> `/b`) and silently rewrite
+  // the registry key, defeating the validation. A real filesystem path passed
+  // by override-resolver.js is already canonical, so a `..` is a tampering
+  // signal. Split on both POSIX and Windows separators so /a/../b and \a\..\b
+  // are both caught regardless of host platform.
+  const rawSegments = projectRoot.split(/[\\/]/);
+  if (rawSegments.includes('..')) {
+    return { ok: false, reason: 'projectRoot must not contain `..` segments' };
+  }
+  if (CONTROL_CHAR_RE.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain control characters',
+    };
+  }
+  if (UNICODE_TAG_BLOCK_RE.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain Unicode tag-block characters',
+    };
+  }
+  // Reject prompt-injection / markdown / HTML tokens that are not meaningful
+  // in a real path but ARE meaningful when rendered into the prelude. These
+  // are not legal in any reasonable filesystem path.
+  if (/[<>`]/.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain `<`, `>`, or backtick',
+    };
+  }
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers — read os.homedir()/HOME at call time so tests can swap HOME
 // via process.env between calls.
@@ -111,21 +197,31 @@ async function readSettings() {
  * Idempotent — re-recording the same (project, preset) updates applied_at
  * rather than duplicating the entry.
  *
- * @param {string} projectRoot
+ * Returns `{ ok: true }` on success or `{ ok: false, reason }` on validation
+ * failure. Does NOT throw on bad input — the value flows into the prelude
+ * the model reads, so we want every untrusted projectRoot rejected loudly
+ * via the return contract instead of via an unhandled Error.
+ *
+ * @param {string} projectRoot     MUST be an absolute path, no `..`, no
+ *                                 control / Unicode tag-block / HTML chars.
  * @param {string} preset
  * @param {string} scope          'base' | 'user' | 'org' | 'project'
  * @param {string} [project_type] auto-detected project type, defaults to
  *                                whatever is already on file or 'unknown'.
+ * @returns {Promise<{ ok: true } | { ok: false, reason: string }>}
  */
 export async function recordOverrideUse(projectRoot, preset, scope, project_type) {
-  if (typeof projectRoot !== 'string' || !projectRoot) {
-    throw new Error('recordOverrideUse: projectRoot must be a non-empty string');
+  // F-SEC-4 (HIGH): full path validation on projectRoot before it enters the
+  // registry. See validateProjectRoot above for the threat-model rationale.
+  const pathCheck = validateProjectRoot(projectRoot);
+  if (!pathCheck.ok) {
+    return pathCheck;
   }
   if (typeof preset !== 'string' || !preset) {
-    throw new Error('recordOverrideUse: preset must be a non-empty string');
+    return { ok: false, reason: 'preset must be a non-empty string' };
   }
   if (typeof scope !== 'string' || !scope) {
-    throw new Error('recordOverrideUse: scope must be a non-empty string');
+    return { ok: false, reason: 'scope must be a non-empty string' };
   }
 
   const state = await readRegistry();
@@ -153,6 +249,7 @@ export async function recordOverrideUse(projectRoot, preset, scope, project_type
   }
   state.projects[projectRoot] = proj;
   await writeRegistry(state);
+  return { ok: true };
 }
 
 /**
@@ -186,6 +283,9 @@ export async function findProjectsWithOverride(preset) {
   const out = [];
   for (const [project, entry] of Object.entries(state.projects || {})) {
     if (!entry || !Array.isArray(entry.active_overrides)) continue;
+    // F-SEC-4 (HIGH) defense-in-depth: legacy registries written before
+    // v1.5.1 validation could contain unsafe keys. Refuse to surface them.
+    if (!validateProjectRoot(project).ok) continue;
     const hit = entry.active_overrides.find(
       (o) => o && o.preset === preset
     );
@@ -226,6 +326,10 @@ export async function findProjectsWithSimilarOverrideSet(
   for (const [project, entry] of Object.entries(state.projects || {})) {
     if (exclude && project === exclude) continue;
     if (!entry || !Array.isArray(entry.active_overrides)) continue;
+    // F-SEC-4 (HIGH) defense-in-depth: legacy registries written before
+    // v1.5.1 validation could contain unsafe keys that would flow into the
+    // promote suggestion text and the prelude. Refuse to surface them.
+    if (!validateProjectRoot(project).ok) continue;
     const theirs = new Set(
       entry.active_overrides
         .filter((o) => o && typeof o.preset === 'string')
@@ -304,4 +408,6 @@ export const __test = {
   settingsPath,
   readRegistry,
   writeRegistry,
+  validateProjectRoot,
+  MAX_PROJECT_ROOT_LEN,
 };