@dzhechkov/harness-core 0.8.33 → 0.8.35

package/src/index.ts

@@ -12,6 +12,12 @@ export const HARNESS_CORE_VERSION: string =
 
 export { REPOSITORY_ORIGIN } from './repository-origin.js';
 
+// Fix-round 1 (feature recall-short-terms, Codex HIGH-1c): `dz recall`'s CLI printer needs the
+// single source of truth for "why did this query tokenize to nothing" without harness-cli taking
+// a new direct dependency on `@dzhechkov/memory` (a publishing-surface change outside this
+// feature's scope) — harness-core already depends on memory, so it re-exports the one helper.
+export { noSearchableTermsReason } from '@dzhechkov/memory';
+
 export * from './skills.js';
 export * from './apply.js';
 export {
@@ -246,6 +252,7 @@ export {
   applyLegHookEntries,
   applyLegStatus,
   applyLegReasonMessage,
+  probeApplyLeg,
   resolveIdleMs,
   IDLE_MS_INT32_MAX,
 } from './apply-leg.js';
@@ -255,6 +262,7 @@ export type {
   ApplyLegHookPresence,
   ApplyLegStatus,
   ApplyLegNotInstalledReason,
+  ApplyLegProbeResult,
   ResolvedIdleMs,
 } from './apply-leg.js';
 // embed-socket-short-path: the ONE resolver the daemon (inlined text), the recall hook (inlined
@@ -303,7 +311,7 @@ export {
   segmentRun,
 } from './eta.js';
 export type { CheckpointObservation, EtaEstimate, EtaInput, IncompleteCoverageSample, RunSegment, StageDurationSample, StageSample } from './eta.js';
-export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES, ensureAgentdbSchema } from './agentdb-index.js';
+export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, resetAgentdbEmbedderCache, getAgentdbEmbedderCacheStats, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES, ensureAgentdbSchema, readStoreGeneration, bumpStoreGeneration } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
 export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
 export type { EmbedModelConfig, EmbedModelSource, EmbedManifest } from './embedding-config.js';
@@ -742,6 +750,8 @@ export {
   buildReleaseNotes,
   releaseTagName,
   firstOutputLine,
+  testsFailureDetail,
+  outputTail,
   RELEASE_GATE_ORDER,
   RELEASE_TIMEOUTS,
 } from './release.js';
@@ -763,13 +773,19 @@ export type {
 } from './release.js';
 export { formatPublishError } from './publish.js';
 // Sibling-drift + packed-install-smoke gates (feature publish-sibling-drift-gate, ADR-001).
-export { detectSiblingDrift } from './publish-sibling-drift.js';
+export { detectSiblingDrift, parseNpmPackInventory } from './publish-sibling-drift.js';
 export type {
   SiblingDriftStatus,
+  InventorySource,
   SiblingDriftResult,
   FetchedPublished,
   FetchPublished,
   DetectSiblingDriftOptions,
+  PackInventory,
+  PackInventoryUnavailable,
+  LocalInventoryResult,
+  PackedTree,
+  LocalInventory,
 } from './publish-sibling-drift.js';
 export { planPackedInstallSmoke, judgePackedInstallSmoke, packedTarballName } from './packed-install-smoke.js';
 export type {

package/src/mutation-gate.ts

@@ -77,6 +77,22 @@ export interface MutationRegistry {
   readonly testCommand?: string;
   /** opt-in proof that the suite harness reached its clean completion path. */
   readonly requireCompletionReceipt?: boolean;
+  /**
+   * optional per-registry suite-run ceiling in milliseconds (mutation-gate-timeout-verdict FR-3):
+   * a package whose real baseline runs longer than the executor's 300000ms default (e.g. this
+   * repo's core package, MEASURED ≈5-8 min) declares its own floor here so `dz mutation-gate` with
+   * no `--timeout` flag still succeeds — precedence is flag > this field > the 300000ms default.
+   */
+  readonly timeoutMs?: number;
+  /**
+   * optional per-registry vitest worker ceiling (mutation-gate-baseline-honesty FR-2): baseline and
+   * mutant runs spawn the package's FULL `testCommand` at vitest's default worker count (= cpu
+   * cores), and under embedding-daemon tests (0.7-3.5 GB/process) this repo's core package measured
+   * load 62-358 and 0.4-1.8 GB free on an 8-core/16GB box — three full runs died overnight
+   * (0bb74d66). The same suite with `--maxWorkers=2` passed (6909/6909). Precedence is the
+   * `--max-workers` flag > this field > `min(4, max(1, floor(cpus/2)))`.
+   */
+  readonly maxWorkers?: number;
   readonly entries: readonly MutationRegistryEntry[];
 }
 
@@ -306,10 +322,12 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
   let entriesRaw: unknown;
   let testCommand: string | undefined;
   let requireCompletionReceipt: boolean | undefined;
+  let timeoutMs: number | undefined;
+  let maxWorkers: number | undefined;
   if (Array.isArray(raw)) {
     entriesRaw = raw;
   } else if (raw && typeof raw === 'object') {
-    const obj = raw as { testCommand?: unknown; requireCompletionReceipt?: unknown; entries?: unknown };
+    const obj = raw as { testCommand?: unknown; requireCompletionReceipt?: unknown; timeoutMs?: unknown; maxWorkers?: unknown; entries?: unknown };
     entriesRaw = obj.entries;
     if (obj.testCommand !== undefined) {
       if (typeof obj.testCommand !== 'string' || obj.testCommand.trim() === '') {
@@ -323,6 +341,18 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
       }
       requireCompletionReceipt = obj.requireCompletionReceipt;
     }
+    if (obj.timeoutMs !== undefined) {
+      if (typeof obj.timeoutMs !== 'number' || !Number.isFinite(obj.timeoutMs) || obj.timeoutMs <= 0) {
+        return { registry: null, entryResults: [], errors: ['timeoutMs must be a finite number > 0 when present'] };
+      }
+      timeoutMs = obj.timeoutMs;
+    }
+    if (obj.maxWorkers !== undefined) {
+      if (typeof obj.maxWorkers !== 'number' || !Number.isInteger(obj.maxWorkers) || obj.maxWorkers < 1) {
+        return { registry: null, entryResults: [], errors: ['maxWorkers must be a positive integer when present'] };
+      }
+      maxWorkers = obj.maxWorkers;
+    }
   }
   if (!Array.isArray(entriesRaw)) {
     return { registry: null, entryResults: [], errors: ['registry must be an array of entries or {testCommand?, requireCompletionReceipt?, entries: [...]}'] };
@@ -439,6 +469,8 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
     registry: {
       ...(testCommand !== undefined ? { testCommand } : {}),
       ...(requireCompletionReceipt !== undefined ? { requireCompletionReceipt } : {}),
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      ...(maxWorkers !== undefined ? { maxWorkers } : {}),
       entries,
     },
     entryResults,
@@ -446,6 +478,26 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
   };
 }
 
+// ── Feature scoping (qe-step-gate-scoped-to-feature) — pure registry diff, no IO ───────────────
+//
+// Step 8's QE mutation gate ran the FULL registry unconditionally (MEASURED 2026-09-12: 358
+// entries on this repo's core package, 30-40 minutes, timed out INCONCLUSIVE every time), though a
+// feature only owns its own touched files and any entries it newly declares. The `--touched` and
+// `--added-since` CLI selectors (harness-cli's executor) scope the run; the executor reads the base
+// registry via `git show <ref>:<path>` (I/O) and hands both parsed registries to this PURE diff so
+// the comparison itself stays testable without a filesystem or git process (NFR-1).
+
+/** Entry ids present in `current` but absent from `base` (by id, not by content). A `null` base
+ *  means the registry did not exist at the reference point — every current entry counts as added. */
+export function registryEntriesAddedSince(
+  base: MutationRegistry | null,
+  current: MutationRegistry,
+): string[] {
+  if (base === null) return current.entries.map((entry) => entry.id);
+  const baseIds = new Set(base.entries.map((entry) => entry.id));
+  return current.entries.filter((entry) => !baseIds.has(entry.id)).map((entry) => entry.id);
+}
+
 // ── Mutation application — exact text surgery, exactly once (rule 1) ──────────────────────────
 
 export interface AppliedMutation {
@@ -732,7 +784,11 @@ export function attributeBaselineRedness(
     if (file !== null && !files.includes(file)) files.push(file);
   };
 
-  const vitestMatches = [...output.matchAll(/^\s*FAIL\s+(\S+)/gm)];
+  // mutation-gate-baseline-honesty FR-1: vitest 3 prints an optional POOL LABEL between `FAIL` and
+  // the file path (`FAIL  |serial| test/x.test.ts > case`, `FAIL  |parallel| …`) — the plain
+  // `(\S+)` used to capture the label itself as "the file", which normaliseReportedFile then
+  // rejects, turning a perfectly parseable red run into `unparseable from runner output`.
+  const vitestMatches = [...output.matchAll(/^\s*FAIL\s+(?:\|[^|\n]*\|\s+)?(\S+)/gm)];
   for (const match of vitestMatches) add(match[1] ?? '');
 
   const tapMatches = [...output.matchAll(/^not ok \d+\s+-\s+(.+)$/gm)];

package/src/operations.ts

@@ -6,7 +6,7 @@
  * @packageDocumentation
  */
 
-import { execFileSync, spawnSync } from 'node:child_process';
+import { execFileSync, spawnSync, type SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
@@ -1437,18 +1437,34 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       const WRITER_EVENTS = ['SessionStart', 'SessionEnd', 'PreCompact'];
       let eventsWithWriter: string[] = [];
       let settingsReadable = false;
+      // Lead edit after Codex review (finding 1, 2026-09-13): three states, not a boolean — an
+      // EXISTING settings.json that cannot be parsed is "unknowable", never "agrees".
+      const settingsPath = join(root, '.claude', 'settings.json');
+      const settingsPresent = existsSync(settingsPath);
       try {
-        const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf-8')) as {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
           hooks?: Record<string, unknown[]>;
         };
-        settingsReadable = true;
         eventsWithWriter = WRITER_EVENTS.filter((ev) => (settings.hooks?.[ev] ?? []).some((h) => commandsOf(h).some(invokesWriter)));
+        // Lead edit after Codex round 2 (new finding 2): "readable" means the hooks were actually
+        // INSPECTED — a parseable but malformed shape (`null`, a non-array event) throws inside the
+        // traversal and must land in the "cannot be compared" row, never in the OK row.
+        settingsReadable = true;
       } catch {
       }
+      const settingsUnreadable = settingsPresent && !settingsReadable;
       const allWired = eventsWithWriter.length === WRITER_EVENTS.length;
       const hooksInvokeAgentdbWriter = eventsWithWriter.length > 0;
 
-      if (configuredMemoryBackend === 'agentdb' && !allWired) {
+      if (settingsUnreadable) {
+        // Lead edit after Codex round 2: precedence — an unparseable settings.json is diagnosed FIRST for
+        // both backends; the hooks are UNKNOWABLE, so neither "not wired" nor "in agreement" may be claimed.
+        checks.push({
+          name: 'memory hooks match config',
+          ok: false,
+          detail: `.dz/config.json says memory.backend=${configuredMemoryBackend} but .claude/settings.json exists and could not be parsed or inspected (invalid JSON or a malformed hooks shape) — the hooks cannot be compared; fix the file (or re-run dz setup)`,
+        });
+      } else if (configuredMemoryBackend === 'agentdb' && !allWired) {
         checks.push({
           name: 'memory hooks match config',
           ok: false,
@@ -1460,6 +1476,15 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
           ok: false,
           detail: '.dz/config.json says memory.backend=jsonl but SessionStart/SessionEnd/PreCompact hooks still invoke agentdb-writer.mjs — run: dz setup --target claude-code --memory jsonl (or --memory agentdb to keep agentdb and bring the config back in sync)',
         });
+      } else {
+        // the OK receipt comes from the SAME comparison that produces the red rows (all three events observed)
+        checks.push({
+          name: 'memory hooks match config',
+          ok: true,
+          detail: configuredMemoryBackend === 'agentdb'
+            ? 'memory.backend=agentdb — SessionStart/SessionEnd/PreCompact all invoke .dz/agentdb-writer.mjs'
+            : `memory.backend=jsonl — SessionStart/SessionEnd/PreCompact do not invoke .dz/agentdb-writer.mjs${settingsPresent ? '' : ' (no .claude/settings.json — no hooks at all)'}`,
+        });
       }
     }
     // configuredMemoryBackend === 'unknown': no .dz/config.json yet — nothing to compare, same
@@ -1498,13 +1523,52 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
             resolved.reason === 'tmpdir-short'
               ? ` (tmpdir-short: project path ${projectPathBytes} bytes > ${EMBED_SOCKET_PATH_BYTES_LIMIT})`
               : '';
+          // FR-6 (hook-recall-hybrid-parity): a socket that merely EXISTS is not proof of what it
+          // answers with — probe it. A non-live fixture (a plain file, no listener) fails the probe
+          // near-instantly and this note stays empty, so every pre-existing detail string here is
+          // untouched.
+          // AM-8 (fix round 1): the socket-speaking probe itself now lives in apply-leg.ts (the
+          // module that already owns the daemon's wire protocol + socket-path resolution) rather
+          // than duplicating a `node:net` IO surface here — dynamic `import()`, same pattern as
+          // `embed-socket-path.js` two lines above, so operations.ts carries no new top-level IO
+          // import for this.
+          const { probeRecallEngine } = await import('./apply-leg.js');
+          const engine = sockAlive ? await probeRecallEngine(resolved.path) : undefined;
+          const engineNote = engine !== undefined ? ` (engine: ${engine})` : '';
           checks.push({
             name: 'apply-leg alive (embed daemon)',
             ok: sockAlive,
             detail: sockAlive
-              ? `embed socket present at ${resolved.path}${tmpdirNote} — recall injection can run`
+              ? `embed socket present at ${resolved.path}${tmpdirNote}${engineNote} — recall injection can run`
               : `embed socket ABSENT at ${resolved.path}: the recall hook is wired but cannot inject (the hook self-heals on the next prompt; a persistent absence means the daemon cannot start)`,
           });
+
+          // APPLY-LEG INJECTS — live probe (feature `apply-leg-never-silent`, ADR-001 Decision 1).
+          // Issue #2's whole defect was that `installed`/`alive` above can ALL read green while the
+          // leg injects nothing in every session but one (a foreign install-root symptom the file-
+          // presence and socket-presence checks above cannot see by construction — they check for
+          // the RIGHT FILES at the RIGHT PATH, never whether the deployed COMMAND actually resolves
+          // to this project's store from a foreign cwd). This row is the difference: it runs the
+          // ACTUAL configured hook command end-to-end and is green ONLY on an observed injection.
+          // Deliberately a SEPARATE try/catch from the socket-alive check above: a probe failure
+          // must never suppress the (already useful) socket-presence row, and vice versa.
+          try {
+            const { probeApplyLeg } = await import('./apply-leg.js');
+            const probe = await probeApplyLeg(root);
+            checks.push({
+              name: 'apply-leg injects (live probe)',
+              ok: probe.ok,
+              detail: probe.ok
+                ? `live probe injected its beacon lesson in ${probe.elapsedMs}ms — the recall hook actually finds this project's store`
+                : `installed but silent: ${probe.reason ?? 'unknown'} (probed in ${probe.elapsedMs}ms) — dz setup wrote the hook, but it is not injecting anything into real sessions`,
+            });
+          } catch (err) {
+            checks.push({
+              name: 'apply-leg injects (live probe)',
+              ok: false,
+              detail: `live probe could not run: ${err instanceof Error ? err.message : String(err)}`,
+            });
+          }
         }
       }
     } catch {
@@ -1815,18 +1879,57 @@ function probeCodexVersion(): string | null {
  * with the helper's own self-failure note unable to fire because the process never started.
  * Grading on file presence would call that "installed".
  */
-export function probeHookLiveness(command: string, payload: string): { readonly status: number | null; readonly stderr: string } {
+/**
+ * `opts` (feature `apply-leg-never-silent`, ADR-001 D1): additive, optional — every pre-existing
+ * 2-arg caller (the Codex veto-hook liveness checks above) is unaffected. `cwd`/`env` let a caller
+ * reproduce the EXACT conditions a real invoking session presents (a foreign cwd, an overridden
+ * `CLAUDE_PROJECT_DIR`) rather than always running from THIS process's own cwd/env — the apply-leg
+ * live probe needs exactly that to prove install-root resolution end-to-end, not merely structurally.
+ * `stdout` is returned alongside `stderr`/`status` for the same reason: a UserPromptSubmit hook's
+ * payload (`hookSpecificOutput.additionalContext`) rides stdout, not stderr (see `probeApplyLeg`'s
+ * own doc comment for the measured stderr-visibility fact this displaces).
+ */
+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 } {
   const shell = process.env['SHELL'] ?? '/bin/sh';
   try {
-    const res = spawnSync(shell, ['-lc', command], {
+    // 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
+    // timeout kill signals only the DIRECT child (the shell), never anything the shell forked, so a
+    // `node "<hook>" || true` grandchild that is still running when the shell dies is orphaned but
+    // free to keep touching whatever this probe is about to remove (the beacon, the temp cwd).
+    // Killing the NEGATIVE pid below reaches the whole group in one signal. `@types/node`'s
+    // `SpawnSyncOptions` does not DECLARE `detached` (only the async `SpawnOptions` does) — MEASURED
+    // this is a typings gap, not a runtime one: a real child under `spawnSync(..., {detached:true})`
+    // reports its own pgid === its own pid (verified with `ps -o pgid=`), exactly as it would under
+    // async `spawn`. Widened via an inline type intersection rather than `as any` so every OTHER key
+    // stays checked.
+    const spawnOpts: SpawnSyncOptionsWithStringEncoding & { readonly detached?: boolean } = {
       input: payload,
       encoding: 'utf8',
-      timeout: 20_000,
-      env: { ...process.env, DZ_HOOK_LIVENESS_PROBE: '1' },
-    });
-    return { status: res.status, stderr: res.stderr ?? '' };
+      timeout: opts.timeoutMs ?? 20_000,
+      detached: true,
+      ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+      env: { ...process.env, DZ_HOOK_LIVENESS_PROBE: '1', ...(opts.env ?? {}) },
+    };
+    const res = spawnSync(shell, ['-lc', command], spawnOpts);
+    // Belt, run on EVERY outcome (timeout OR a clean, on-time exit): a `node` grandchild can still
+    // be alive in the group even after the shell itself exited normally (e.g. it double-forked or
+    // outlived a `|| true` that already returned). ESRCH — the common, successful case, everything
+    // already exited — is swallowed; this is best-effort cleanup, never a probe failure.
+    if (typeof res.pid === 'number' && res.pid > 0) {
+      try {
+        process.kill(-res.pid, 'SIGKILL');
+      } catch {
+        /* group already gone */
+      }
+    }
+    return { status: res.status, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
   } catch (err) {
-    return { status: null, stderr: String((err as Error)?.message ?? err) };
+    return { status: null, stdout: '', stderr: String((err as Error)?.message ?? err) };
   }
 }
 
@@ -2006,7 +2109,7 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
   //     a home that never opted in (the leg-1 F12 lesson).
   if (options.check === true) {
     const drift = diffCodexHooks(currentText, entries, manifest);
-    const live = drift.installed && options.liveness !== false ? probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD) : { status: null, stderr: '' };
+    const live = drift.installed && options.liveness !== false ? probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD) : { status: null, stdout: '', stderr: '' };
     const executable = drift.installed && (options.liveness === false || live.status === 0 || live.status === 2);
     // `--check` must report the TRUST axis too. Without it the report said `installed && executable`
     // with `trust: 'unknown'`, and the CLI printed a success word for it — the exact G-G/AM-17
@@ -2105,7 +2208,7 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
 
 
   // (6) LIVENESS: exit 127 is ALLOW to the runtime, so it must never be graded as installed (G-L).
-  const live = options.liveness === false ? { status: 0, stderr: '' } : probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD);
+  const live = options.liveness === false ? { status: 0, stdout: '', stderr: '' } : probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD);
   const executable = live.status === 0 || live.status === 2;
   if (!executable) {
     warnings.push(

package/src/publish-sibling-drift.ts

@@ -28,10 +28,24 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, relative } from 'node:path';
+import { join, relative, isAbsolute } from 'node:path';
 
 export type SiblingDriftStatus = 'same' | 'drift' | 'unavailable';
 
+/**
+ * AM-6 (feature publish-gate-audit-durable): which mechanism produced BOTH sides' file inventory
+ * for this comparison — named on every result, never left implicit. `'npm-pack'`: the caller
+ * injected {@link DetectSiblingDriftOptions.localInventory} (the CLI's `npm pack --dry-run --json`
+ * via {@link parseNpmPackInventory}); the workspace side is exactly what npm will ship, and the
+ * published side is hashed by a FULL recursive walk of the already-unpacked tarball (AM-1 — the
+ * two sides must be symmetric: "every file npm put there" on one side, "every file npm will put
+ * there" on the other). `'readdir-approximation'`: no provider was injected — BOTH sides fall back
+ * to the pre-existing `dist`/`files`/`bin` walk ({@link shippedInventoryDirs}), which stays
+ * symmetric by construction (same function, same rules, both sides) but can miss a file
+ * `.npmignore` excludes or include one npm would never ship.
+ */
+export type InventorySource = 'npm-pack' | 'pnpm-pack' | 'readdir-approximation';
+
 export interface SiblingDriftResult {
   readonly name: string;
   readonly version: string;
@@ -42,6 +56,12 @@ export interface SiblingDriftResult {
   readonly missingExports: readonly string[];
   /** Present only when status === 'unavailable'. */
   readonly reason?: string;
+  /**
+   * AM-6: named per-result (not merely per-call) because `detectSiblingDrift` short-circuits to
+   * `'unavailable'` before ever reaching the hashing step for some entries — those still carry the
+   * source that WOULD have been used, so a reader never has to guess.
+   */
+  readonly inventorySource: InventorySource;
 }
 
 export interface FetchedPublished {
@@ -65,6 +85,21 @@ export interface DetectSiblingDriftOptions {
   /** Names being published in THIS batch — they publish fresh, so drift cannot be measured against them. */
   readonly batch: ReadonlySet<string>;
   readonly fetchPublished: FetchPublished;
+  /**
+   * FR-3 (feature publish-gate-audit-durable): the LOCAL (workspace) package's shipped-file
+   * inventory, asked from npm instead of approximated by walking `dist`/`files`/`bin` by hand —
+   * `.npmignore` and nested ignore rules make the hand-rolled walk wrong in both directions (a file
+   * npm will never ship can still be read off disk, producing a false drift). No production default
+   * lives in THIS module — core stays pure (never spawns `npm`, per the core-boundary import
+   * ratchet). The CLI runs `npm pack --dry-run --json` and hands the stdout to
+   * {@link parseNpmPackInventory}, then passes the resulting closure here; a caller that injects
+   * nothing (`undefined`) makes `detectSiblingDrift` fall back to the named
+   * `'readdir-approximation'` {@link InventorySource} on BOTH sides (AM-1) — never a silent "no
+   * drift".
+   */
+  readonly localInventory?: LocalInventory;
+  /** Label for the injected provider's source (default `'npm-pack'`); the CLI passes `'pnpm-pack'` for a packed tree. */
+  readonly localInventorySource?: InventorySource;
 }
 
 function listFilesRecursive(root: string, dir: string): string[] {
@@ -83,6 +118,120 @@ function sha256(data: string | Buffer): string {
   return createHash('sha256').update(data).digest('hex');
 }
 
+// ── FR-3 (feature publish-gate-audit-durable): ask npm, don't approximate ──────────────────────
+
+/** The exact set of relative paths `npm pack` will ship for a package — no `.npmignore` guessing. */
+export interface PackInventory {
+  readonly paths: readonly string[];
+}
+
+/** `npm pack --dry-run --json` could not be run or answered in a shape this code cannot use. */
+export interface PackInventoryUnavailable {
+  readonly unavailable: string;
+}
+
+/**
+ * Lead fix after the fix-round's live dry-run (2026-09-14 01:02): the workspace side PACKED BY THE
+ * LIVE TRANSPORT (`pnpm pack`) and unpacked into `packedDir`. pnpm synthesises a LICENSE from the
+ * workspace root into the tarball of a package whose own tree has none; `npm pack --dry-run --json`
+ * never lists that file, so a `paths` inventory read every such sibling as "LICENSE only in the
+ * published copy" — 2 false drifts (harness-presets, scout) on a tree unchanged since publication.
+ * A packed tree is hashed by the SAME full walk as the published side, symmetric by construction.
+ */
+export interface PackedTree {
+  readonly packedDir: string;
+}
+
+export type LocalInventoryResult = PackInventory | PackedTree | PackInventoryUnavailable;
+
+/** Ask what npm would ship for the package rooted at `dir`. Injected in tests (no subprocess). */
+export type LocalInventory = (dir: string) => LocalInventoryResult;
+
+/**
+ * C-1/AM-4: `npm pack --dry-run --json` is a real subprocess call — the CLI caches its result per
+ * absolute directory for the lifetime of ONE `dz publish` run (not per package being checked), so
+ * a run that checks the same sibling from more than one dependent package packs it only once. Core
+ * itself never runs the subprocess or owns the cache (core-boundary import ratchet) — this parser
+ * is the pure half only.
+ *
+ * Parses `npm pack --dry-run --json`'s stdout (an array with one element; `files[]` holds
+ * `{path,size,mode}` per shipped path, plus `integrity`/`shasum`/`entryCount`) into the exact set of
+ * relative paths npm intends to ship, honouring `.npmignore`/`files`/default-ignore exactly the way
+ * a real `npm publish` would. A failure to run, parse, or make sense of the shape — including a
+ * malformed individual `files[]` element (AM-5: a corrupt entry is a reason to say the WHOLE
+ * inventory is untrustworthy, never a file to silently drop) — is `{ unavailable: reason }`: an
+ * input this gate cannot read is a reason to say so, never a silent "nothing to compare".
+ */
+export function parseNpmPackInventory(stdout: string): LocalInventoryResult {
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    const entry = Array.isArray(parsed) ? (parsed[0] as unknown) : undefined;
+    const files = entry !== null && typeof entry === 'object' ? (entry as Record<string, unknown>)['files'] : undefined;
+    if (!Array.isArray(files)) return { unavailable: 'npm pack --dry-run --json returned no files[] array' };
+    // AM-5 (Codex round-1 finding 6, medium): a malformed element used to be `.filter()`ed out
+    // silently — a `files[]` entry npm itself always shapes as `{path,size,mode}` should never fail
+    // to parse; if one DOES (missing/non-string `path`, or a non-object element), that is a signal
+    // this output cannot be trusted, not a single file to quietly drop from the comparison. Say so.
+    const paths: string[] = [];
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      if (f === null || typeof f !== 'object') {
+        return { unavailable: `npm pack --dry-run --json files[${i}] is not an object (got ${JSON.stringify(f)})` };
+      }
+      const path = (f as Record<string, unknown>)['path'];
+      if (typeof path !== 'string' || path === '') {
+        return { unavailable: `npm pack --dry-run --json files[${i}].path is missing or not a non-empty string (got ${JSON.stringify(path)})` };
+      }
+      paths.push(path);
+    }
+    return { paths };
+  } catch (err) {
+    return { unavailable: `npm pack --dry-run --json output could not be parsed: ${(err as Error).message.split('\n')[0]}` };
+  }
+}
+
+/** Hash exactly the paths `npm pack` names (package.json normalized separately, as {@link hashTree} does). */
+/**
+ * Codex round-2 (2026-09-14) new findings 1+2: a listed path that is absent, a directory, absolute,
+ * or that climbs out of `dir` via `..` used to be SKIPPED silently — a comparison over a listing
+ * the tree does not match is not a comparison, it is `unavailable`; and an inventory must never
+ * read outside the package directory. Thrown here, turned into an `unavailable` result by the caller.
+ */
+class InventoryListingError extends Error {}
+
+function hashTreeFromPaths(dir: string, paths: readonly string[], manifest: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const rel of paths) {
+    if (rel === 'package.json') continue; // normalized below, not hashed raw
+    if (isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+      throw new InventoryListingError(`inventory path "${rel}" is absolute or leaves the package directory`);
+    }
+    const abs = join(dir, rel);
+    if (!existsSync(abs)) throw new InventoryListingError(`inventory path "${rel}" does not exist in the workspace copy`);
+    if (statSync(abs).isDirectory()) throw new InventoryListingError(`inventory path "${rel}" is a directory, not a file`);
+    map.set(rel, sha256(readFileSync(abs)));
+  }
+  map.set('package.json', sha256(normalizedPackageJsonText(manifest)));
+  return map;
+}
+
+/**
+ * AM-1: hash EVERY file under `dir` (the already-unpacked published tarball) — the literal "full
+ * recursive walk of what npm put there" the amendment names, used ONLY as the symmetric partner to
+ * {@link hashTreeFromPaths} (i.e. only when a `localInventory` provider is injected). `dir` here is
+ * always an extracted tarball, never the workspace tree, so there is no `.npmignore` to consult:
+ * everything that exists on disk is, by construction, exactly what npm shipped.
+ */
+function hashTreeFull(dir: string, manifest: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const rel of listFilesRecursive(dir, dir)) {
+    if (rel === 'package.json') continue; // normalized below, not hashed raw
+    map.set(rel, sha256(readFileSync(join(dir, rel))));
+  }
+  map.set('package.json', sha256(normalizedPackageJsonText(manifest)));
+  return map;
+}
+
 /**
  * package.json PARSED and validated. `null` (never `undefined`) means "this side cannot be built
  * at all" — AM-3: a missing or unparseable manifest on EITHER side must surface as `unavailable`,
@@ -208,6 +357,9 @@ function missingExportNames(publishedDir: string, workspaceDir: string): string[
 export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDriftResult[] {
   const results: SiblingDriftResult[] = [];
   const seen = new Set<string>();
+  // AM-6: named ONCE per call — every result below (including the short-circuited `unavailable`
+  // ones) carries the source that is or would have been used for this comparison.
+  const inventorySource: InventorySource = opts.localInventory !== undefined ? (opts.localInventorySource ?? 'npm-pack') : 'readdir-approximation';
   // AM-3: `optionalDependencies` ships and pins EXACTLY like `dependencies`/`peerDependencies` —
   // checking only the first two let a stale optional sibling through untouched (round-1 finding 3).
   const entries = [
@@ -233,6 +385,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `${dep} is declared workspace:-protocol but is not a known workspace package`,
+        inventorySource,
       });
       continue;
     }
@@ -246,6 +399,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `could not fetch ${dep}@${version} from the registry (network unavailable or the version was not found)`,
+        inventorySource,
       });
       continue;
     }
@@ -264,12 +418,62 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         changedFiles: [],
         missingExports: [],
         reason: `${dep}@${version}: package.json in ${side} is missing or not valid JSON — cannot compare`,
+        inventorySource,
       });
       continue;
     }
 
-    const publishedHashes = hashTree(fetched.dir, publishedManifest);
-    const workspaceHashes = hashTree(workspaceDir, workspaceManifest);
+    // FR-3/AM-1: the LOCAL package's inventory comes from npm, not from a hand-rolled dist/files/bin
+    // walk — `.npmignore` (and nested ignore rules) can exclude a file this gate would otherwise walk
+    // straight into, producing a false drift about a file npm was never going to ship. AM-1 (Codex
+    // review, round-1 finding 3, high): the two sides must stay SYMMETRIC. With a provider injected,
+    // the workspace side is npm's OWN shipped-path list; the published side must then be hashed by a
+    // FULL recursive walk of the already-unpacked tarball (every file npm actually put there —
+    // README/LICENSE included, since npm auto-packs those regardless of `files`), not the narrower
+    // `dist`/`files`/`bin` approximation `hashTree` uses — that approximation would silently OMIT an
+    // auto-packed README/LICENSE from the published side while the workspace side (via real `npm
+    // pack`) correctly includes them, reading as a false "only in workspace" drift. WITHOUT a
+    // provider, core has no way to ask npm on either side, so it degrades to the SAME approximation
+    // on BOTH sides (symmetry preserved, just cruder) — a named approximation, never a subprocess.
+    let workspaceHashes: Map<string, string>;
+    let publishedHashes: Map<string, string>;
+    if (opts.localInventory !== undefined) {
+      const localResult = opts.localInventory(workspaceDir);
+      if ('unavailable' in localResult) {
+        results.push({
+          name: dep,
+          version,
+          status: 'unavailable',
+          changedFiles: [],
+          missingExports: [],
+          reason: `${dep}@${version}: local package inventory unavailable (${localResult.unavailable})`,
+          inventorySource,
+        });
+        continue;
+      }
+      try {
+        workspaceHashes = 'packedDir' in localResult
+          ? hashTreeFull(localResult.packedDir, workspaceManifest)
+          : hashTreeFromPaths(workspaceDir, localResult.paths, workspaceManifest);
+      } catch (err) {
+        if (!(err instanceof InventoryListingError)) throw err;
+        results.push({
+          name: dep,
+          version,
+          status: 'unavailable',
+          changedFiles: [],
+          missingExports: [],
+          reason: `${dep}@${version}: local package inventory unusable (${err.message})`,
+          inventorySource,
+        });
+        continue;
+      }
+      publishedHashes = hashTreeFull(fetched.dir, publishedManifest);
+    } else {
+      workspaceHashes = hashTree(workspaceDir, workspaceManifest);
+      publishedHashes = hashTree(fetched.dir, publishedManifest);
+    }
+
     const allKeys = new Set<string>([...publishedHashes.keys(), ...workspaceHashes.keys()]);
     const changed: string[] = [];
     for (const key of allKeys) {
@@ -278,7 +482,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
     changed.sort();
 
     if (changed.length === 0) {
-      results.push({ name: dep, version, status: 'same', changedFiles: [], missingExports: [] });
+      results.push({ name: dep, version, status: 'same', changedFiles: [], missingExports: [], inventorySource });
     } else {
       results.push({
         name: dep,
@@ -286,6 +490,7 @@ export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDrif
         status: 'drift',
         changedFiles: changed,
         missingExports: missingExportNames(fetched.dir, workspaceDir),
+        inventorySource,
       });
     }
   }