@dzhechkov/harness-core 0.8.34 → 0.8.36

package/src/skills.ts

@@ -4,8 +4,8 @@
  * @packageDocumentation
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
 
 import { parse as parseYaml } from 'yaml';
 
@@ -55,15 +55,259 @@ function readAssetContent(path: string): { encoding: 'utf-8' | 'base64'; content
   return { encoding: 'utf-8', content: decoded };
 }
 
-/** Recursively list every file under `dir`. */
-function walkFiles(dir: string): string[] {
-  const out: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+/**
+ * One filesystem entry skipped during skill asset discovery, named so nothing
+ * vanishes silently (feature `skills-walk-symlinks-and-junk`, FR-1/FR-2). `path`
+ * is the entry's own path (not its symlink target); `reason` is a short,
+ * stable, human-readable tag: `'junk file (<pattern>)'` (e.g. `'junk file
+ * (*.pyc)'` — fix-round 1 HIGH-1(b): the pattern that matched, not just the
+ * verdict), `'junk directory (<name>)'`, `'broken symlink'`, `'symlink escapes
+ * the skill directory'` (fix-round 1 AM-8), `'symlink cycle — directory
+ * already visited'`, or `'unreadable directory (<errno message>)'` (fix-round
+ * 1 MEDIUM-3).
+ */
+export interface SkippedEntry {
+  readonly path: string;
+  readonly reason: string;
+}
+
+/** The result of {@link walkFiles}: the real assets found, plus everything skipped. */
+export interface SkillWalkResult {
+  readonly files: readonly string[];
+  readonly skipped: readonly SkippedEntry[];
+}
+
+/**
+ * Directory names that never carry legitimate skill assets — build/cache artifacts a
+ * skill author does not intend to ship. **This list IS the published contract for "what
+ * counts as junk"** (fix-round 1 HIGH-1(a), REFUTED-by-contract — see
+ * `packages/@dzhechkov/harness-core/README.md`, "What counts as junk"): a skill cannot
+ * ship a directory bearing one of these exact names as an asset, on purpose or by
+ * accident — that is the deliberate, documented trade the design makes, not an
+ * oversight to be widened into content-sniffing heuristics. NOT a whitelist of allowed
+ * directories: any OTHER name (including a dotdir the author added on purpose) is
+ * walked as usual — filtering a user's own files is not this list's job (FR-2,
+ * requirements AC-1).
+ */
+export const SKILL_JUNK_DIRS: ReadonlySet<string> = new Set([
+  '__pycache__', // Python bytecode cache
+  'node_modules', // an accidentally-vendored dependency tree
+  '.git', // VCS metadata
+  '__MACOSX', // macOS zip-archive resource-fork sidecar directory (fix-round 1 MEDIUM-2)
+  '.pytest_cache', // pytest's cache directory (fix-round 1 MEDIUM-2)
+  '.mypy_cache', // mypy's cache directory (fix-round 1 MEDIUM-2)
+]);
+
+/** Exact junk filenames skipped during skill asset discovery (FR-2). */
+export const SKILL_JUNK_FILES: ReadonlySet<string> = new Set([
+  '.DS_Store', // macOS Finder folder metadata
+  'Thumbs.db', // Windows Explorer thumbnail cache
+]);
+
+/** Junk filename SUFFIXES skipped during skill asset discovery (FR-2). */
+const SKILL_JUNK_FILE_SUFFIXES: readonly string[] = [
+  '.pyc', // Python bytecode
+  '.pyo', // Python optimized bytecode
+  '.swp', // Vim swap file
+  '.swo', // Vim swap file, second form left after a crash recovery (fix-round 1 MEDIUM-2)
+  // A trailing `~` (editor backup) is deliberately NOT on this list (Codex r2 HIGH, lead
+  // decision): it is the one pattern a legitimate asset name can plausibly end with
+  // (`notes~`), and FR-2's list is conservative by contract — a false positive here would
+  // silently drop a real asset, which AC-1 forbids. Backup files ending in `~` ship as assets.
+];
+
+/** Junk filename PREFIXES skipped during skill asset discovery (fix-round 1 MEDIUM-2). */
+const SKILL_JUNK_FILE_PREFIXES: readonly string[] = [
+  '.#', // Emacs lock file (e.g. `.#notes.txt`), left behind by an unclean editor exit
+];
+
+/** True when `name` matches a documented junk-file pattern (FR-2). */
+export function isSkillJunkFile(name: string): boolean {
+  if (SKILL_JUNK_FILES.has(name)) return true;
+  if (SKILL_JUNK_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix))) return true;
+  return SKILL_JUNK_FILE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+/**
+ * The ONE decision point `walkFiles` calls to ask "is this entry junk?" — a directory
+ * check and a file check both funnel through here so a single mutation can prove (or
+ * disprove) that junk filtering, as a whole, is wired in (registry entry
+ * `walk-filters-junk`). Splitting this into two never-both-mutated call sites would let
+ * a mutation of just one half pass unnoticed while the other half still filtered.
+ */
+function isJunkEntry(name: string, kind: 'file' | 'directory'): boolean {
+  return kind === 'directory' ? SKILL_JUNK_DIRS.has(name) : isSkillJunkFile(name);
+}
+
+/**
+ * Which junk PATTERN `name` matched — used to build a `reason` that NAMES the pattern,
+ * not just the verdict (fix-round 1 HIGH-1(b): `'junk file (*.pyc)'`, never a bare
+ * `'junk file'`). Kept separate from {@link isJunkEntry} (the one go/no-go point the
+ * `walk-filters-junk` mutation targets) so a mutation of the decision does not also
+ * have to fake this label to stay silent.
+ */
+function junkPatternLabel(name: string, kind: 'file' | 'directory'): string {
+  if (kind === 'directory') return name;
+  if (SKILL_JUNK_FILES.has(name)) return name;
+  for (const suffix of SKILL_JUNK_FILE_SUFFIXES) {
+    if (name.endsWith(suffix)) return `*${suffix}`;
+  }
+  for (const prefix of SKILL_JUNK_FILE_PREFIXES) {
+    if (name.startsWith(prefix)) return `${prefix}*`;
+  }
+  return name; // unreachable when isJunkEntry(name, kind) is true; kept total, not partial.
+}
+
+/**
+ * True when `targetRealPath` lies within `rootRealDir` — refuses a symlink whose
+ * resolved target escapes the skill directory (lead item AM-8: `assets/secret ->
+ * /etc/hostname`, or `-> ../../..`, must never be followed and bundled as an asset).
+ * Uses `relative()` plus a leading-`..`/absolute check rather than a lexical
+ * `startsWith`, the SAME idiom as `containedUnderRoot` in
+ * `packages/@dzhechkov/harness-cli/src/cli.ts` (read-only reference for technique) —
+ * a lexical string-prefix check is fooled by a sibling directory that happens to share
+ * the root as a text prefix (root `/a/b` vs. target `/a/bc`).
+ */
+function isContained(rootRealDir: string, targetRealPath: string): boolean {
+  if (targetRealPath === rootRealDir) return true;
+  const rel = relative(rootRealDir, targetRealPath);
+  // Codex r2 MEDIUM (lead fix): only a `..` COMPONENT escapes — a file legitimately named
+  // `..asset` yields rel === '..asset', which is inside the root.
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * Recursively list every real, non-junk file under `dir`, resolving symlinks to
+ * their targets and guarding against symlink cycles.
+ *
+ * A `Dirent` from `readdirSync` answers `false` to BOTH `isDirectory()` and
+ * `isFile()` for a symlink entry — trusting those two checks alone silently drops
+ * every symlinked asset (MEASURED: 2 of 4 fixture assets vanished, exit 0). This
+ * resolves each symlink with `statSync` (which follows the link) before deciding
+ * whether it names a file or a directory.
+ *
+ * Cycle guard: each directory's `realpath` is recorded in `seenRealDirs` while
+ * it is being walked and REMOVED again when its walk returns — the set is the
+ * chain of ANCESTORS on the current recursion path, not every directory ever
+ * visited. A directory (reached directly or through a symlink) whose real path is
+ * already on that chain ends the walk there instead of recursing — this is what
+ * stops `a -> ..` from hanging (AC-2; registry entry `walk-guards-cycles`). Two
+ * non-cyclic aliases of the same directory (`alias1 -> shared`, `alias2 -> shared`)
+ * are BOTH walked under their own logical paths (Codex r2 HIGH, lead fix): an
+ * alias is not a cycle, and the earlier visited-set semantics silently dropped the
+ * second one as if it were.
+ *
+ * Containment guard (lead item AM-8): every symlink's resolved target is checked
+ * against `rootRealDir` — the real path of the directory the OUTERMOST call was
+ * given (the skill directory itself, for every caller in this file) — before it is
+ * followed. A symlink whose target resolves outside that root is skipped, named,
+ * never bundled as an asset; `rootRealDir` is threaded through every recursive call
+ * so a nested symlinked directory is still checked against the ORIGINAL skill root,
+ * not against whichever subdirectory happens to be walking it.
+ *
+ * `readdirSync` failure (fix-round 1 MEDIUM-3) — e.g. an unreadable directory whose
+ * own `realpath` still resolved — produces a named `skipped` entry, same as an
+ * unresolvable `realpathSync`; it never throws out of this function or out of
+ * {@link loadSkillFromDir}.
+ */
+export function walkFiles(
+  dir: string,
+  seenRealDirs: Set<string> = new Set<string>(),
+  rootRealDir?: string,
+): SkillWalkResult {
+  const files: string[] = [];
+  const skipped: SkippedEntry[] = [];
+
+  let realDir: string;
+  try {
+    realDir = realpathSync(dir);
+  } catch (error) {
+    skipped.push({ path: dir, reason: `unreadable directory (${error instanceof Error ? error.message : String(error)})` });
+    return { files, skipped };
+  }
+  if (seenRealDirs.has(realDir)) {
+    skipped.push({ path: dir, reason: 'symlink cycle — directory already visited' });
+    return { files, skipped };
+  }
+  seenRealDirs.add(realDir);
+  const root = rootRealDir ?? realDir;
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    skipped.push({ path: dir, reason: `unreadable directory (${error instanceof Error ? error.message : String(error)})` });
+    seenRealDirs.delete(realDir);
+    return { files, skipped };
+  }
+
+  for (const entry of entries) {
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkFiles(full));
-    else if (entry.isFile()) out.push(full);
+
+    if (entry.isSymbolicLink()) {
+      let target;
+      try {
+        target = statSync(full); // follows the link
+      } catch {
+        skipped.push({ path: full, reason: 'broken symlink' });
+        continue;
+      }
+      let resolvedReal: string;
+      try {
+        resolvedReal = realpathSync(full);
+      } catch {
+        // statSync just followed this same link successfully, so this is very unlikely
+        // (a race with something deleting the target); treat it the same as broken.
+        skipped.push({ path: full, reason: 'broken symlink' });
+        continue;
+      }
+      if (!isContained(root, resolvedReal)) {
+        skipped.push({ path: full, reason: 'symlink escapes the skill directory' });
+        continue;
+      }
+      if (target.isDirectory()) {
+        if (isJunkEntry(entry.name, 'directory')) {
+          skipped.push({ path: full, reason: `junk directory (${junkPatternLabel(entry.name, 'directory')})` });
+          continue;
+        }
+        const nested = walkFiles(full, seenRealDirs, root);
+        files.push(...nested.files);
+        skipped.push(...nested.skipped);
+      } else if (target.isFile()) {
+        if (isJunkEntry(entry.name, 'file')) {
+          skipped.push({ path: full, reason: `junk file (${junkPatternLabel(entry.name, 'file')})` });
+          continue;
+        }
+        files.push(full);
+      } else {
+        skipped.push({ path: full, reason: 'symlink target is neither a file nor a directory' });
+      }
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      if (isJunkEntry(entry.name, 'directory')) {
+        skipped.push({ path: full, reason: `junk directory (${junkPatternLabel(entry.name, 'directory')})` });
+        continue;
+      }
+      const nested = walkFiles(full, seenRealDirs, root);
+      files.push(...nested.files);
+      skipped.push(...nested.skipped);
+    } else if (entry.isFile()) {
+      if (isJunkEntry(entry.name, 'file')) {
+        skipped.push({ path: full, reason: `junk file (${junkPatternLabel(entry.name, 'file')})` });
+        continue;
+      }
+      files.push(full);
+    } else {
+      skipped.push({ path: full, reason: 'not a regular file, directory, or symlink' });
+    }
   }
-  return out;
+
+  // Ancestor-chain semantics (see the cycle-guard doc above): this directory's walk is
+  // over, so a sibling alias of it must be allowed to walk it again under its own path.
+  seenRealDirs.delete(realDir);
+  return { files, skipped };
 }
 
 /** Return the ids of every `<skillsDir>/<id>/SKILL.md`, sorted. */
@@ -88,6 +332,9 @@ export function discoverSkillIds(skillsDir: string): string[] {
  */
 export function listSkills(skillsDir: string): SkillSummary[] {
   return discoverSkillIds(skillsDir).map((id) => {
+    // Codex r3 (lead fix): the SKILL.md containment check guards EVERY public reader, not
+    // only loadSkillFromDir/getSkillInfo — an escaping SKILL.md symlink is refused here too.
+    assertSkillMdContained(join(skillsDir, id), join(skillsDir, id, 'SKILL.md'), id);
     const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
     const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
     return { id, description: frontmatter.description };
@@ -146,6 +393,9 @@ export function describeSkillLoadFailure(
   const path = join(skillsDir, id, 'SKILL.md');
   let firstLine = '';
   try {
+    // Codex r3 (lead fix): never read an ESCAPING SKILL.md even for a diagnostic snippet —
+    // the first line of a file outside the skill directory is not ours to print.
+    assertSkillMdContained(join(skillsDir, id), path, id);
     const raw = readFileSync(path, 'utf-8');
     const line = (raw.split('\n', 1)[0] ?? '').replace(/\r$/, '').trim();
     firstLine =
@@ -176,6 +426,8 @@ export function listSkillsDetailed(skillsDir: string): SkillListing {
   const failures: SkillLoadFailure[] = [];
   for (const id of discoverSkillIds(skillsDir)) {
     try {
+      // Codex r3 (lead fix): refused BEFORE the read; the throw lands in `failures` below.
+      assertSkillMdContained(join(skillsDir, id), join(skillsDir, id, 'SKILL.md'), id);
       const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
       const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
       skills.push({ id, description: frontmatter.description });
@@ -258,15 +510,36 @@ export function formatSkillApplyFailures(failures: readonly SkillApplyFailure[])
 }
 
 /** Get detailed info about a single skill without loading all assets. */
+/**
+ * Codex r2 CRITICAL (lead fix, AM-8 completed): the walk's containment guard runs AFTER
+ * `SKILL.md` has already been read, so a `SKILL.md` that is itself a symlink escaping
+ * the skill directory (`SKILL.md -> /etc/motd`, `-> ../../outside.md`) was followed and
+ * installed regardless. `SKILL.md` is mandatory, so an escaping one cannot be "skipped" —
+ * the whole skill is REFUSED with a named reason, never loaded from outside its directory.
+ * An in-tree `SKILL.md` symlink (a real file elsewhere inside the same skill directory)
+ * still loads. Returns nothing; throws on escape.
+ */
+function assertSkillMdContained(skillDir: string, skillMdPath: string, id: string): void {
+  if (!lstatSync(skillMdPath).isSymbolicLink()) return;
+  const rootReal = realpathSync(skillDir);
+  const targetReal = realpathSync(skillMdPath);
+  if (!isContained(rootReal, targetReal)) {
+    throw new Error(
+      `skill ${JSON.stringify(id)}: SKILL.md is a symlink escaping the skill directory (-> ${targetReal}) — refused`,
+    );
+  }
+}
+
 export function getSkillInfo(skillsDir: string, id: string): SkillInfo | undefined {
   const skillDir = join(skillsDir, id);
   const skillMdPath = join(skillDir, 'SKILL.md');
   if (!existsSync(skillMdPath)) return undefined;
+  assertSkillMdContained(skillDir, skillMdPath, id);
   const document = parseSkillDocument(readFileSync(skillMdPath, 'utf-8'));
   const fm = parseYaml(document.frontmatterYaml) as Record<string, unknown>;
   const parsed = ClaudeSkillFrontmatterSchema.parse(fm);
   const assetPaths = walkFiles(skillDir)
-    .filter((p) => p !== skillMdPath)
+    .files.filter((p) => p !== skillMdPath)
     .map((p) => relative(skillDir, p).split('\\').join('/'))
     .sort();
   return {
@@ -281,21 +554,35 @@ export function getSkillInfo(skillsDir: string, id: string): SkillInfo | undefin
   };
 }
 
+/**
+ * A {@link CanonicalSkill} plus, optionally, the {@link SkippedEntry} list
+ * {@link loadSkillFromDir} collected while walking the skill's directory. The
+ * field is additive and optional — a `CanonicalSkill`-typed caller (every
+ * adapter, every existing consumer) sees exactly the shape it always saw;
+ * only a caller that reads `.skipped` learns about junk/broken-symlink skips.
+ */
+export type LoadedSkill = CanonicalSkill & { readonly skipped?: readonly SkippedEntry[] };
+
 /**
  * Load one `<skillsDir>/<id>/` directory into a {@link CanonicalSkill}: its
- * `SKILL.md` document plus every other file as a bundled asset.
+ * `SKILL.md` document plus every other file as a bundled asset. Junk entries
+ * and broken/cyclic symlinks encountered along the way are named in
+ * `.skipped` (feature `skills-walk-symlinks-and-junk`, FR-1/FR-2) — omitted
+ * entirely when nothing was skipped, never a silent drop.
  *
  * @throws if the skill directory has no `SKILL.md`.
  */
-export function loadSkillFromDir(skillsDir: string, id: string): CanonicalSkill {
+export function loadSkillFromDir(skillsDir: string, id: string): LoadedSkill {
   const skillDir = join(skillsDir, id);
   const skillMdPath = join(skillDir, 'SKILL.md');
   if (!existsSync(skillMdPath)) {
     throw new Error(`skill not found: ${JSON.stringify(id)} (looked in ${skillsDir})`);
   }
+  assertSkillMdContained(skillDir, skillMdPath, id);
   const document = parseSkillDocument(readFileSync(skillMdPath, 'utf-8'));
   const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
-  const assets: SkillAsset[] = walkFiles(skillDir)
+  const walk = walkFiles(skillDir);
+  const assets: SkillAsset[] = walk.files
     .filter((path) => path !== skillMdPath)
     .map((path) => {
       const { encoding, content } = readAssetContent(path);
@@ -306,5 +593,7 @@ export function loadSkillFromDir(skillsDir: string, id: string): CanonicalSkill
       };
     })
     .sort((a, b) => a.path.localeCompare(b.path));
-  return { id, frontmatter, document, assets };
+  return walk.skipped.length > 0
+    ? { id, frontmatter, document, assets, skipped: walk.skipped }
+    : { id, frontmatter, document, assets };
 }

package/src/vector-tier.ts

@@ -69,6 +69,7 @@ import {
   reindexAgentdbRows,
   readAgentdbRowsByTaskType,
   DZ_OWNED_TASK_TYPES,
+  readStoreGeneration,
 } from './agentdb-index.js';
 // smart-backlog (ADR-001/005 lifecycle): `dz vector reindex` must re-embed dz-backlog rows too, or
 // they rot in a stale embedding space after a model bump. One-directional import — backlog.ts imports
@@ -857,12 +858,17 @@ interface EngineCacheEntry {
   readonly stat: AgentdbDbStat;
 }
 
-/** The three independent invalidation signals AM-6 asks for, plus the recency stamp
+/** The four independent invalidation signals: the three AM-6 asks for (mtime/size/inode) PLUS the
+ * store's own write-generation counter (`store-generation-counter`, FR-2) — a same-size same-tick
+ * temp+rename replace can still leave mtime/size/inode all coincidentally unchanged on a coarse
+ * filesystem, but `indexPatternsToAgentdb` bumps the generation on every real write, so it is the
+ * one signal that can never coincidentally match a stale cache entry. Plus the recency stamp
  * {@link touchEngineCacheEntry} needs for the bounded-size eviction below. */
 interface AgentdbDbStat {
   readonly mtimeMs: number;
   readonly size: number;
   readonly ino: number;
+  readonly generation: number;
   lastUsedAt: number;
 }
 
@@ -897,21 +903,25 @@ function engineCacheKey(projectRoot: string): string {
 
 /** stat facts of `<root>/.dz/agentdb.db`, or `-1`/`-1`/`-1` when absent — a distinct, stable cache
  * key for "no store yet" so a project that later gains a store is never confused with one that
- * never had (statSync's own floor is mtime 0). Never throws. */
-function agentdbDbStat(projectRoot: string): { mtimeMs: number; size: number; ino: number } {
+ * never had (statSync's own floor is mtime 0). `generation` is read regardless of whether the stat
+ * itself succeeded (`readStoreGeneration` already degrades a missing/corrupt counter file to `0`,
+ * FR-2's compatibility floor for a pre-existing store). Never throws. */
+function agentdbDbStat(projectRoot: string): { mtimeMs: number; size: number; ino: number; generation: number } {
+  const generation = readStoreGeneration(projectRoot);
   try {
     const st = statSync(join(projectRoot, '.dz', 'agentdb.db'));
-    return { mtimeMs: st.mtimeMs, size: st.size, ino: st.ino };
+    return { mtimeMs: st.mtimeMs, size: st.size, ino: st.ino, generation };
   } catch {
-    return { mtimeMs: -1, size: -1, ino: -1 };
+    return { mtimeMs: -1, size: -1, ino: -1, generation };
   }
 }
 
-/** True when NONE of the three independent signals changed — the only case where a cached engine
- * may still be trusted (AM-6). Any one of them differing (a same-tick replace still bumps size or
- * gets a fresh inode from a temp+rename write) forces a re-resolve. */
-function agentdbDbStatUnchanged(a: AgentdbDbStat, b: { mtimeMs: number; size: number; ino: number }): boolean {
-  return a.mtimeMs === b.mtimeMs && a.size === b.size && a.ino === b.ino;
+/** True when NONE of the four independent signals changed — the only case where a cached engine
+ * may still be trusted (AM-6, and `store-generation-counter` FR-2). Any one of them differing (a
+ * same-tick replace still bumps size or gets a fresh inode from a temp+rename write, and every real
+ * write bumps the generation regardless) forces a re-resolve. */
+function agentdbDbStatUnchanged(a: AgentdbDbStat, b: { mtimeMs: number; size: number; ino: number; generation: number }): boolean {
+  return a.mtimeMs === b.mtimeMs && a.size === b.size && a.ino === b.ino && a.generation === b.generation;
 }
 
 /** Evict the least-recently-used entry once the cache is at capacity — called only on a genuine
@@ -1148,13 +1158,87 @@ export interface RankedPattern {
 
 const RRF_K = 60;
 
+/**
+ * One entry in the total order every post-merge ranking step shares (feature
+ * `recall-parity-tie-break`, FR-1). `evidence` is the SAME three-way rank `mergeHybridHits` has
+ * always used (`both` < lexical-only < semantic-only — lower is stronger), computed once by
+ * {@link evidenceRank} from a hit's `backend`.
+ */
+export interface HybridOrderKey {
+  readonly score: number;
+  readonly evidence: number;
+  readonly dzId: string;
+}
+
+/** `both` outranks lexical-only outranks semantic-only (mergeHybridHits' own rule, ADR-001 AM-4). */
+export function evidenceRank(backend: RecallHit['backend']): number {
+  return backend === 'both' ? 0 : backend === 'vector' ? 2 : 1;
+}
+
+/**
+ * The ONE deterministic total order recall uses at every step where a tie can occur: fused score
+ * DESC, then EVIDENCE (both > lexical-only > semantic-only), then `dzId` ASC. `mergeHybridHits`
+ * always applied exactly this rule inline; it is exported here (FR-1) so `dampQuarantined`,
+ * `orderHitsForReRank` (the pre-sort `enhance()` runs before its reinforcement/bandit re-rank) and
+ * any other post-merge sort can share the SAME tiebreak instead of an ad hoc score-only comparator
+ * that is deterministic only because its input already arrived pre-ordered — a property that
+ * silently breaks the moment an upstream step feeds it hits in a different order
+ * (recall-parity-tie-break T0: MEASURED, `apply-leg-recall-parity.test.ts` AM-4, a racy
+ * reinforcement-signal read, not a comparator defect, actually explained the observed tail swap —
+ * this comparator is hardening kept from that round; the actual causal fix, per fix-round 1, is the
+ * byte-level store snapshot AM-4 now takes, not this comparator and not an awaited flush).
+ *
+ * FINITE-NUMBER INVARIANT (fix-round 1, LOW finding): plain subtraction (`b.score - a.score`) is
+ * NOT total over `number` — `NaN - x` is `NaN`, and the `||` chain treats a `NaN` term as falsy,
+ * silently SKIPPING it and falling through to the next key as if score had never been compared.
+ * Both terms below use explicit `>`/`<` comparisons instead (correct as-is for ±Infinity — IEEE 754
+ * orders infinities correctly) plus an explicit NaN case: a `NaN` score or evidence is the WEAKEST
+ * possible value on its own axis, so it sorts deterministically LAST, never a coincidental tie.
+ */
+function compareScoreDesc(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? 1 : -1;
+  return a > b ? -1 : a < b ? 1 : 0;
+}
+function compareEvidenceAsc(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? 1 : -1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+export function compareHybridHits(a: HybridOrderKey, b: HybridOrderKey): number {
+  return compareScoreDesc(a.score, b.score)
+    || compareEvidenceAsc(a.evidence, b.evidence)
+    || (a.dzId < b.dzId ? -1 : a.dzId > b.dzId ? 1 : 0);
+}
+
+/**
+ * Sorts `hits` into the shared total order {@link compareHybridHits} defines — used by `enhance()`
+ * BEFORE its reinforcement/bandit re-rank runs (`applyLearningSignalsWithTerms` et al.,
+ * `learning-backend.ts`, out of this fix's edit scope). That re-rank sorts by an ADJUSTED score
+ * with a STABLE tie-break on each hit's ORIGINAL array position — so pre-ordering the input here
+ * makes any tie in the adjusted score resolve in the SAME evidence/dzId order `compareHybridHits`
+ * would give directly, without touching the re-rank's own internals.
+ *
+ * This closes the ordering gap `enhance()` had (recall-parity-tie-break fix-round 1, HIGH finding):
+ * `dampQuarantined` only ran {@link compareHybridHits} when `memory.learning.quarantine` was ON;
+ * with it OFF (the default), `enhance()`'s final order was whatever the re-rank's own
+ * original-index tie-break happened to preserve — invisible from the printed `score` column,
+ * because the re-rank reorders the hit array but never rewrites `.score`. Real (non-tied) score
+ * differences from reinforcement/bandit re-ranking are UNCHANGED by this — it only decides ties.
+ */
+export function orderHitsForReRank(hits: readonly HybridHit[], idOf: (p: PatternRecord) => string): HybridHit[] {
+  return [...hits].sort((a, b) => compareHybridHits(
+    { score: a.score, evidence: evidenceRank(a.backend), dzId: idOf(a.pattern) },
+    { score: b.score, evidence: evidenceRank(b.backend), dzId: idOf(b.pattern) },
+  ));
+}
+
 /**
  * Reciprocal Rank Fusion merge: `score(p) = Σ 1/(60 + rank)` over the lists containing `p`
  * (semantic ranks weighted by `semanticWeight`). Dedup by id; `backend: 'both'` when a pattern
  *
- * Ordering: fused score, then EVIDENCE (`both` before lexical-only before semantic-only), then id.
- * When `semanticWeight > 1` the lexical top-1 is guaranteed a place in the result, taken from the
- * last seat unless that seat holds a `both` hit. See `features/semantic-keeps-exact-hits`.
+ * Ordering: fused score, then EVIDENCE (`both` before lexical-only before semantic-only), then id
+ * — {@link compareHybridHits}. When `semanticWeight > 1` the lexical top-1 is guaranteed a place in
+ * the result, taken from the last seat unless that seat holds a `both` hit. See
+ * `features/semantic-keeps-exact-hits`.
  *
  * appears in both lists. DETERMINISTIC (AC-6): ties break on id, so fixed inputs always yield
  * the same ordering. Pure — no I/O.
@@ -1186,12 +1270,14 @@ export function mergeHybridHits(
   });
   // Ties break by EVIDENCE, not by the id alphabet: a hit both legs found outranks one only a single
   // leg found. Before this, an exact-term match lost a tie to an arbitrary semantic hit purely
-  // because its id sorted later (ADR-001 AM-4).
-  const evidence = (v: Acc): number => (v.lex !== undefined && v.sem ? 0 : v.lex !== undefined ? 1 : 2);
+  // because its id sorted later (ADR-001 AM-4). Now routed through the shared {@link
+  // compareHybridHits} (FR-1) — same three-part rule, no behaviour change.
+  const evidenceOfAcc = (v: Acc): number => evidenceRank(v.lex !== undefined && v.sem ? 'both' : v.lex ?? 'vector');
   const ordered = [...acc.entries()]
-    .sort((a, b) => b[1].score - a[1].score
-      || evidence(a[1]) - evidence(b[1])
-      || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    .sort((a, b) => compareHybridHits(
+      { score: a[1].score, evidence: evidenceOfAcc(a[1]), dzId: a[0] },
+      { score: b[1].score, evidence: evidenceOfAcc(b[1]), dzId: b[0] },
+    ));
   const toHit = ([, v]: [string, Acc]): HybridHit => ({
     pattern: v.pattern,
     backend: v.lex !== undefined && v.sem ? ('both' as const) : v.lex ?? ('vector' as const),
@@ -1246,6 +1332,27 @@ export function mergeHybridHits(
  *
  * `bandit` is passed ONLY when `memory.learning.banditRerank` is armed; when it is absent this
  * function is byte-identical to its pre-feature self — no state file, no lock, no allocation.
+ *
+ * `backend.train()` fires FIRE-AND-FORGET (`void backend.train().catch(() => undefined)`) — this is
+ * a REVERT (recall-parity-tie-break, fix-round 1, MEDIUM finding). An intermediate version of this
+ * fix AWAITED the flush, on the theory that a caller's own reinforcement write landing before it got
+ * an answer would remove the race `apply-leg-recall-parity.test.ts` AM-4 was catching (two tail hits
+ * swapping order between the daemon's `op:recall` reply and a `dz recall --json` invoked a moment
+ * later — MEASURED byte-identical `score` fields, only `uses` differed, so the merge/comparator was
+ * never the cause). MEASURED (lead, 2026-09-15 15:57, temp project, 8 lexical hits, 5 warm runs):
+ * `recallHybrid` took 2 ms with `onRecallHits:false` (no flush at all) vs 57–131 ms with the flush
+ * AWAITED — landing INSIDE the hook's 500 ms `HOOK_RECALL_BUDGET_MS` but a real, avoidable tax on
+ * every recall, for a property the await did not even fully deliver: the awaited write still let a
+ * CLI invoked immediately after the daemon see the DAEMON'S OWN just-computed exposure for that same
+ * query, answering a subtly different question than the daemon had. AM-4 now proves parity by taking
+ * a byte-level SNAPSHOT of the store BEFORE each query's daemon call and pointing `dz recall --json`
+ * at the frozen snapshot (`--project <snapshot>`) — both sides then answer the identical question
+ * from the identical state under PRODUCTION defaults (`onRecallHits` ON), and no write, awaited or
+ * not, can reach the CLI's read. That snapshot is what actually closes the race; this function stays
+ * fire-and-forget, exactly as it always was, because the snapshot makes its timing irrelevant to the
+ * test. `test/lesson-bandit-byte-identity.test.ts` documents the same underlying race in its own
+ * fixture comment and works around it with `onRecallHits: false` there — a narrower, still-valid
+ * isolation for a different test's needs.
  */
 function markRecallHits(
   projectRoot: string,
@@ -1346,7 +1453,15 @@ export async function recallHybrid(
         const q = rec !== undefined && readQuarantineState(rec).quarantined;
         return q ? { ...h, score: h.score * memCfg.quarantineDamp, quarantined: true as const } : h;
       })
-      .sort((a, b) => b.score - a.score);
+      // FR-1 (recall-parity-tie-break): score-only used to rely on the INCOMING array already
+      // being pre-ordered (native Array.sort is stable, so a genuine tie only stayed put by
+      // accident of arrival order). Routed through the same {@link compareHybridHits} the merge
+      // uses, so damping two equally-scored hits can never reorder them differently from how the
+      // merge itself would have.
+      .sort((a, b) => compareHybridHits(
+        { score: a.score, evidence: evidenceRank(a.backend), dzId: idOf(a.pattern) },
+        { score: b.score, evidence: evidenceRank(b.backend), dzId: idOf(b.pattern) },
+      ));
   };
   // lesson-bandit-rerank (ADR-001): the payoff axis. Resolved ONCE per recall; `enabled:false` ⇒
   // the Lesson Payoff context is NEVER CONSTRUCTED — the branch is taken BEFORE any work, so the
@@ -1356,7 +1471,15 @@ export async function recallHybrid(
   let banditReport: BanditRecallReport | undefined;
   let banditExplored: readonly string[] = [];
   const enhance = (hits: readonly HybridHit[]): HybridHit[] => {
-    const candidates = hits.map((h) => {
+    // FR-1 (recall-parity-tie-break, fix-round 1, HIGH finding): pre-sort into the shared total
+    // order BEFORE the reinforcement/bandit re-rank runs — see {@link orderHitsForReRank}.
+    // Why the pre-sort is sufficient and not "reliance on a stable sort" (Codex round 2): the
+    // re-rank's own sort in learning-backend.ts is `b.adjusted - a.adjusted || a.i - b.i` — an
+    // EXPLICIT tie-break on the incoming index, so an adjusted-score tie resolves to exactly the
+    // order built here (score → evidence → dzId), by construction, on any engine. That generic
+    // function only knows `score`, so it cannot call compareHybridHits itself.
+    const ordered = orderHitsForReRank(hits, idOf);
+    const candidates = ordered.map((h) => {
       const dzId = idOf(h.pattern);
       const rec = idToRecord.get(dzId);
       return { dzId, score: h.score, reinforcement: rec !== undefined ? readReinforcementState(rec) : undefined };
@@ -1382,8 +1505,8 @@ export async function recallHybrid(
         ? []
         : [{ id: 'delta', byIndex: candidates.map((c) => deltaMap.get(c.dzId) ?? 0), cap: REINFORCE_RRF_CAP }];
       // The SAME ranking without the payoff term — the only honest way to say what the term moved.
-      const before = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, baseTerms));
-      const after = dampQuarantined(applyLearningSignalsWithTerms(hits, learning, candidates, REINFORCE_RRF_CAP, [
+      const before = dampQuarantined(applyLearningSignalsWithTerms(ordered, learning, candidates, REINFORCE_RRF_CAP, baseTerms));
+      const after = dampQuarantined(applyLearningSignalsWithTerms(ordered, learning, candidates, REINFORCE_RRF_CAP, [
         ...baseTerms,
         // ADDED, never assigned, and pre-bounded to [-1,+1] by the ACL — so `squash` is identity and
         // `cap` is an EXACT bound on this term's contribution (INV-4).
@@ -1413,9 +1536,9 @@ export async function recallHybrid(
     }
     if (deltaMap !== undefined) {
       const deltaByIndex = candidates.map((c) => deltaMap.get(c.dzId) ?? 0);
-      return dampQuarantined(applyLearningSignalsWithDelta(hits, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
+      return dampQuarantined(applyLearningSignalsWithDelta(ordered, learning, candidates, REINFORCE_RRF_CAP, deltaByIndex, REINFORCE_RRF_CAP));
     }
-    return dampQuarantined(applyLearningSignals(hits, learning, candidates, REINFORCE_RRF_CAP));
+    return dampQuarantined(applyLearningSignals(ordered, learning, candidates, REINFORCE_RRF_CAP));
   };
   /** The exposure/telemetry payload for `markRecallHits` — `undefined` while disarmed (INV-1). */
   const banditEmission = (): { readonly contextKey: string; readonly explored: readonly string[]; readonly moved: number; readonly arms: number; readonly deferred?: boolean } | undefined =>