@dzhechkov/harness-core 0.8.35 → 0.8.36

package/src/apply-leg.ts

@@ -33,7 +33,7 @@ import { connect as netConnect } from 'node:net';
 // (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 } from 'node:os';
+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';
@@ -1768,6 +1768,19 @@ export interface ApplyLegProbeResult {
    * 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`
@@ -1778,6 +1791,221 @@ const PROBE_PROMPT_WORDS = 'apply leg live probe';
  * 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,
@@ -1821,6 +2049,12 @@ export async function probeApplyLeg(
   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() };
@@ -1844,8 +2078,32 @@ export async function probeApplyLeg(
   // 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}`,
+    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,
@@ -1874,12 +2132,13 @@ export async function probeApplyLeg(
   // 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.
-  try {
-    // a loaded pattern carries the STORE's own id (`dzId`); recomputing it from normalised fields
-    // (type/ts round-trip) can diverge, so the store id wins and the recomputation is the fallback.
-    const stale = loadStorePatternsSync(root).filter((p) => p.domain === PROBE_BEACON_DOMAIN).map((p) => p.dzId ?? patternRecordId(p));
-    if (stale.length > 0) removeBeacon(root, new Set(stale));
-  } catch { /* scavenging is best-effort; the probe's own cleanup below is the accountable path */ }
+  // 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;
@@ -1903,7 +2162,6 @@ export async function probeApplyLeg(
       mkdirSync(join(tempCwd, '.claude'), { recursive: true });
 
       const { probeHookLiveness } = await import('./operations.js');
-      const timeoutMs = opts.timeoutMs ?? 8000;
       const probeResult = probeHookLiveness(command, JSON.stringify({ prompt: probePrompt }), {
         cwd: tempCwd,
         env: { ...(opts.env ?? {}), CLAUDE_PROJECT_DIR: tempCwd },
@@ -1924,12 +2182,12 @@ export async function probeApplyLeg(
       }
 
       if (typeof additionalContext === 'string' && additionalContext.includes(secretToken)) {
-        result = { ok: true, elapsedMs: elapsed() };
+        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() };
+        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
@@ -1937,15 +2195,16 @@ export async function probeApplyLeg(
         const skipMatch = /\[dz-recall\] skipped reason=(\S+)/.exec(probeResult.stderr);
         const skipReason = skipMatch?.[1];
         if (skipReason !== undefined) {
-          result = { ok: false, reason: skipReason, elapsedMs: elapsed() };
+          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() };
+          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,
           };
         }
       }
@@ -1978,11 +2237,20 @@ export async function probeApplyLeg(
   }
 
   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 } : {}),
     };
   }
-  return result;
+  // 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;
 }

package/src/codex-hooks-assets.ts

@@ -141,6 +141,66 @@ function findProjectRoot(startDir) {
   }
 }
 
+/**
+ * FR-1 (codex-hook-root-provenance): the ONE place both hooks compute their start directory and
+ * walk to a project root — replacing two independent copies of the same ternary. T1 (fix-round 1:
+ * the original reproducer had an unexported \`BASE\`, so it measured the wrong file; corrected and
+ * re-run — see the feature's change manifest for both) measured LIVE on \`codex-cli 0.154.0\`: three
+ * real \`codex exec\` sessions (project root, a nested subdirectory, a directory with no \`.dz\`
+ * anywhere in its ancestry), each with BOTH hook events (\`PreToolUse\` and \`UserPromptSubmit\`)
+ * captured SEPARATELY. \`payload.cwd\` was present and equal to both \`PWD\` and the hook's own
+ * \`process.cwd()\` in every one of the 6 captures. \`PWD\`/\`process.cwd()\` therefore stay only as a
+ * DEFENSIVE fallback for a payload shaped without \`cwd\` — not because that fallback was ever
+ * observed to fire. This is a SCOPED finding, not a claim that the "hook read the wrong project"
+ * defect class cannot exist: it was not observed on codex-cli 0.154.0 across these 3 scenarios / 6
+ * captures, and 01_requirements.md's own Ограничение C-3 is what permits cutting FR-3 (the explicit
+ * \`DZ_PROJECT_ROOT\` override) on a scoped finding like that — not a claim of nonexistence.
+ */
+function resolveHookRoot(payload) {
+  const hasPayloadCwd = typeof payload.cwd === 'string' && payload.cwd !== '';
+  const startDir = hasPayloadCwd ? payload.cwd : (process.env.PWD || process.cwd());
+  const source = hasPayloadCwd ? 'payload-cwd' : (process.env.PWD ? 'env-pwd' : 'process-cwd');
+  return { root: findProjectRoot(startDir), source, startDir };
+}
+
+/**
+ * Fix-round 1, item 4: a path interpolated into the provenance line below can itself carry control
+ * characters — a \`payload.cwd\` from an untrusted producer, or a \`PWD\` set to something hostile —
+ * and a bare newline in the middle of it would defeat the "ONE line" promise the diagnostic makes.
+ * Escape the whole C0 range (0x00-0x1F) plus DEL (0x7F) into a visible \`\\n\`/\\r\`/\\t\`/\\xHH\`
+ * representation; every other byte, including non-ASCII path segments, passes through unchanged.
+ */
+function escapeControlChars(value) {
+  return String(value).replace(/[\\x00-\\x1f\\x7f]/g, function (ch) {
+    var code = ch.charCodeAt(0);
+    if (code === 10) return '\\\\n';
+    if (code === 13) return '\\\\r';
+    if (code === 9) return '\\\\t';
+    return '\\\\x' + code.toString(16).padStart(2, '0');
+  });
+}
+
+/**
+ * FR-2: ONE provenance line, same shape as the Claude hook's (\`apply-leg.ts\`'s \`skip()\`), printed
+ * to stderr. When no root was found it ALWAYS prints (the walk's whole verdict was silent before
+ * this feature); when a root WAS found it prints only under \`DZ_CODEX_HOOK_DEBUG\`, so the found
+ * path stays byte-for-byte silent by default (NFR-2). Tradeoff, named plainly: this line discloses
+ * the absolute directory the hook was asked about (which can embed a username, a customer or
+ * repository name) to stderr — accepted because it is a diagnostic aimed at the person running the
+ * hook, not a return value, and redacting it would make the not-found case as silent as the bug
+ * this feature exists to fix. \`startDir\`/\`root\` are escaped via \`escapeControlChars\` first, so an
+ * adversarial value cannot itself defeat the "ONE line" guarantee.
+ */
+function reportRootProvenance(resolved) {
+  if (resolved.root === null) {
+    process.stderr.write(\`[\${HELPER}] skipped reason=no-project-root start=\${escapeControlChars(resolved.startDir)} (\${resolved.source})\\n\`);
+    return;
+  }
+  if (process.env.DZ_CODEX_HOOK_DEBUG) {
+    process.stderr.write(\`[\${HELPER}] root=\${escapeControlChars(resolved.root)} start=\${escapeControlChars(resolved.startDir)} (\${resolved.source})\\n\`);
+  }
+}
+
 function readProjectConfig(root) {
   try {
     return JSON.parse(fs.readFileSync(path.join(root, '.dz', 'config.json'), 'utf8'));
@@ -229,9 +289,10 @@ async function main() {
   const command = input && typeof input === 'object' ? input.command : undefined;
   if (typeof command !== 'string' || command === '') return 0;
 
-  const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : process.env.PWD || process.cwd();
-  const root = findProjectRoot(cwd);
-  if (root === null) return 0; // inert outside an opted-in dz project: no decision, no output, no write
+  const resolved = resolveHookRoot(payload);
+  reportRootProvenance(resolved);
+  const root = resolved.root;
+  if (root === null) return 0; // inert outside an opted-in dz project: no DECISION and no WRITE — one diagnostic line on stderr (FR-2), nothing else
 
   // (1) The destructive-command guard. Never blocks on our own failure: an absent module, a throw,
   // or an \`undecidable\` verdict all fall through to the shell veto below (AC-10).
@@ -370,8 +431,9 @@ async function main() {
   const prompt = typeof payload.prompt === 'string' ? payload.prompt : '';
   if (prompt.trim() === '') return;
 
-  const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : process.env.PWD || process.cwd();
-  const root = findProjectRoot(cwd);
+  const resolved = resolveHookRoot(payload);
+  reportRootProvenance(resolved);
+  const root = resolved.root;
   if (root === null) return; // inert outside an opted-in dz project
 
   const policy = await loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');

package/src/codex-hooks.ts

@@ -56,8 +56,20 @@ import { mergeManagedHookEntries } from './managed-hooks.js';
  * run was indistinguishable from a clean allow. The Claude hook already failed open loudly here.
  * Now it prints ONE line, `DZ-DESTRUCTIVE-WARN: classifier threw — <message>`, and still exits 0.
  * A changed body ⇒ re-trust.
+ * 8 — `codex-hook-root-provenance`: both hooks now share ONE `resolveHookRoot(payload)` instead of
+ * two copies of the same `payload.cwd || PWD || cwd()` ternary, and a silent `root === null` early
+ * return now prints one provenance line (`[dz-codex-<hook>] skipped reason=no-project-root
+ * start=<startDir> (<source>)`); the found-root path stays silent unless `DZ_CODEX_HOOK_DEBUG` is
+ * set. T1 (live probe, codex-cli 0.154.0) found `payload.cwd` always present and equal to `PWD`/
+ * `process.cwd()`, so no explicit-override knob was added. A changed body ⇒ re-trust.
+ * 9 — fix-round 1: the provenance line's interpolated paths are now escaped via
+ * `escapeControlChars` (C0 range + DEL) before printing, so a hostile `payload.cwd` cannot defeat
+ * the "ONE line" promise with an embedded newline; the corrected T1 re-run (both hook events
+ * captured separately, per-scenario — the original reproducer's `BASE` was never exported) reached
+ * the SAME conclusion, scoped honestly as "not observed on codex-cli 0.154.0 across 3 scenarios / 6
+ * captures", not "does not exist". A changed body ⇒ re-trust.
  */
-export const DZ_HOOK_HELPER_VERSION = 7;
+export const DZ_HOOK_HELPER_VERSION = 9;
 
 /** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
 export const DZ_HOOK_TIMEOUT_SECONDS = 5;

package/src/index.ts

@@ -203,6 +203,9 @@ export {
   mirrorPatternsToVector,
   backfillVectorMirror,
   mergeHybridHits,
+  compareHybridHits,
+  evidenceRank,
+  orderHitsForReRank,
   recallHybrid,
   teachGuard,
   vectorTierStatus,
@@ -224,6 +227,7 @@ export type {
   HybridRecall,
   HybridRecallMode,
   HybridHit,
+  HybridOrderKey,
   RankedPattern,
   VectorServiceOptions,
   VectorTierStatus,
@@ -730,7 +734,8 @@ export type {
   ChainDefectAges,
   ChainedJournal,
 } from './event-chain.js';
-export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, rewriteWorkspaceSpecs, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion } from './publish.js';
+export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, rewriteWorkspaceSpecs, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion, planReadmeVersionSync } from './publish.js';
+export type { ReadmeVersionSyncPlan, ReadmeSyncRewrite } from './publish.js';
 export { RELEASE_LINE_RE, findReleaseLine, rewriteReleaseLine } from './release-line.js';
 export * from './course-staleness.js';
 export { fetchAllDownloads } from './downloads.js';

package/src/operations.ts

@@ -1893,8 +1893,19 @@ export function probeHookLiveness(
   command: string,
   payload: string,
   opts: { readonly cwd?: string; readonly env?: Readonly<Record<string, string>>; readonly timeoutMs?: number } = {},
-): { readonly status: number | null; readonly stdout: string; readonly stderr: string } {
+): { readonly status: number | null; readonly stdout: string; readonly stderr: string; readonly groupKillAttempted: boolean } {
   const shell = process.env['SHELL'] ?? '/bin/sh';
+  // Fix round 1 (apply-leg-never-silent, HIGH-1): a caller previously had to INFER "was the group
+  // kill sent" by reading this function's source — a regression removing or bypassing the
+  // `process.kill(-pid, ...)` call below would silently invalidate that inference. `groupKillAttempted`
+  // is the OBSERVABLE fact instead: true exactly when this call reached the point of attempting the
+  // kill syscall (`res.pid` was a real positive pid), false when it never got that far (e.g. the
+  // spawn itself never produced a pid). It does NOT claim the signal found a live recipient — ESRCH
+  // ("group already gone", the common successful-exit case) still counts as "sent": the syscall was
+  // issued, its target simply no longer existed. That is a SEPARATE fact from whether the grandchild
+  // is actually dead by the time a caller checks — see `probeApplyLeg`'s AM-5 test for the
+  // kill-sent-vs-death-observed split this field exists to make possible.
+  let groupKillAttempted = false;
   try {
     // AM-5 (fix round 1, apply-leg-never-silent): `detached: true` puts the shell in its OWN
     // process GROUP (pgid === its own pid) instead of sharing the caller's — `spawnSync`'s own
@@ -1925,11 +1936,15 @@ export function probeHookLiveness(
         process.kill(-res.pid, 'SIGKILL');
       } catch {
         /* group already gone */
+      } finally {
+        // set right after the process.kill(-pid, 'SIGKILL') attempt (HIGH-1 lead decision): reached
+        // regardless of ESRCH, because ESRCH means "no recipient", not "syscall not issued".
+        groupKillAttempted = true;
       }
     }
-    return { status: res.status, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+    return { status: res.status, stdout: res.stdout ?? '', stderr: res.stderr ?? '', groupKillAttempted };
   } catch (err) {
-    return { status: null, stdout: '', stderr: String((err as Error)?.message ?? err) };
+    return { status: null, stdout: '', stderr: String((err as Error)?.message ?? err), groupKillAttempted };
   }
 }