@dzhechkov/harness-core 0.8.34 → 0.8.36

package/src/apply-leg.ts

@@ -27,10 +27,16 @@
  * @packageDocumentation
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { connect as netConnect } from 'node:net';
-import { join } from 'node:path';
+// `node:os` is NOT one of the modules `countIoImports` (core-boundary.ts) tracks — free to import
+// (core-boundary.test.ts's ratchet only counts fs/child_process/https). `probeApplyLeg`'s temp probe
+// cwd reuses the existing top-level 'node:fs' import above (mkdtempSync/rmSync added to that SAME
+// import statement, not a new one) so the ratchet stays at its pinned files:63 imports:69.
+import { tmpdir, uptime } from 'node:os';
+import { join, resolve } from 'node:path';
 import { hookCommandsOf } from './managed-hooks.js';
+import { patternRecordId, recordPattern, removePatternsByIds, loadStorePatternsSync, type PatternRecord, type RemovePatternsResult } from './patterns.js';
 
 /**
  * FR-6 (feature `hook-recall-hybrid-parity`, ADR-001 C-4): send ONE `op: recall` probe to a LIVE
@@ -140,8 +146,52 @@ export function probeRecallEngine(socketPath: string, timeoutMs = 1000): Promise
  * fallback rather than a bare protocol error (AM-3); (d) reports the RAW core RRF score, unchanged,
  * instead of a locally re-normalized [0,1] value (AM-5) — the hook's own `HOOK_SCORE_FLOOR` default
  * moved from `0.01` to `0.005` to match (see that constant's own comment for the measurement).
+ *
+ * Bumped 6→7 (feature `apply-leg-install-root`, ADR-001 D1): both generated files now resolve
+ * `PROJECT` install-root-first (`INSTALL_ROOT` = this file's own location, when it owns a `.dz/`)
+ * instead of trusting a foreign session's `CLAUDE_PROJECT_DIR`/cwd (issue #2) — the hook's own
+ * `[dz-recall]` diagnostic line also gains `root=<path> (install|env|cwd)`.
+ *
+ * Bumped 7→8 (`apply-leg-install-root`, fix round 1, AM-7 HIGH — real regression MEASURED via
+ * `retro-debt-hook.test.ts` going 4/5 red on the v7 hub helper): `PROJECT` install-root-first is
+ * correct for the STORE (pattern db, socket, daemon script) but WRONG for a per-session artifact —
+ * the narrated-error retro-debt sentinel (`retro-pending.json`) is written by the INVOKING
+ * SESSION's own Stop hook under `CLAUDE_PROJECT_DIR`, not under wherever the hook happens to be
+ * installed; a shared $HOME install made the hook look for a foreign session's sentinel under the
+ * install root and silently drop every session's own debt confrontation. Split: `PROJECT` (install-
+ * root-first) stays the STORE root; a new `SESSION_ROOT` (`CLAUDE_PROJECT_DIR || cwd()`, the
+ * pre-feature resolution, unchanged) is the root for `RETRO_PENDING` — the ONE per-session file this
+ * hook reads (every other `PROJECT`-derived path in this file names the store, the daemon, or the
+ * harness-core install, confirmed by grep against every `path.join(PROJECT, …)` site). The diag line
+ * gains `session=<path>` alongside the existing `root=<path> (…)`.
+ *
+ * Bumped 8→9 (feature `apply-leg-never-silent`, ADR-001 D2, FR-1): every early return in `main()`
+ * now prints `[dz-recall] skipped reason=<store-not-found|socket-absent|core-unavailable|
+ * empty-prompt|no-hits> root=<path> (…) session=<path>` on stderr before returning — the hook used
+ * to exit silently on every one of these paths, indistinguishable (from stderr alone) from a
+ * correctly-quiet "nothing relevant" outcome. `embedDaemonSource`'s own bytes are UNCHANGED by this
+ * bump; the shared version number still advances because both helpers are upgraded as one unit by
+ * `dz setup`/`applyLegStatus`.
+ *
+ * Bumped 9→10 (`apply-leg-never-silent`, fix round 1 — cross-model review AM-3/AM-6): (a) the hook
+ * now tags its `op: recall` request with `probe: <bool>` (true only when
+ * `DZ_HOOK_LIVENESS_PROBE=1`, the env {@link "./operations.js".probeHookLiveness} already stamps on
+ * every live-probe spawn) so the daemon can tell a genuine session prompt apart from
+ * `probeApplyLeg`'s own beacon query — AM-3: a beacon written for the ~8s of a doctor/parity probe
+ * used to be recallable by ANY concurrent real prompt in the SAME project, a probe-only fixture
+ * leaking into a real session's context; (b) `askDaemon`'s every failure path used to collapse into
+ * one `undefined`, forcing the hook's own `skip('socket-absent')` call regardless of what actually
+ * went wrong — AM-6: it now returns a tagged `{error: 'socket-absent'|'connect-refused'|
+ * 'daemon-timeout'|'bad-reply'}` so the stderr reason names the ACTUAL failure (no socket file vs a
+ * non-socket file at that path vs a listener that never replies vs a listener that replies with
+ * something unparseable/shapeless). `embedDaemonSource`'s bytes also change for AM-3: `loadPatterns`
+ * now reads each row's `domain` out of the SAME metadata JSON `dzIdOf`/`quarantinedOf` already
+ * parse (the vector mirror carries no separate domain column), and both `hybridRecall`'s hits and
+ * the cosine-fallback `scored` array are filtered to exclude `domain === 'apply-leg-probe'` unless
+ * the request carried `probe: true` — a probe's own beacon still needs to reach ITS query, only a
+ * REAL prompt must never see it.
  */
-export const APPLY_LEG_VERSION = 6;
+export const APPLY_LEG_VERSION = 10;
 
 /**
  * Parse the `dz-apply-leg-version` stamp from a deployed helper file. Unlike
@@ -231,7 +281,24 @@ const crypto = require('node:crypto');
 const os = require('node:os');
 const { pathToFileURL } = require('node:url');
 
-const PROJECT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+// FR-1 (ADR-001 D1, apply-leg-install-root): resolve OUR OWN store from where this hook is
+// INSTALLED, not from whatever project the invoking session happens to be in — a hook installed at
+// $HOME (a common single-machine layout: \`dz setup --target claude --memory agentdb --project
+// $HOME\`, expecting the leg everywhere) used to silently look up a DIFFERENT project's \`.dz/\`
+// whenever CLAUDE_PROJECT_DIR pointed elsewhere (issue #2, MEASURED). Precedent:
+// claude-hooks-assets.ts's \`path.resolve(__dirname, '..', '..')\` for the destructive-guard hook.
+// Order: INSTALL_ROOT (if it owns a \`.dz/\`) -> CLAUDE_PROJECT_DIR -> cwd.
+const INSTALL_ROOT = path.resolve(__dirname, '..', '..');
+const ROOT_SOURCE = fs.existsSync(path.join(INSTALL_ROOT, '.dz')) ? 'install' : (process.env.CLAUDE_PROJECT_DIR ? 'env' : 'cwd');
+const PROJECT = ROOT_SOURCE === 'install' ? INSTALL_ROOT : (process.env.CLAUDE_PROJECT_DIR || process.cwd());
+// AM-7 (fix round 1, apply-leg-install-root): PROJECT above is the STORE root (install-first) — a
+// pattern db shared across every session at a $HOME install is correctly install-scoped. A
+// per-session ARTIFACT is the opposite: the retro-debt sentinel is written by THIS SESSION's own
+// Stop hook under its own CLAUDE_PROJECT_DIR, so looking it up under a foreign install root finds
+// nothing (or, worse, another session's leftover file) and silently drops the confrontation.
+// SESSION_ROOT is the pre-feature resolution, unchanged — the root for any file that belongs to the
+// INVOKING session rather than to the store.
+const SESSION_ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const CORE_DIST_DIR = ${coreDistDir === null ? 'null' : JSON.stringify(coreDistDir)};
 
 // embed-socket-short-path (FR-1/FR-2): byte-for-byte the same logic as \`resolveEmbedSocketPath\` /
@@ -267,6 +334,11 @@ function resolveEffectiveEmbedSocketPath(projectRoot, env) {
   return pointer !== undefined && fs.existsSync(pointer) ? { path: pointer, reason: 'tmpdir-short' } : resolved;
 }
 const SOCKET = resolveEffectiveEmbedSocketPath(PROJECT, process.env).path;
+// AM-3 (fix round 1, apply-leg-never-silent): set ONLY by probeHookLiveness (operations.ts) on
+// every live-probe spawn — never by a real Claude Code session. Rides into the daemon's op:recall
+// request as \`probe\` so the daemon can admit the probe's OWN beacon (domain=apply-leg-probe)
+// without ever surfacing it to a concurrent real prompt in the same project.
+const IS_LIVENESS_PROBE = process.env.DZ_HOOK_LIVENESS_PROBE === '1';
 const USAGE_LOG = process.env.DZ_RECALL_USAGE_LOG || path.join(PROJECT, '.dz', 'recall-usage.jsonl');
 // Measured (2026-09-14, apply-leg-socket.test.ts): an ordinary hook round-trip (spawn + one socket
 // op) took 81-121 ms; 800 ms leaves a wide margin for a loaded daemon while still bounding the AM-2
@@ -359,7 +431,9 @@ async function loadPolicy() {
  *  - stale / other-session sentinel ⇒ '' (the debt belongs to a dead session; retro collected it);
  *  - core module absent or old (no directive exports) ⇒ '' — inert, NEVER-BLOCK.
  */
-const RETRO_PENDING = path.join(PROJECT, '.dz', 'retro-pending.json');
+// AM-7 (fix round 1): SESSION_ROOT, not PROJECT — the sentinel is a per-session artifact (see the
+// SESSION_ROOT comment above).
+const RETRO_PENDING = path.join(SESSION_ROOT, '.dz', 'retro-pending.json');
 async function retroDebtDirective(payload) {
   if (!fs.existsSync(RETRO_PENDING)) return '';
   const sentinel = safe(() => JSON.parse(fs.readFileSync(RETRO_PENDING, 'utf-8')), undefined);
@@ -414,9 +488,13 @@ function readLogTail(chain, file) {
 // FR-6 (hook-recall-hybrid-parity): the reply now carries \`engine\`/\`reason\` alongside \`hits\` —
 // returned as a small object rather than the bare hit array, so the caller can apply the RIGHT
 // floor (FR-5) and print the engine to stderr ONLY (never into the injected context, FR-2).
+// AM-6 (fix round 1): every failure used to collapse into one \`undefined\`, forcing the caller's
+// \`skip('socket-absent')\` regardless of whether the socket was truly absent, refused the connect,
+// never replied, or replied with garbage. Each branch now tags its OWN reason so the stderr line
+// (and, through it, \`probeApplyLeg\`'s parsed reason) names what actually happened.
 function askDaemon(prompt) {
   return new Promise((resolve) => {
-    if (!fs.existsSync(SOCKET)) return resolve(undefined);
+    if (!fs.existsSync(SOCKET)) return resolve({ error: 'socket-absent' });
     let settled = false;
     const done = (v) => {
       if (settled) return;
@@ -425,29 +503,29 @@ function askDaemon(prompt) {
       resolve(v);
     };
     const sock = net.connect(SOCKET);
-    const timer = setTimeout(() => done(undefined), TIMEOUT_MS);
+    const timer = setTimeout(() => done({ error: 'daemon-timeout' }), TIMEOUT_MS);
     timer.unref?.();
     let buf = '';
-    sock.on('connect', () => sock.write(JSON.stringify({ op: 'recall', prompt, limit: 8 }) + '\\n'));
+    sock.on('connect', () => sock.write(JSON.stringify({ op: 'recall', prompt, limit: 8, probe: IS_LIVENESS_PROBE }) + '\\n'));
     sock.on('data', (chunk) => {
       buf += chunk.toString('utf8');
       const nl = buf.indexOf('\\n');
       if (nl === -1) return;
       clearTimeout(timer);
       const msg = safe(() => JSON.parse(buf.slice(0, nl)), undefined);
-      done(
-        msg && Array.isArray(msg.hits)
-          ? {
-              hits: msg.hits,
-              engine: typeof msg.engine === 'string' ? msg.engine : undefined,
-              reason: typeof msg.reason === 'string' ? msg.reason : undefined,
-            }
-          : undefined,
-      );
+      if (msg && Array.isArray(msg.hits)) {
+        done({
+          hits: msg.hits,
+          engine: typeof msg.engine === 'string' ? msg.engine : undefined,
+          reason: typeof msg.reason === 'string' ? msg.reason : undefined,
+        });
+      } else {
+        done({ error: 'bad-reply' });
+      }
     });
     sock.on('error', () => {
       clearTimeout(timer);
-      done(undefined);
+      done({ error: 'connect-refused' });
     });
   });
 }
@@ -455,6 +533,13 @@ function askDaemon(prompt) {
 const REVIVE_LOCK = path.join(PROJECT, '.dz', 'embed-daemon.lock');
 const REVIVE_LOCK_FRESH_MS = 120_000; // model load takes ~45s; don't respawn while one is coming up
 function reviveDaemon() {
+  // AM-7 (fix round 1, test-only): a test that probes the SAME dead fixture multiple times in quick
+  // succession (probeApplyLeg directly, then again through runDoctor, then again through a
+  // 'dz parity' subprocess) used to race against this very self-heal — the first probe's revive
+  // could finish loading a real daemon before the second or third probe ran, flipping
+  // "socket-absent" into "hybrid"/"cosine-fallback" non-deterministically. No production session
+  // ever sets this.
+  if (process.env.DZ_RECALL_NO_REVIVE === '1') return;
   // CROSS-PROCESS lock: every prompt runs a fresh hook process, so a per-process flag let 20 queued
   // prompts spawn 20 daemons while the first was still loading its model (Codex #5). A lockfile with
   // a freshness window means at most one spawn per window, machine-wide.
@@ -620,6 +705,17 @@ function emitContext(context) {
   );
 }
 
+// FR-1 (ADR-001 D2, apply-leg-never-silent): every silent early exit below now names WHY, on
+// stderr, one line, same shape as the existing \`[dz-recall] engine=…\` diagnostic. Exit code stays
+// 0 — a broken/empty/quiet hook must never fail a prompt (NEVER-BLOCK, unchanged). The reason is
+// for TWO readers, neither of which is "the user watching Claude Code's own transcript" (FR-2's
+// own manifest names why that channel does not apply to this hook): (1) \`dz doctor\`'s live probe,
+// which spawns this exact command as a child process and reads ITS OWN child's stderr directly —
+// unmediated by Claude Code's UI, so the redirect policy of any particular hook EVENT is moot; and
+// (2) a human running the command by hand from a terminal, who sees stderr exactly as printed.
+const skip = (reason) =>
+  safe(() => process.stderr.write(\`[dz-recall] skipped reason=\${reason} root=\${PROJECT} (\${ROOT_SOURCE}) session=\${SESSION_ROOT}\\n\`));
+
 async function main() {
   const raw = readStdin();
   const payload = safe(() => JSON.parse(String(raw || '').trim()), undefined);
@@ -630,13 +726,34 @@ async function main() {
   // sentinel is absent this is one existsSync and debt === '' (byte-identical outputs to before).
   const debt = await retroDebtDirective(payload);
 
-  if (prompt === '') return emitContext(debt);
+  if (prompt === '') {
+    skip('empty-prompt');
+    return emitContext(debt);
+  }
+
+  // FR-1: the most fundamental silent failure (issue #2) — no \`.dz/\` at all under the resolved
+  // PROJECT root. Checked BEFORE the policy/daemon legs below: a missing store makes every
+  // downstream question ("is the daemon alive?") moot, and printing THIS reason first is what let
+  // the original issue's symptom (four green checks, a store that was never there) be diagnosed
+  // from stderr alone.
+  if (!fs.existsSync(path.join(PROJECT, '.dz'))) {
+    skip('store-not-found');
+    return emitContext(debt);
+  }
 
   const policy = await loadPolicy();
-  if (!policy) return emitContext(debt);
+  if (!policy) {
+    skip('core-unavailable');
+    return emitContext(debt);
+  }
 
   const daemonReply = await askDaemon(prompt);
-  if (!daemonReply) {
+  // AM-6: the tagged reason IS the diagnosis now — 'socket-absent' (no file), 'connect-refused' (a
+  // file exists but nothing answers like a daemon), 'daemon-timeout' (something answers, never in
+  // time) and 'bad-reply' (answers, unparseable/shapeless) are four DIFFERENT defects with four
+  // different remedies; collapsing them back into one string is exactly the finding this fixes.
+  if (daemonReply.error) {
+    skip(daemonReply.error);
     // SELF-HEAL (2026-07-28): the daemon is started at SessionStart only, so when it dies mid-way
     // through a long-lived session NOTHING restarts it — the apply leg was silently dead for 19
     // days (MEASURED: recall-usage.jsonl last record 2026-07-09, socket absent). Spawn it
@@ -648,9 +765,12 @@ async function main() {
   // FR-6/FR-2: the engine (and, on fallback, why) is the caller's business, not the model's — it
   // NEVER rides into additionalContext, only stderr, which Claude Code does not read as context.
   if (typeof engine === 'string') {
-    safe(() => process.stderr.write(\`[dz-recall] engine=\${engine}\${reason ? \` reason=\${reason}\` : ''}\\n\`));
+    safe(() => process.stderr.write(\`[dz-recall] engine=\${engine}\${reason ? \` reason=\${reason}\` : ''} root=\${PROJECT} (\${ROOT_SOURCE}) session=\${SESSION_ROOT}\\n\`));
+  }
+  if (hits.length === 0) {
+    skip('no-hits');
+    return emitContext(debt); // daemon alive, nothing relevant — silence is correct
   }
-  if (hits.length === 0) return emitContext(debt); // daemon alive, nothing relevant — silence is correct
 
   // FR-5 (ADR-001 D2): a hybrid-engine reply carries an RRF-based score — its OWN floor, applied to
   // both languages. A cosine-fallback reply (or an old daemon that never sent \`engine\` at all)
@@ -774,14 +894,19 @@ import { createRequire } from 'node:module';
 import { connect } from 'node:net';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 
 const log = (...a) => console.error('[dz-embed]', ...a);
 
 /** Never let a diagnostic reach stdout — the hook that spawns us may be parsing it. */
 console.log = (...a) => console.error(...a);
 
-const PROJECT = process.env['DZ_PROJECT_ROOT'] ?? process.cwd();
+// FR-4 (ADR-001 D1, apply-leg-install-root): the SAME install-root-first order the hook uses (see
+// recallHookSource's own PROJECT comment) — DZ_PROJECT_ROOT stays the TOP override for the daemon
+// (a caller that explicitly names a project root always wins), then INSTALL_ROOT (this file's own
+// location, when it owns a \`.dz/\`), then cwd.
+const INSTALL_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const PROJECT = process.env['DZ_PROJECT_ROOT'] ?? (existsSync(join(INSTALL_ROOT, '.dz')) ? INSTALL_ROOT : process.cwd());
 
 // ADR-001 (hook-recall-hybrid-parity, D1): the SAME candidate-list resolution the hook uses for its
 // own policy modules — the baked \`coreDistDir\` first (a real install's absolute dist path), then
@@ -958,6 +1083,27 @@ function quarantinedOf(metadataJson) {
   }
 }
 
+// AM-3 (fix round 1, apply-leg-never-silent): the vector mirror's own row carries no domain column
+// (see loadPatterns' own note below) — domain lives in the SAME metadata JSON dzIdOf/quarantinedOf
+// already parse, so this is the ONE extra field read off a column that's already in hand.
+function domainOf(metadataJson) {
+  try {
+    const d = JSON.parse(String(metadataJson || '{}'))?.domain;
+    return typeof d === 'string' && d !== '' ? d : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// AM-3: the ONE domain a genuine session must never see — probeApplyLeg's own beacon marker
+// (apply-leg.ts's PROBE_BEACON_DOMAIN, inlined here as text for the same reason every other shared
+// constant in this generated file is: a template string cannot import a compiled module).
+const PROBE_BEACON_DOMAIN = 'apply-leg-probe';
+/** Strip probe-domain hits from a real (non-probe) answer; a probe request passes through untouched. */
+function filterProbeHits(hits, probe) {
+  return probe ? hits : hits.filter((h) => h.domain !== PROBE_BEACON_DOMAIN);
+}
+
 async function main() {
   if (await socketAlive(SOCKET)) {
     log('a daemon already owns', SOCKET, '— exiting');
@@ -1007,7 +1153,9 @@ async function main() {
       return rows.map((r) => {
         const buf = r.embedding;
         const vec = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-        return { dzId: dzIdOf(r.metadata), pattern: r.pattern, vec, quarantined: quarantinedOf(r.metadata) };
+        // AM-3: domain rides along so answerRecall can exclude the probe's own beacon from a real
+        // session's cosine-fallback answer — the SAME metadata column dzIdOf/quarantinedOf already read.
+        return { dzId: dzIdOf(r.metadata), pattern: r.pattern, vec, quarantined: quarantinedOf(r.metadata), domain: domainOf(r.metadata) };
       });
     } finally {
       db.close();
@@ -1033,7 +1181,7 @@ async function main() {
   // \`hybridRecall\`'s own promise is left running past a timeout loss (never awaited a second time)
   // — its \`.catch\` below only silences a LATE rejection so a slow, eventually-failing engine call
   // can never become an unhandled-rejection crash for this long-lived process.
-  async function hybridRecall(prompt, limit) {
+  async function hybridRecall(prompt, limit, probe) {
     if (hybridInFlight >= HYBRID_MAX_IN_FLIGHT) {
       return { ok: false, reason: \`hybrid saturated (\${hybridInFlight} attempt(s) still in flight, cap \${HYBRID_MAX_IN_FLIGHT})\` };
     }
@@ -1073,7 +1221,10 @@ async function main() {
         domain: h.pattern.domain,
         ...(h.quarantined ? { quarantined: true } : {}),
       }));
-      return { ok: true, hits: hits.slice(0, limit) };
+      // AM-3 (fix round 1): filter BEFORE slicing to \`limit\` — filtering after would let a probe
+      // beacon that happened to rank in the top \`limit\` silently crowd out a real hit for a real
+      // (non-probe) caller instead of simply being excluded from consideration.
+      return { ok: true, hits: filterProbeHits(hits, probe).slice(0, limit) };
     } catch (err) {
       clearTimeout(timer);
       return { ok: false, reason: \`recallHybrid failed: \${err?.message ?? err}\` };
@@ -1082,10 +1233,10 @@ async function main() {
 
   /** \`op: recall\`'s whole answer: hybrid first (budget-bounded), cosine fallback on ANY failure —
    * always honestly labelled with \`engine\`/\`reason\` (FR-2/FR-6). */
-  async function answerRecall(prompt, limitRaw) {
+  async function answerRecall(prompt, limitRaw, probe) {
     const limit = Math.min(Number(limitRaw) || 8, 32);
     if (prompt.trim() === '') return { hits: [], engine: 'none', reason: 'empty prompt' }; // Codex round-2: every reply carries \`engine\`
-    const hybrid = await hybridRecall(prompt, limit);
+    const hybrid = await hybridRecall(prompt, limit, probe);
     if (hybrid.ok) return { hits: hybrid.hits, engine: 'hybrid' };
     // Reload the cosine mirror if it changed on disk (a \`dz teach\` between turns) — the SAME
     // staleness window as before this feature, just checked only when actually falling back.
@@ -1099,9 +1250,10 @@ async function main() {
     }
     if (patterns.length === 0) return { hits: [], engine: 'cosine-fallback', reason: hybrid.reason };
     const qv = await embed(prompt);
-    const scored = patterns.map((p) => ({ dzId: p.dzId, pattern: p.pattern, score: cos(qv, p.vec), ...(p.quarantined ? { quarantined: true } : {}) }));
+    const scored = patterns.map((p) => ({ dzId: p.dzId, pattern: p.pattern, score: cos(qv, p.vec), domain: p.domain, ...(p.quarantined ? { quarantined: true } : {}) }));
     scored.sort((a, b) => b.score - a.score);
-    return { hits: scored.slice(0, limit), engine: 'cosine-fallback', reason: hybrid.reason };
+    // AM-3: same domain exclusion as the hybrid leg, applied before slicing for the same reason.
+    return { hits: filterProbeHits(scored, probe).slice(0, limit), engine: 'cosine-fallback', reason: hybrid.reason };
   }
 
   // AM-1 (fix round 1): warm resolveAgentdbEmbedder — cached PER PROCESS since db1521ba (cold
@@ -1162,7 +1314,7 @@ async function main() {
             return shutdown(0);
           } else if (msg.op === 'recall') {
             const prompt = typeof msg.prompt === 'string' ? msg.prompt : '';
-            reply = await answerRecall(prompt, msg.limit);
+            reply = await answerRecall(prompt, msg.limit, msg.probe === true);
           } else {
             reply = { error: \`unknown op \${String(msg.op)}\` };
           }
@@ -1263,25 +1415,104 @@ export interface ApplyLegHookEntry {
   readonly hooks: readonly { readonly type: 'command'; readonly command: string }[];
 }
 
+/**
+ * POSIX single-quote a value for safe interpolation into a shell command line: wraps it in `'`,
+ * escaping every embedded `'` as the standard `'\''` sequence (close quote, literal escaped quote,
+ * reopen quote). Single quotes disable EVERY shell expansion — `$`, backticks, `"`, another `'` —
+ * unlike a bare `"..."` interpolation, which blocks only whitespace/globbing and still lets `$`/
+ * backtick content run (AM-1, fix round 1, HIGH).
+ */
+function shellQuote(value: string): string {
+  return `'${value.split(`'`).join(`'\\''`)}'`;
+}
+
 /**
  * The two hook-registry entries `runSetup` merges into `.claude/settings.json` (FR-1). Commands
  * match the hub's own `.claude/settings.json` verbatim (`grep`-diffed against it at authoring time):
  * the recall hook is invoked with a swallowed non-zero exit (`|| true`) so a broken hook body never
  * fails a prompt, and the embed daemon is spawned detached via `nohup` + a backgrounding `sh -c`
  * so `SessionStart` never waits on model load.
+ *
+ * `installRoot` (ADR-001 D2, feature `apply-leg-install-root`): when the caller (`dz setup`) knows
+ * its own install root, the commands bake it in as an ABSOLUTE path — the deployed helper already
+ * bakes an absolute `CORE_DIST_DIR`, so a `${CLAUDE_PROJECT_DIR:-.}`-relative command in
+ * settings.json only masked that non-portability, and broke down to `Cannot find module` (swallowed
+ * by `2>/dev/null || true`) whenever `project === $HOME` and a session's own `CLAUDE_PROJECT_DIR`
+ * pointed elsewhere (issue #2). Omitting `installRoot` (every pre-existing zero-arg caller — status
+ * fixtures, `applyLegStatus` regression tests) keeps the original `CLAUDE_PROJECT_DIR`-relative
+ * form byte for byte; `hookCommandInvokes`/`applyLegStatus` (FR-3) recognize BOTH forms as wired,
+ * and `runSetup`'s `addIfMissing` (setup.ts) REPLACES a stale form with the current one in place —
+ * never a second entry — on re-setup.
+ *
+ * Fix round 1 corrections to the absolute (`installRoot`-given) branch — the legacy zero-arg branch
+ * is UNCHANGED byte for byte:
+ *  - AM-1 (HIGH): a caller-controlled path was interpolated RAW into shell source. A `"`, `$`,
+ *    backtick, or `'` in `installRoot` altered or injected commands, and the SessionStart form broke
+ *    outright on a `'` (it cannot be escaped inside a `'...'` body by nesting `"`). Fixed:
+ *    {@link shellQuote} wraps every path; SessionStart passes them as POSITIONAL ARGS (`$1`/`$2`) to
+ *    an INNER `sh -c` whose script text is a FIXED literal with no caller-controlled bytes, so
+ *    nested-quote fragility cannot arise at all.
+ *  - AM-3 (HIGH): the daemon used to fall back to `DZ_PROJECT_ROOT ?? installLocal`, and nothing in
+ *    the SessionStart command ever SET that variable — a stale inherited `DZ_PROJECT_ROOT` in the
+ *    parent env could win over the install root the hook itself resolves to. Fixed: the SessionStart
+ *    command now sets `DZ_PROJECT_ROOT="$1"` (`$1` = installRoot) explicitly, so the daemon and the
+ *    hook agree by construction regardless of what the parent environment happens to carry.
+ *  - AM-4 (LOW): a relative `installRoot` used to produce a relative command, breaking the "every
+ *    baked path is absolute" invariant the module's own docs claim. Fixed: `resolve()`s its input.
  */
-export function applyLegHookEntries(): { readonly userPromptSubmit: ApplyLegHookEntry; readonly sessionStart: ApplyLegHookEntry } {
+export function applyLegHookEntries(
+  installRoot?: string,
+): { readonly userPromptSubmit: ApplyLegHookEntry; readonly sessionStart: ApplyLegHookEntry } {
+  if (installRoot === undefined) {
+    // Legacy zero-arg form — byte-identical to every pre-fix-round build. Kept only for
+    // `applyLegStatus`'s upgrade-recognition tests (a pre-feature install's settings.json) and for
+    // seeding "stale entry" fixtures; every real `dz setup` caller passes `opts.projectRoot`.
+    return {
+      userPromptSubmit: {
+        hooks: [{
+          type: 'command',
+          // FR-2 (apply-leg-never-silent, ADR-001 D2): `2>/dev/null` removed — the hook itself now
+          // names every silent exit on stderr (FR-1), and swallowing that stream at the settings.json
+          // level would defeat it at the source. `|| true` stays: a broken hook body must never fail
+          // the prompt.
+          command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/recall-hook.cjs" || true',
+        }],
+      },
+      sessionStart: {
+        hooks: [{
+          type: 'command',
+          command: "sh -c 'nohup node \"${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/dz-embed-daemon.mjs\" >/dev/null 2>&1 & exit 0'",
+        }],
+      },
+    };
+  }
+  // AM-4: make a relative caller input absolute so the "every baked path is absolute" invariant
+  // holds regardless of what the caller passed, not merely for callers that already resolve first.
+  const root = resolve(installRoot);
+  const recallHookPath = `${root}/.claude/helpers/recall-hook.cjs`;
+  const daemonPath = `${root}/.claude/helpers/dz-embed-daemon.mjs`;
   return {
     userPromptSubmit: {
       hooks: [{
         type: 'command',
-        command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/recall-hook.cjs" 2>/dev/null || true',
+        // AM-1: shellQuote the WHOLE path — a bare `"..."` interpolation only blocks whitespace and
+        // globbing, it still lets `$`, backticks, and a literal `"` do damage; single-quoting blocks
+        // every shell expansion at once.
+        // FR-2 (apply-leg-never-silent, ADR-001 D2): `2>/dev/null` removed — see the zero-arg branch's
+        // comment above for why.
+        command: `node ${shellQuote(recallHookPath)} || true`,
       }],
     },
     sessionStart: {
       hooks: [{
         type: 'command',
-        command: "sh -c 'nohup node \"${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/dz-embed-daemon.mjs\" >/dev/null 2>&1 & exit 0'",
+        // AM-1/AM-3: the INNER script text (`'DZ_PROJECT_ROOT="$1" nohup node "$2" …'`) is a FIXED
+        // literal — no caller-controlled byte ever sits inside it, so it can never itself contain an
+        // unescaped `'` that would break the outer single-quoting. `root`/`daemonPath` instead arrive
+        // as POSITIONAL ARGS (`$1`/`$2`), each independently shellQuote()d for the OUTER shell that
+        // parses this whole command line. AM-3: `DZ_PROJECT_ROOT="$1"` pins the daemon to THIS
+        // install root explicitly — a stale value already in the parent environment can never win.
+        command: `sh -c 'DZ_PROJECT_ROOT="$1" nohup node "$2" >/dev/null 2>&1 & exit 0' sh ${shellQuote(root)} ${shellQuote(daemonPath)}`,
       }],
     },
   };
@@ -1357,10 +1588,27 @@ function readHelperStatus(path: string): { exists: boolean; version: number; unr
  * Codex, third pass). A bare mention (`echo .claude/helpers/recall-hook.cjs`) is not an invocation:
  * the helper path must follow a `node` word — directly, or inside the daemon's
  * `sh -c 'nohup node "…"'` spawn. Forward slashes only: every command dz writes uses them.
+ *
+ * Fix round 1 (AM-1/AM-3, apply-leg-install-root): the SessionStart command now passes its daemon
+ * path as a POSITIONAL ARG (`sh -c '… node "$2" …' sh <root> <daemonPath>`) rather than interpolating
+ * it textually next to `node`, so the ORIGINAL adjacency regex alone no longer matches it. A SECOND
+ * recognizer accepts that shape: the command invokes `node` with a `$N`-style positional argument
+ * AND carries `markerPath` as one of its own (shellQuote()d) trailing arguments — both conditions
+ * together, so a foreign command that merely echoes the marker path near an unrelated `node "$1"`
+ * invocation still does not count.
  */
 export function hookCommandInvokes(command: string, markerPath: string): boolean {
-  const invoked = new RegExp('(^|[\\s;&|(])node\\s+[\'"]?[^\\s\'"]*' + markerPath.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'));
-  return invoked.test(command);
+  const escapedMarker = markerPath.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+  const direct = new RegExp('(^|[\\s;&|(])node\\s+[\'"]?[^\\s\'"]*' + escapedMarker);
+  if (direct.test(command)) return true;
+  // Codex round-2 (NEW): the absolute form is POSIX-single-quoted (`node '<root>/.claude/…'`), and a
+  // root may contain whitespace or `'` (written as `'\''`) — the bare `[^\s'"]*` run above stops at
+  // the first space, so such an entry read as "absent" and re-setup appended a duplicate.
+  const quotedDirect = new RegExp("(^|[\\s;&|(])node\\s+'(?:[^']|'\\\\'')*" + escapedMarker);
+  if (quotedDirect.test(command)) return true;
+  const invokesNodeWithPositional = /\bnode\s+["']?\$\d/.test(command);
+  const markerAsQuotedArg = new RegExp("'[^']*" + escapedMarker + "'");
+  return invokesNodeWithPositional && markerAsQuotedArg.test(command);
 }
 
 /**
@@ -1468,3 +1716,541 @@ export function applyLegReasonMessage(status: ApplyLegStatus): string {
   }
   return 'not installed — run dz setup --target claude-code --memory agentdb';
 }
+
+/**
+ * The ACTUAL command `.claude/settings.json` carries for the wired `UserPromptSubmit` recall hook —
+ * not a reconstruction. {@link probeApplyLeg} must run exactly what a real session would run,
+ * `${CLAUDE_PROJECT_DIR:-.}`-relative legacy form and all: reconstructing our own `node <path> ||
+ * true` would silently stop testing the shell-expansion half of the legacy form, the exact half
+ * issue #2 broke. Mirrors {@link hookWiredUnder}'s traversal (kept in lock-step: both read
+ * `hooks.UserPromptSubmit[*].hooks[*].command` and recognize it via {@link hookCommandInvokes}) but
+ * returns the command TEXT instead of a boolean.
+ */
+function findConfiguredRecallHookCommand(root: string): string | undefined {
+  try {
+    const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf-8')) as unknown;
+    const hooksSection = (settings as { hooks?: unknown })?.hooks;
+    const list = hooksSection && typeof hooksSection === 'object' ? (hooksSection as Record<string, unknown>)['UserPromptSubmit'] : undefined;
+    if (!Array.isArray(list)) return undefined;
+    for (const entry of list) {
+      for (const cmd of hookCommandsOf(entry)) {
+        if (hookCommandInvokes(cmd, '.claude/helpers/recall-hook.cjs')) return cmd;
+      }
+    }
+  } catch {
+    /* settings.json absent, unreadable, or not valid JSON — nothing to probe */
+  }
+  return undefined;
+}
+
+/**
+ * AM-4 (fix round 1, apply-leg-never-silent): the LEGACY zero-arg form ({@link applyLegHookEntries}'s
+ * no-installRoot branch) reads `${CLAUDE_PROJECT_DIR:-.}` — a shell expansion that only resolves to
+ * something useful from a REAL session's own cwd. Spawning it from `probeApplyLeg`'s temp "foreign"
+ * cwd can never find the deployed helper by construction (the file lives at `root`'s own
+ * `.claude/helpers/`, never under the temp dir), so a probe against this form would spawn a doomed
+ * command and report a confusing generic failure — not a fact about whether the leg injects, only a
+ * fact about the fixture being unprobeable. The absolute form ({@link shellQuote}'d installRoot)
+ * never contains this literal env-expansion syntax — it bakes a resolved path instead — so a plain
+ * substring check distinguishes the two without re-parsing shell grammar.
+ */
+export function isLegacyRelativeRecallCommand(command: string): boolean {
+  return command.includes('${CLAUDE_PROJECT_DIR');
+}
+
+/** {@link probeApplyLeg}'s result — the ONE measurement `dz doctor`'s new row and `dz parity`'s
+ * Self-learning cell both read (ADR-001 Decision 3, extended by `apply-leg-never-silent` D1): green
+ * means OBSERVED injection, never inferred file presence. */
+export interface ApplyLegProbeResult {
+  /** True ONLY when the probe's own beacon lesson came back inside `additionalContext`. */
+  readonly ok: boolean;
+  /** Present exactly when `ok` is `false` — taken from the hook's own `[dz-recall] skipped
+   * reason=…` stderr line when present, else a best-effort description of what went wrong. */
+  readonly reason?: string;
+  readonly elapsedMs: number;
+  /** Fix round 1 (HIGH-1): the KILL-ATTEMPT fact, straight from `probeHookLiveness`'s own
+   * `groupKillAttempted` — present only on the branches that actually reached a spawn (absent for the
+   * early "not installed" / "no hook configured" / "legacy command" / "beacon write failed"
+   * returns, none of which ever call `probeHookLiveness`). This is deliberately a DIFFERENT fact
+   * from "is the grandchild still alive" — a caller observes both separately, never conflates them. */
+  readonly groupKillAttempted?: boolean;
+  /** FR-3 (feature `apply-leg-daemon-hygiene`): present exactly when the pre-probe scavenge of
+   * STALE beacon-domain records failed — the reason comes straight from {@link
+   * scavengeStaleProbeBeacons}'s own `error`, never swallowed. Independent of `ok`/`reason`: a
+   * scavenge failure does not itself flip `ok` to `false` (the probe's own injection result may
+   * still be perfectly genuine), but it IS a fact `dz doctor`/`dz parity` callers can surface
+   * rather than lose. */
+  readonly scavengeError?: string;
+}
+
+/** Words a real prompt needs to clear `hasEnoughSignal` (recall-hook-policy.ts: `MIN_PROMPT_CHARS`
+ * 10, `MIN_CONTENT_TOKENS` 2) — a bare unique token alone is ONE token and would be silently
+ * dropped by the very floor this probe means to exercise honestly. */
+const PROBE_PROMPT_WORDS = 'apply leg live probe';
+/** Doctor/parity probes share ONE domain tag so a leaked beacon (a failed removal) is trivially
+ * findable and excludable — never `dz-teach`/`general`, which would blend it into real lessons. */
+const PROBE_BEACON_DOMAIN = 'apply-leg-probe';
+
+/**
+ * FR-3 (feature `apply-leg-daemon-hygiene`): the scavenger that ran at the top of every probe used
+ * to delete EVERY beacon-domain record unconditionally — safe against a probe killed mid-flight
+ * (Codex round-2's own reason for the scavenger existing at all), but WRONG the moment two probes
+ * from two DIFFERENT sessions can be live against the SAME store at once: the second probe's
+ * scavenge deletes the first probe's still-in-flight beacon, and the first probe then reports a
+ * false `ok:false` (its own hook query returns nothing, because the lesson it was about to match
+ * against is already gone) — a false-red `dz doctor`/`dz parity` parity check with no defect behind
+ * it. The fix: tag every beacon with its OWNER (`probe-owner=<pid>:<startedMs>`, embedded in the
+ * pattern TEXT so it survives a round-trip through any store tier without a schema change — NFR-1
+ * forbids a new column) and scavenge ONLY a beacon whose owner is provably gone: the pid no longer
+ * answers `process.kill(pid, 0)`, OR the beacon has outlived its TTL (see {@link
+ * scavengeStaleProbeBeacons}'s own `ttlMs` parameter).
+ */
+const PROBE_OWNER_TAG_PREFIX = 'probe-owner=';
+/** Fix round 1 (HIGH-6 residual): a second, independent tag alongside `probe-owner=` — the WRITING
+ * process's own OS-level start time (epoch ms, from `/proc/<pid>/stat`), so the scavenger can tell a
+ * PID-REUSE case (the recorded pid is technically "alive" per `process.kill(pid,0)`, but the LIVE
+ * process at that pid started at a different time than the one that wrote the beacon) apart from
+ * the genuine same-process case. Absent whenever the write-time `/proc` read fails (non-Linux,
+ * permission) — the scavenger then falls back to the plain alive+TTL check alone, unchanged. */
+const PROC_START_TAG_PREFIX = 'proc-start=';
+/** Lead delta after Codex round 2 (HIGH-4): the beacon's OWN expiry, in epoch ms, written by the
+ * probe that owns it. The pre-delta scavenger applied ITS OWN `ttlMs` to SOMEONE ELSE'S beacon, so a
+ * default-budget probe (ttl 60 s) deleted the live beacon of a widened-budget probe (ttl 360 s) after
+ * 60 s — the very false-red this hardening exists to prevent, one level up. A beacon now states when
+ * IT expires; the scavenger's own `ttlMs` is only the fallback for a beacon written before this tag
+ * existed. */
+const PROBE_EXPIRES_TAG_PREFIX = 'probe-expires=';
+
+/**
+ * Fix round 1 (HIGH-6): the pre-fix-round TTL was a flat 60 000 ms, independent of the probe's own
+ * `timeoutMs` — a caller that legitimately widens `timeoutMs` past that (a widened, suspended, or
+ * heavily loaded probe) could have its OWN still-in-flight beacon scavenged by a concurrent probe
+ * before it ever replies. The TTL is now DERIVED from the probe's own `timeoutMs`
+ * (`max(timeoutMs * 3, 60_000)`, see {@link probeApplyLeg}'s call site) so a widened timeout widens
+ * its own protection window too; the 60 000 ms floor keeps the pre-fix-round generous margin for the
+ * default (unwidened) case. Exported as a named constant only for the floor value — the ACTUAL TTL
+ * used by a given probe is always `ttlMs`, computed at the call site, never this constant alone.
+ */
+const PROBE_BEACON_TTL_FLOOR_MS = 60_000;
+
+function formatProbeOwner(pid: number, startedMs: number): string {
+  return `${PROBE_OWNER_TAG_PREFIX}${pid}:${startedMs}`;
+}
+
+/** Parses the `probe-owner=<pid>:<startedMs>` tag out of a beacon's pattern text. `undefined` for
+ * any beacon predating this tag (an older deployed core wrote it) — treated by the scavenger as
+ * ownerless and therefore always safe to remove (the pre-FR-3 behavior for exactly that case). */
+function parseProbeOwner(patternText: string): { readonly pid: number; readonly startedMs: number } | undefined {
+  const idx = patternText.indexOf(PROBE_OWNER_TAG_PREFIX);
+  if (idx === -1) return undefined;
+  const match = /probe-owner=(\d+):(\d+)/u.exec(patternText.slice(idx));
+  if (match?.[1] === undefined || match[2] === undefined) return undefined;
+  return { pid: Number(match[1]), startedMs: Number(match[2]) };
+}
+
+function formatProcStart(procStartedAtMs: number): string {
+  return ` ${PROC_START_TAG_PREFIX}${procStartedAtMs}`;
+}
+
+function formatProbeExpires(expiresAtMs: number): string {
+  return ` ${PROBE_EXPIRES_TAG_PREFIX}${expiresAtMs}`;
+}
+
+/** Parses the `probe-expires=<epochMs>` tag — `undefined` for a beacon written before the tag
+ * existed, which is exactly when the scavenger falls back to its own `ttlMs`. */
+function parseProbeExpires(patternText: string): number | undefined {
+  const idx = patternText.indexOf(PROBE_EXPIRES_TAG_PREFIX);
+  if (idx === -1) return undefined;
+  const match = /probe-expires=(\d+)/u.exec(patternText.slice(idx));
+  if (match?.[1] === undefined) return undefined;
+  return Number(match[1]);
+}
+
+/** Parses the `proc-start=<ticks>` tag — `undefined` when absent (pre-fix-round beacon, or the
+ * write-time `/proc` read failed). */
+function parseProcStart(patternText: string): number | undefined {
+  const idx = patternText.indexOf(PROC_START_TAG_PREFIX);
+  if (idx === -1) return undefined;
+  const match = /proc-start=(\d+)/u.exec(patternText.slice(idx));
+  if (match?.[1] === undefined) return undefined;
+  return Number(match[1]);
+}
+
+/** True when `pid` answers a liveness signal — `process.kill(pid, 0)` sends no actual signal, it
+ * only probes whether the OS still has a process at that pid (ESRCH ⇒ dead). */
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code !== 'ESRCH';
+  }
+}
+
+/**
+ * Fix round 1 (HIGH-6 residual, Linux-only, best-effort), tightened by the lead after Codex round 2
+ * (MEDIUM-6): a process's OWN `starttime` from `/proc/<pid>/stat` — field 22 overall, found by
+ * skipping past the LAST `)` so a `comm` containing spaces or parens never misaligns the split —
+ * returned as RAW TICKS SINCE BOOT, the unit the kernel reports. No wall clock is consulted and no
+ * CLK_TCK conversion is performed, so a stepped wall clock can no longer make the same live process
+ * look like a different one. `undefined` on ANY read/parse failure (non-Linux, permission, the
+ * process exiting mid-read) — the caller MUST treat that as "cannot prove", never as a pass in
+ * either direction.
+ */
+function pidStartedAtMsFromProcStat(pid: number): number | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+    const afterComm = stat.slice(stat.lastIndexOf(')') + 1).trim();
+    const fields = afterComm.split(/\s+/u);
+    // Overall field 22 (`starttime`) = fields[22 - 3] here, since fields[] starts at overall field 3
+    // (state) once `pid (comm)` (fields 1-2) has been stripped above.
+    const starttimeTicks = Number(fields[19]);
+    if (!Number.isFinite(starttimeTicks)) return undefined;
+    // Lead delta after Codex round 2 (MEDIUM-6): return the RAW ticks-since-boot, never an epoch
+    // derived from `Date.now() - uptime()`. The derived epoch moves when the WALL CLOCK is stepped,
+    // so the same still-running process appeared to have "started at a different time" and its LIVE
+    // beacon was deleted as a pid-reuse. Ticks since boot are monotonic within a boot and identical
+    // for the same process on every read; across a reboot the recorded pid is dead anyway, which the
+    // liveness check catches first — WITHDRAWN by the lead after Codex round 4: that sentence was
+    // wrong, because across a reboot the pid may ALREADY have been reused and can collide on start
+    // ticks too; the honest scope is the NAMED LIMIT stated below. This also removes the CLK_TCK assumption entirely — no conversion
+    // to milliseconds happens at all, the two values are compared in their own unit.
+    // NAMED LIMIT (lead delta after Codex round 3, MEDIUM): identity holds WITHIN one boot. Across a
+    // reboot both pid allocation and ticks-since-boot restart, so a beacon that somehow persisted
+    // could in principle collide with a new process at the same pid and the same tick. A boot id
+    // would close it; the honest scope today is "within one boot", and a reboot also means the
+    // beacon's own TTL has almost certainly passed, which the TTL branch catches first.
+    return starttimeTicks;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Fix round 1 (HIGH-6 residual): `process.kill(pid,0)` proves SOME process occupies `pid`, never
+ * that it is the SAME process that wrote the beacon — PID reuse defeats the plain alive check named
+ * as a residual limit in the review. Compares the LIVE process's own start time (from `/proc/<pid>/
+ * stat`) against `recordedStartedMs` (the beacon's own `proc-start=` tag). A mismatch beyond {@link
+ * PID_START_TOLERANCE_MS} means the pid was reused by an unrelated process — the true owner is
+ * confirmed gone. `undefined` (stat unreadable) means "cannot prove either way" — the lead's decision
+ * (fix round 1, item 6) is explicit: that MUST read as "do not remove" wherever it is consumed, never
+ * as a pass. */
+function isSameProcessInstance(pid: number, recordedStartTicks: number): boolean | undefined {
+  const actualStartTicks = pidStartedAtMsFromProcStat(pid);
+  if (actualStartTicks === undefined) return undefined;
+  // Lead delta after Codex round 2 (MEDIUM-6): EXACT equality on ticks-since-boot. The old
+  // ±5 000 ms tolerance existed only to absorb the CLK_TCK guess in the epoch conversion; with the
+  // raw kernel value there is nothing to absorb, and a tolerance would re-admit the very pid-reuse
+  // case it was meant to exclude (a reused pid started within the tolerance read as "same process").
+  return actualStartTicks === recordedStartTicks;
+}
+
+/** {@link scavengeStaleProbeBeacons}'s result — FR-3: a scavenge error is a FACT the caller can
+ * surface, never a swallowed exception (the pre-fix `catch { /* best-effort *\/ }` this replaces). */
+export type ScavengeResult = { readonly ok: true; readonly removed: number } | { readonly ok: false; readonly error: string };
+
+/**
+ * FR-3/FR-4: remove only the STALE beacon-domain records in `root`'s store — owner dead
+ * (`process.kill(pid, 0)` ⇒ ESRCH), older than `ttlMs`, OR (fix round 1, HIGH-6 residual) alive AND
+ * within `ttlMs` but the live pid's OWN `/proc/<pid>/stat` start time no longer matches the beacon's
+ * `proc-start=` tag — a confirmed PID-reuse case, where the recorded owner is provably gone even
+ * though `pid` itself answers. An UNREADABLE stat at scavenge time never counts as reuse evidence —
+ * it falls back to the plain alive+TTL verdict, per the lead's "cannot prove ⇒ do not remove"
+ * decision. A beacon whose owner is alive, within TTL, and (when provable) confirmed the SAME
+ * process is left untouched, even though it belongs to a different probe. An ownerless (pre-FR-3)
+ * beacon is always treated as stale. `ttlMs` defaults to {@link PROBE_BEACON_TTL_FLOOR_MS} for a
+ * caller that does not derive one (`apply-leg-beacon-owner.test.ts`'s own fixtures); `probeApplyLeg`
+ * always passes its own derived value. Exported so `apply-leg-beacon-owner.test.ts` can exercise the
+ * property directly, without needing a live hook/daemon (FR-4's red-first case needs only a store
+ * and an injectable remover, never a real probe round-trip).
+ */
+export function scavengeStaleProbeBeacons(
+  root: string,
+  removeBeacon: (root: string, ids: ReadonlySet<string>) => RemovePatternsResult,
+  ttlMs: number = PROBE_BEACON_TTL_FLOOR_MS,
+): ScavengeResult {
+  try {
+    const beacons = loadStorePatternsSync(root).filter((p) => p.domain === PROBE_BEACON_DOMAIN);
+    const staleIds: string[] = [];
+    for (const beacon of beacons) {
+      const owner = parseProbeOwner(beacon.pattern);
+      if (owner === undefined) {
+        staleIds.push(beacon.dzId ?? patternRecordId(beacon));
+        continue;
+      }
+      const alive = isPidAlive(owner.pid);
+      // Lead delta after Codex round 2 (HIGH-4): the beacon's OWN expiry wins over this scavenger's
+      // `ttlMs`, which belongs to a DIFFERENT probe and knows nothing of this owner's budget.
+      const ownExpiresAtMs = parseProbeExpires(beacon.pattern);
+      const withinTtl = ownExpiresAtMs !== undefined
+        ? Date.now() <= ownExpiresAtMs
+        : Date.now() - owner.startedMs <= ttlMs;
+      if (!alive || !withinTtl) {
+        staleIds.push(beacon.dzId ?? patternRecordId(beacon));
+        continue;
+      }
+      // alive AND within TTL — the plain check says "keep", but confirm it is the SAME process, not
+      // a reused pid, whenever the beacon carries the (best-effort) proc-start tag.
+      const procStart = parseProcStart(beacon.pattern);
+      if (procStart !== undefined) {
+        const same = isSameProcessInstance(owner.pid, procStart);
+        if (same === false) staleIds.push(beacon.dzId ?? patternRecordId(beacon)); // confirmed reuse
+        // same === true, or same === undefined (unreadable ⇒ cannot prove ⇒ do not remove): keep.
+      }
+    }
+    if (staleIds.length === 0) return { ok: true, removed: 0 };
+    const result = removeBeacon(root, new Set(staleIds));
+    if (result.error !== undefined) return { ok: false, error: result.error };
+    return { ok: true, removed: result.removed };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Live, end-to-end proof that the apply leg actually injects — ADR-001 Decision 1. `applyLegStatus`
+ * only proves FILES exist and are STRUCTURALLY wired (issue #2's whole defect: four green checks,
+ * a leg that injected nothing in every session but one). This spawns the REAL configured hook
+ * command from a TEMPORARY cwd with `CLAUDE_PROJECT_DIR` pointing at that same temp dir — the exact
+ * shape of a real Claude Code session, which never runs a hook from the project root itself — and
+ * asks it to recall a throwaway "beacon" lesson written into the store for the duration of the call.
+ * `ok: true` only when the beacon's own SECRET token (fix round 1, AM-1 — never sent as input, only
+ * stored) comes back inside `additionalContext`; every other outcome is `ok: false` with a `reason`,
+ * never a silent guess.
+ *
+ * The beacon is written via {@link recordPattern} (the SAME lexical-store seam `dz teach` uses) and
+ * removed via {@link removePatternsByIds} in a `finally` — a probe that throws, times out, or never
+ * finds the leg alive still leaves the store exactly as it found it (proven by a count-before ==
+ * count-after test, not merely claimed).
+ *
+ * `timeoutMs` bounds `probeHookLiveness`'s spawn. Measured (this environment, 2026-09-14, T1): a
+ * `store-not-found`/`socket-absent` early exit returns in well under 200 ms; a live-daemon probe
+ * answers in ~100-200 ms, matching ADR-001's own estimate. 8000 ms leaves roughly a 40x margin for a
+ * loaded daemon without ever approaching `probeHookLiveness`'s own un-overridden 20 000 ms ceiling —
+ * a genuinely dead probe still returns to `dz doctor`/`dz parity` in bounded time.
+ *
+ * `env` is a TEST-ONLY escape hatch (never used by `dz doctor`/`dz parity`, both call this with
+ * default opts): it lets a test widen the HOOK's OWN internal socket-connect timeout
+ * (`DZ_RECALL_HOOK_TIMEOUT_MS`) against a genuinely cold daemon, matching the same widening
+ * `apply-leg-recall-parity.test.ts`/`apply-leg-install-root.test.ts` already apply to the daemon's
+ * `HOOK_RECALL_BUDGET_MS`. Merged BEFORE `CLAUDE_PROJECT_DIR`, so a caller can never override the
+ * one env var this probe's own honesty depends on.
+ */
+export async function probeApplyLeg(
+  root: string,
+  opts: {
+    timeoutMs?: number;
+    env?: Readonly<Record<string, string>>;
+    /** TEST-ONLY seam (AM-2, fix round 1): a stand-in for {@link removePatternsByIds} so a test can
+     * force cleanup to fail WITHOUT needing to corrupt the real store mid-call. Never set by
+     * `dz doctor`/`dz parity` — both call with default opts, and the real function is the default. */
+    removeBeacon?: (root: string, ids: ReadonlySet<string>) => RemovePatternsResult;
+  } = {},
+): Promise<ApplyLegProbeResult> {
+  const started = Date.now();
+  const elapsed = (): number => Date.now() - started;
+
+  // Fix round 1 (HIGH-6): computed HERE, before the scavenger runs, so the scavenge TTL can be
+  // derived from THIS probe's own budget rather than a flat constant blind to a caller-widened
+  // timeout — see the `ttlMs` computation below, right before the beacon that carries its implicit
+  // promise is written.
+  const timeoutMs = opts.timeoutMs ?? 8000;
+
+  const status = applyLegStatus(root);
+  if (!status.installed) {
+    return { ok: false, reason: 'apply-leg not installed', elapsedMs: elapsed() };
+  }
+  const command = findConfiguredRecallHookCommand(root);
+  if (command === undefined) {
+    return { ok: false, reason: 'no UserPromptSubmit entry invokes recall-hook.cjs (settings.json missing or unreadable)', elapsedMs: elapsed() };
+  }
+  // AM-4: the legacy relative form can never be reached from a foreign cwd by construction — see
+  // isLegacyRelativeRecallCommand's own doc comment. Reported BEFORE any beacon is written: there is
+  // nothing to clean up for a probe that never ran.
+  if (isLegacyRelativeRecallCommand(command)) {
+    return { ok: false, reason: 'legacy-relative-command', elapsedMs: elapsed() };
+  }
+
+  // AM-1 (CRITICAL, fix round 1): two INDEPENDENT tokens, not one. `queryToken` rides the PROMPT the
+  // probe sends the hook — a dead/stub hook that merely echoes its own stdin back into
+  // `additionalContext` makes THIS token reappear too, so it alone can never prove genuine
+  // injection. `secretToken` exists ONLY inside the beacon's STORED pattern text and is never sent
+  // to the hook as input — only a hook that actually queried the store and returned a matched
+  // pattern's own text can produce it. `ok: true` therefore requires the SECRET, never the query.
+  const queryToken = `dzapplylegquery${process.pid}${Date.now()}${Math.random().toString(36).slice(2, 10)}`;
+  const secretToken = `dzapplylegsecret${process.pid}${Date.now()}${Math.random().toString(36).slice(2, 10)}`;
+  // FR-3: the owner tag rides the SAME pattern text as the secret — a beacon's owner is knowable
+  // from its store record alone, no side channel, no schema change (NFR-1).
+  const ownerTag = formatProbeOwner(process.pid, started);
+  // Fix round 1 (HIGH-6): TTL derives from THIS probe's own timeoutMs — a caller that widens
+  // timeoutMs (this repo's own live tests widen it to 15_000 ms) widens its own protection window
+  // too, rather than staying pinned to a flat constant blind to that widening. Floored at the
+  // pre-fix-round 60_000 ms so the default (unwidened) case keeps its original generous margin.
+  // Asserted, not merely trusted — an unreasoned future edit to the formula must fail loudly right
+  // here, where the beacon carrying this TTL's implicit promise is about to be written, rather than
+  // silently reintroducing the false-red-under-concurrency defect this closes.
+  const ttlMs = Math.max(timeoutMs * 3, PROBE_BEACON_TTL_FLOOR_MS);
+  if (!(timeoutMs < ttlMs)) {
+    throw new Error(`invariant violated: timeoutMs (${String(timeoutMs)}) must be < ttlMs (${String(ttlMs)}) — scavenger TTL formula regressed`);
+  }
+  // Fix round 1 (HIGH-6 residual, best-effort): the writing process's OWN OS-level start time,
+  // captured NOW so a later scavenger can tell a genuinely-still-alive owner apart from a DIFFERENT
+  // process that merely reused this pid (isSameProcessInstance's own doc comment). Omitted entirely
+  // when unreadable (non-Linux, permission) — the scavenger then falls back to the plain alive+TTL
+  // check for this beacon, unchanged from before this residual hardening.
+  const ownProcStart = pidStartedAtMsFromProcStat(process.pid);
+  const procStartTag = ownProcStart !== undefined ? formatProcStart(ownProcStart) : '';
+  // Lead delta after Codex round 2 (HIGH-4): this beacon states its OWN expiry, so a concurrent
+  // probe with a different (shorter) budget can never out-vote this probe's protection window.
+  const expiresTag = formatProbeExpires(started + ttlMs);
+  const beaconPattern: PatternRecord = {
+    pattern: `${PROBE_PROMPT_WORDS} ${queryToken} — dz doctor / dz parity live-probe marker, safe to remove. probe-secret=${secretToken} ${ownerTag}${procStartTag}${expiresTag}`,
+    type: 'lesson-learned',
+    reward: 0,
+    domain: PROBE_BEACON_DOMAIN,
+    ts: new Date().toISOString(),
+    source: 'apply-leg-probe',
+  };
+  // Deterministic content-hash id (patternRecordId), computed from the SAME object recordPattern is
+  // about to write — the id is a pure function of {pattern, ts, reward, domain, type}, so the value
+  // computed here and the value the store assigns are guaranteed equal without a round-trip read.
+  const beaconId = patternRecordId(beaconPattern);
+  const probePrompt = `${PROBE_PROMPT_WORDS} ${queryToken}`;
+  const removeBeacon = opts.removeBeacon ?? removePatternsByIds;
+
+  // AM-2 (HIGH, fix round 1): `wrote` is armed BEFORE the write is even attempted, and cleanup below
+  // runs off `wrote` alone — a `recordPattern` call that PARTIALLY lands and then rejects used to
+  // skip cleanup entirely (the old code's `finally` only wrapped the code AFTER a successful
+  // `await recordPattern`), leaking the beacon forever. A cleanup FAILURE (the store refuses the
+  // delete) now overrides whatever `result` the probe body computed — `ok: true` is not honest if
+  // the probe cannot even prove the store is clean afterward.
+  let wrote = false;
+  let cleanupFailed = false;
+  let cleanupErrMsg = '';
+  let tempCwd: string | undefined;
+  let result!: ApplyLegProbeResult;
+
+  // Codex round-2: a process killed mid-probe bypasses `finally`, so a beacon can outlive its probe.
+  // Every probe therefore starts by SCAVENGING any beacon left behind by an earlier one (the probe
+  // domain is reserved for beacons, never for user lessons) — the store is clean before AND after.
+  // FR-3/FR-4: scavenging is no longer unconditional — a LIVE beacon from a DIFFERENT concurrent
+  // probe (another session's `dz doctor`/`dz parity` against the same store) must survive; only a
+  // beacon whose owner is dead or past its TTL is removed. A scavenge failure is a named FACT
+  // (`scavengeError`), never a swallowed exception (the pre-fix `catch {}` this replaces).
+  let scavengeError: string | undefined;
+  const scavengeResult = scavengeStaleProbeBeacons(root, removeBeacon, ttlMs);
+  if (!scavengeResult.ok) scavengeError = scavengeResult.error;
+
+  try {
+    wrote = true;
+    let writeFailed: string | undefined;
+    try {
+      await recordPattern(root, beaconPattern);
+    } catch (err) {
+      writeFailed = err instanceof Error ? err.message : String(err);
+    }
+
+    if (writeFailed !== undefined) {
+      result = { ok: false, reason: `beacon write failed: ${writeFailed}`, elapsedMs: elapsed() };
+    } else {
+      // AM-4: a bare empty temp dir does not model a FOREIGN session — a real foreign
+      // CLAUDE_PROJECT_DIR names a DIFFERENT project with its own (empty-of-lessons, but present)
+      // `.dz`/`.claude` tree, not "nothing at all". This closes the gap between "no project" and "a
+      // different, empty project" a bare empty dir cannot distinguish, matching what the hook's own
+      // SESSION_ROOT-derived reads (e.g. the retro-debt sentinel) would see in a real foreign session.
+      tempCwd = mkdtempSync(join(tmpdir(), 'dz-apply-leg-probe-'));
+      mkdirSync(join(tempCwd, '.dz'), { recursive: true });
+      mkdirSync(join(tempCwd, '.claude'), { recursive: true });
+
+      const { probeHookLiveness } = await import('./operations.js');
+      const probeResult = probeHookLiveness(command, JSON.stringify({ prompt: probePrompt }), {
+        cwd: tempCwd,
+        env: { ...(opts.env ?? {}), CLAUDE_PROJECT_DIR: tempCwd },
+        timeoutMs,
+      });
+
+      const stdoutLines = probeResult.stdout.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+      let additionalContext: unknown;
+      for (const line of stdoutLines) {
+        try {
+          const parsed = JSON.parse(line) as { hookSpecificOutput?: { additionalContext?: unknown } };
+          if (typeof parsed?.hookSpecificOutput?.additionalContext === 'string') {
+            additionalContext = parsed.hookSpecificOutput.additionalContext;
+          }
+        } catch {
+          /* not a JSON line — the hook only ever emits at most one, but tolerate stray output */
+        }
+      }
+
+      if (typeof additionalContext === 'string' && additionalContext.includes(secretToken)) {
+        result = { ok: true, elapsedMs: elapsed(), groupKillAttempted: probeResult.groupKillAttempted };
+      } else if (typeof additionalContext === 'string' && additionalContext.includes(queryToken)) {
+        // AM-1: the QUERY came back but the SECRET did not — the hook (or a stub standing in for
+        // it) echoed its own input instead of genuinely querying the store. Named distinctly from
+        // every other red reason so a dead leg and a FAKING one never read the same.
+        result = { ok: false, reason: 'echo-not-injection', elapsedMs: elapsed(), groupKillAttempted: probeResult.groupKillAttempted };
+      } else {
+        // FR-1's own reason line is the authoritative source — the hook names itself why it stayed
+        // quiet. Falling back to a raw stderr/status summary keeps the probe honest even against an
+        // OLDER deployed hook (pre-`apply-leg-never-silent`) that has not been upgraded yet.
+        const skipMatch = /\[dz-recall\] skipped reason=(\S+)/.exec(probeResult.stderr);
+        const skipReason = skipMatch?.[1];
+        if (skipReason !== undefined) {
+          result = { ok: false, reason: skipReason, elapsedMs: elapsed(), groupKillAttempted: probeResult.groupKillAttempted };
+        } else if (probeResult.status === null) {
+          result = { ok: false, reason: `probe did not complete (timeout or spawn error after ${timeoutMs} ms)`, elapsedMs: elapsed(), groupKillAttempted: probeResult.groupKillAttempted };
+        } else {
+          const stderrFirstLine = probeResult.stderr.trim().split('\n')[0];
+          result = {
+            ok: false,
+            reason: stderrFirstLine && stderrFirstLine !== '' ? stderrFirstLine : 'no beacon in additionalContext (empty or non-matching reply)',
+            elapsedMs: elapsed(),
+            groupKillAttempted: probeResult.groupKillAttempted,
+          };
+        }
+      }
+    }
+  } finally {
+    if (tempCwd !== undefined) {
+      try {
+        rmSync(tempCwd, { recursive: true, force: true });
+      } catch {
+        /* best-effort cleanup of the probe's own temp cwd */
+      }
+    }
+    // Beacon removal is UNCONDITIONAL on `wrote` — success, failure, or a thrown probe all reach
+    // here (AM-2). `removePatternsByIds` never throws (patterns.ts's own contract) — a failure is
+    // reported through its RETURN VALUE's `.error`, checked below, never via a catch.
+    if (wrote) {
+      try {
+        const removeResult = removeBeacon(root, new Set([beaconId]));
+        if (removeResult.error !== undefined) {
+          cleanupFailed = true;
+          cleanupErrMsg = removeResult.error;
+        }
+      } catch (err) {
+        // Codex round-2: a remover that THROWS (a foreign store implementation, a test seam) must not
+        // escape past the cleanup accounting — it is a cleanup failure like any other.
+        cleanupFailed = true;
+        cleanupErrMsg = err instanceof Error ? err.message : String(err);
+      }
+    }
+  }
+
+  if (cleanupFailed) {
+    // a cleanup failure can only happen after `result` was assigned (the finally block runs after
+    // the try body) — carry the kill-attempt fact through rather than dropping it on this path.
+    // `exactOptionalPropertyTypes` forbids assigning `undefined` to an optional field explicitly, so
+    // the key is included only when `result.groupKillAttempted` actually has a value.
+    return {
+      ok: false,
+      reason: `beacon-cleanup-failed: beacon ${beaconId} could not be removed (${cleanupErrMsg})`,
+      elapsedMs: elapsed(),
+      ...(result.groupKillAttempted !== undefined ? { groupKillAttempted: result.groupKillAttempted } : {}),
+      ...(scavengeError !== undefined ? { scavengeError } : {}),
+    };
+  }
+  // FR-3: a scavenge failure is surfaced on the SUCCESS path too — it does not override `ok`/
+  // `reason` (this probe's own injection result may be perfectly genuine), but it is a fact a
+  // caller should not lose.
+  return scavengeError !== undefined ? { ...result, scavengeError } : result;
+}