@dzhechkov/harness-core 0.7.12 → 0.8.2

package/src/book-kb.ts

@@ -16,6 +16,8 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 
+import { describeNativeDep, exerciseSqliteOpen, probeNativeDep } from './native-dep-probe.js';
+
 /** A digitized Knowledge Unit as stored in the book KB. */
 export interface BookKU {
   readonly book: string;            // ISBN or book slug (the immutable upstream key)
@@ -64,6 +66,11 @@ const SCHEMA = `CREATE VIRTUAL TABLE IF NOT EXISTS book_knowledge USING fts5(
 );`;
 
 async function openDb(projectRoot: string, dbPath?: string): Promise<NativeDb | { error: string }> {
+  const verdict = probeNativeDep(projectRoot, 'better-sqlite3', exerciseSqliteOpen, 'sqlite-open');
+  if (verdict.state === 'absent') {
+    return { error: 'better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
+  }
+  if (verdict.state === 'unusable') return { error: describeNativeDep(verdict) };
   let sqliteUrl: string;
   try {
     const req = createRequire(join(projectRoot, 'package.json'));
@@ -71,6 +78,16 @@ async function openDb(projectRoot: string, dbPath?: string): Promise<NativeDb |
   } catch {
     return { error: 'better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
   }
+  // The probe above absorbs the DEPENDENCY failures — absent, or present-but-unloadable — which is
+  // what cross-family review (F2) required: those are instrument failures and must be RETURNED.
+  //
+  // What follows must still THROW, and that is deliberate. `dz recall --books` distinguishes two
+  // states by throw-vs-return, and collapsing them loses a shipped honesty contract (measured
+  // 2026-08-27, `books-recall-honesty.test.ts`):
+  //   throws   -> the STORE ITSELF is unreadable  -> exit 1, naming the path and a cure
+  //   {error}  -> the INSTRUMENT did not run      -> exit 3 under --semantic, never a clean 0-hit
+  // A corrupted `books.sqlite` is the first state. Wrapping it into `{error}` made a corrupt store
+  // read as a missing instrument and exit 0 — a false clean pass over unreadable data.
   const path = dbPath ?? bookKbPath(projectRoot);
   mkdirSync(dirname(path), { recursive: true });
   const { default: Database } = (await import(sqliteUrl)) as { default: new (p: string) => NativeDb };

package/src/feature-adr-checkpoints.ts

@@ -497,6 +497,113 @@ export const TRAINPAIR_PRIVACY_NOTE =
 /** Coerce a stage input/output to text: strings pass through; objects serialize to JSON;
  * an unserializable value degrades to String(v) — buildTrainingPair NEVER throws (capture
  * is non-blocking by contract). */
+/** Marker pair of the operator-profile block (feature operator-profile, ADR-001 Decision 5).
+ * DELIBERATE LOCAL COPIES of profile.ts's PROFILE_MARKER_START/END: this module stays import-free
+ * so the workflow can mirror it inline. `test/profile-redaction.test.ts` pins the pairs equal. */
+export const TP_PROFILE_MARKER_START = '<!-- dz:profile:start -->';
+export const TP_PROFILE_MARKER_END = '<!-- dz:profile:end -->';
+
+/** What a redacted block is replaced with — visible in the dataset, so a missing profile is
+ * distinguishable from a never-present one. */
+export const TP_PROFILE_REDACTED = '[dz:profile REDACTED]';
+
+/**
+ * Strip every operator-profile block from `text` BEFORE a training pair is persisted.
+ *
+ * Why here and not "the guard already says never write the profile into a project": training-pair
+ * capture records the FULL prompt as the model received it into `.dz/fa-training/`, which is
+ * deliberately NOT gitignored — so a profile injected into context would reach a committable
+ * directory, and the never-in-a-project guard would be defeated through this path (ADR-001
+ * Decision 5, exit 3). Redaction at the single assembly seam closes it for capture AND backfill.
+ *
+ * Semantics: every complete `start…end` span is replaced (markers included) with
+ * {@link TP_PROFILE_REDACTED}. A START marker with no matching END fails CLOSED — everything from
+ * the marker to the end of the text is dropped (over-redaction is a lost training sample;
+ * under-redaction is a personal-data leak). Text without markers passes through byte-identical.
+ * Works on JSON-stringified payloads too: the marker literals contain no characters JSON escapes.
+ */
+export function redactProfileBlock(text: string): string {
+  if (typeof text !== 'string' || text === '') return typeof text === 'string' ? text : '';
+  let out = '';
+  let rest = text;
+  for (;;) {
+    const start = rest.indexOf(TP_PROFILE_MARKER_START);
+    if (start === -1) return out + rest;
+    out += rest.slice(0, start) + TP_PROFILE_REDACTED;
+    const end = rest.indexOf(TP_PROFILE_MARKER_END, start + TP_PROFILE_MARKER_START.length);
+    if (end === -1) return out; // unterminated block: fail closed, drop the tail
+    rest = rest.slice(end + TP_PROFILE_MARKER_END.length);
+  }
+}
+
+/**
+ * Deep redaction over an already-PARSED training-pair payload — the PERSIST-SIDE half of CF-6.
+ *
+ * Why a second entry point next to {@link redactProfileBlock}: the DEFAULT-ON capture in the
+ * canonical workflow builds its pair with an INLINE mirror of buildTrainingPair and hands the
+ * serialised JSON to `dz feature-adr-record` — a path that never passes through the core builder.
+ * Redacting at the builder alone therefore guarded the path that does NOT run (Codex cross-family
+ * finding, 2026-08-28: guard 1 defeated through guard 3, one seam further down — the exact shape
+ * ADR-001 Decision 5 names). This function runs inside `decideRecordWrite` (run-records.ts), the
+ * one decision every witnessed training-pair write funnels through, so a FUTURE pair builder is
+ * covered without patching its caller.
+ *
+ * Semantics: every string leaf (keys included) goes through {@link redactProfileBlock} — same
+ * fail-closed rule on an unterminated block; arrays and plain objects are walked; numbers,
+ * booleans and null pass through untouched. A payload with no markers anywhere round-trips to a
+ * deep-equal value.
+ *
+ * Two mechanics, both cross-family findings (2026-08-28), both load-bearing:
+ *
+ * - Rebuilt objects have a NULL prototype, so every JSON key — `__proto__` included — lands as an
+ *   OWN property. The previous `{}` + assignment invoked the inherited `__proto__` SETTER for a
+ *   payload like `{"slug":"s","stage":"code","__proto__":{"input":"i","output":"o"}}`: the result
+ *   then INHERITED input/output (the shape check passed) while serialization dropped them — an
+ *   invalid pair reported `written`. With own-key reconstruction the JSON keys round-trip exactly
+ *   and that payload fails the shape check honestly.
+ * - The walk is ITERATIVE (explicit stack), not recursive: ~5000 nested arrays is a ~10 KB payload
+ *   that passes JSON.parse and sits under the line cap, but a recursive map hit RangeError before
+ *   any size guard — a throw escaping a seam whose callers promise non-blocking verdicts. The
+ *   iterative walk chose over a caught-RangeError→`refused` wrapper because it keeps the honest
+ *   outcome for deep-but-valid payloads (they get redacted and judged on their merits) instead of
+ *   refusing them at an arbitrary engine-dependent depth. A repeated container is walked once and
+ *   reused (WeakMap), so a shared or cyclic reference can never loop the walk either.
+ */
+export function redactTrainingPayload(v: unknown): unknown {
+  if (typeof v === 'string') return redactProfileBlock(v);
+  if (v === null || typeof v !== 'object') return v;
+  const makeDst = (src: object): Record<string, unknown> | unknown[] =>
+    Array.isArray(src) ? new Array(src.length) : (Object.create(null) as Record<string, unknown>);
+  const dstOf = new WeakMap<object, Record<string, unknown> | unknown[]>();
+  const root = makeDst(v);
+  dstOf.set(v, root);
+  const stack: object[] = [v];
+  const walkChild = (child: unknown): unknown => {
+    if (typeof child === 'string') return redactProfileBlock(child);
+    if (child === null || typeof child !== 'object') return child;
+    let dst = dstOf.get(child);
+    if (dst === undefined) {
+      dst = makeDst(child);
+      dstOf.set(child, dst);
+      stack.push(child);
+    }
+    return dst;
+  };
+  while (stack.length > 0) {
+    const src = stack.pop()!;
+    const dst = dstOf.get(src)!;
+    if (Array.isArray(src)) {
+      const arr = dst as unknown[];
+      for (let i = 0; i < src.length; i++) arr[i] = walkChild(src[i]);
+    } else {
+      const obj = dst as Record<string, unknown>;
+      // null prototype ⇒ this assignment defines an OWN property even for the key '__proto__'
+      for (const [key, value] of Object.entries(src)) obj[redactProfileBlock(key)] = walkChild(value);
+    }
+  }
+  return root;
+}
+
 function coerceText(v: unknown): string {
   if (typeof v === 'string') return v;
   if (v === null || v === undefined) return '';
@@ -526,8 +633,10 @@ export function buildTrainingPair(opts: {
   captureMode?: unknown;
   resumed?: unknown;
 }): TrainingPair {
-  let input = coerceText(opts.input);
-  let output = coerceText(opts.output);
+  // Operator-profile redaction FIRST — before the oversize guard, so the truncation hashes are
+  // hashes of the redacted text and the full-text fnv1a64 never fingerprints personal data.
+  let input = redactProfileBlock(coerceText(opts.input));
+  let output = redactProfileBlock(coerceText(opts.output));
   let truncated: TrainingPairTruncation | null = null;
   if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {
     truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };

package/src/index.ts

@@ -182,7 +182,8 @@ export type {
   ReindexVectorReport,
   TeachGuardResult,
 } from './vector-tier.js';
-export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
+export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION,
+  agentdbStorePath, agentdbMcpStorePath, agentdbStoreSeparationProblem } from './setup.js';
 export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
 export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES } from './agentdb-index.js';
@@ -251,6 +252,11 @@ export {
   serializeTrainingPair,
   trainingPairPath,
   trainingPairAppendCmd,
+  // operator-profile (ADR-001 Decision 5): the profile block never reaches .dz/fa-training/.
+  redactProfileBlock,
+  TP_PROFILE_MARKER_START,
+  TP_PROFILE_MARKER_END,
+  TP_PROFILE_REDACTED,
   // wave1-instrument-repair (ADR-003 Condition 3): the persist allowlist + composite shape check.
   codeCheckpointPersistAllowed,
   codeStageResultShapeValid,
@@ -691,6 +697,12 @@ export type {
   CodexQeDeclineDetail,
   CodexReviewResult,
 } from './feature-adr-routing.js';
+export {
+  PARSER_SAFE_REGION_START,
+  PARSER_SAFE_REGION_END,
+  checkParserSafeRegion,
+} from './parser-safe-region.js';
+export type { ParserSafeRegionVerdict, ParserSafeRegionRefusal } from './parser-safe-region.js';
 export {
   CLAUDE_USAGE_MODELS,
   computeUsage,
@@ -858,3 +870,29 @@ export { quiescenceProbeScript, decideWriterQuiescence, WQ_WINDOW_SECONDS, WQ_MA
 export type { WriterQuiescenceDecision } from './writer-quiescence.js';
 export { decideCadenceWindow, isoWeekOf, weeklyBuckets, guardRepeatDecay, buildCadenceReport, CADENCE_WINDOW_DAYS } from './cadence.js';
 export type { CadenceWindow, CadenceReport, CadenceWindowDecision } from './cadence.js';
+export { readQeRounds, countQeRounds, QE_ROUNDS_DEFAULT_CEILING } from './qe-rounds.js';
+export type { QeRound, QeFailedAttempt, QeRoundsReport, QeRoundsStatus } from './qe-rounds.js';
+export { describeStoreLocation, storeLocationLine } from './store-location.js';
+export type { StoreLocation, StoreOrigin } from './store-location.js';
+export { mergeStoreHits, sameStore, globalStoreRoot, storeCountLabel } from './store-merge.js';
+export type { HitOrigin, OriginTagged } from './store-merge.js';
+export { resolveTeachTarget, teachReasonPhrase, readTeachToConfig, TeachTargetError, TEACH_STORES } from './teach-target.js';
+export type { TeachStore, TeachReason, TeachTarget } from './teach-target.js';
+export { probeNativeDep, describeNativeDep, exerciseSqliteOpen } from './native-dep-probe.js';
+export type { NativeDepState, NativeDepVerdict } from './native-dep-probe.js';
+
+// Operator profile (feature operator-profile, ADR-001) — WHO the assistant is talking to: a
+// per-user 0600 store under homedir(), rendered into a marked block in ~/.claude/CLAUDE.md
+// (layer 2 — loaded in every project, no dz required). The register changes FORM, never FACTS.
+export {
+  renderProfileBlock, readProfile, writeProfile, validateProfile,
+  profileStorePath, claudeMdPath, syncProfileBlock, checkProfileDrift,
+  mergeProfileBlock, extractProfileBlock, wrapProfileBlock,
+  parseRegister, registerOwnerWord, profileAgeDays,
+  parseDomainList, domainListText, parseYesNo,
+  PROFILE_MARKER_START, PROFILE_MARKER_END, REGISTERS,
+} from './profile.js';
+export type {
+  Register, Domain, OperatorProfile, ProfileReadResult, ProfileSyncResult,
+  ProfileDriftVerdict, ProfileDriftResult,
+} from './profile.js';

package/src/loop-blobs.generated.ts

@@ -52,11 +52,11 @@ export const BLOBS: Record<string, LoopBlob> = {
   "training-pairs": {
     name: "training-pairs",
     version: "1.1.0",
-    contentHash: "740b733d3d995e7031590f1707b442d0f0f9d7d585ada6f37bbf08c5db3351e9",
+    contentHash: "199eaaa8ce5dba4f54744b4a4f34eea32a3c33d4de8dbbddd3d119b70459361d",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-checkpoints.ts",
     requires: ["checkpoints"],
     exports: ["TRAINPAIR_SCHEMA_VERSION","TRAINPAIR_MAX_IO_CHARS","trainingPairFamily","trainingPairPath","TRAINPAIR_PRIVACY_NOTE","buildTrainingPair","serializeTrainingPair","trainingPairAppendCmd","decideCaptureMode","captureFailureRecord","trainingPairBackfillCmd","TP_BACKFILL_OK","TP_BACKFILL_SKIP"],
-    code: "function decideCaptureMode(opts) {\n    if (!opts.enabled)\n        return 'skip-disabled';\n    if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0)\n        return 'skip-empty';\n    return opts.resumed ? 'backfill' : 'capture';\n}\nfunction captureFailureRecord(stage, mode, reason, detail) {\n    const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';\n    const normalizedMode = mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'\n        ? mode\n        : null;\n    const normalizedReason = reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'\n        ? reason\n        : 'threw';\n    let normalizedDetail = null;\n    if (detail !== null && detail !== undefined) {\n        try {\n            const text = String(detail);\n            if (text !== '')\n                normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;\n        }\n        catch {\n            normalizedDetail = null;\n        }\n    }\n    return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };\n}\nconst TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = \"feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.\";\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = coerceText(opts.input);\n    let output = coerceText(opts.output);\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n        captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',\n        resumed: opts.resumed === true,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}\nconst TP_BACKFILL_OK = 'TP-BACKFILL-OK';\nconst TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';\nconst TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';\nfunction trainingPairBackfillCmd(repoAbs, slug, stage, lines, markKey) {\n    if (typeof repoAbs !== 'string' || repoAbs === '')\n        return null;\n    if (typeof slug !== 'string' || slug === '')\n        return null;\n    if (typeof stage !== 'string' || stage === '')\n        return null;\n    if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== ''))\n        return null;\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';\n    const markStage = stage.replace(/\\.\\./g, '_').replace(/\\//g, '_');\n    const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\\0' + lines.join('\\n')) : markKey;\n    const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;\n    const appends = lines\n        .map(line => \"printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs))\n        .join(' && ');\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        ' && mkdir -p ' + shellQuote(markDir) +\n        ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +\n        'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +\n        '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +\n        '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi');\n}",
+    code: "function decideCaptureMode(opts) {\n    if (!opts.enabled)\n        return 'skip-disabled';\n    if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0)\n        return 'skip-empty';\n    return opts.resumed ? 'backfill' : 'capture';\n}\nfunction captureFailureRecord(stage, mode, reason, detail) {\n    const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';\n    const normalizedMode = mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'\n        ? mode\n        : null;\n    const normalizedReason = reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'\n        ? reason\n        : 'threw';\n    let normalizedDetail = null;\n    if (detail !== null && detail !== undefined) {\n        try {\n            const text = String(detail);\n            if (text !== '')\n                normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;\n        }\n        catch {\n            normalizedDetail = null;\n        }\n    }\n    return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };\n}\nconst TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';\nconst TRAINPAIR_MAX_IO_CHARS = 48000;\nfunction trainingPairFamily(spec) {\n    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';\n}\nfunction trainingPairPath(slug, stage) {\n    return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';\n}\nconst TRAINPAIR_PRIVACY_NOTE = \"feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.\";\nconst TP_PROFILE_MARKER_START = '<!-- dz:profile:start -->';\nconst TP_PROFILE_MARKER_END = '<!-- dz:profile:end -->';\nconst TP_PROFILE_REDACTED = '[dz:profile REDACTED]';\nfunction redactProfileBlock(text) {\n    if (typeof text !== 'string' || text === '')\n        return typeof text === 'string' ? text : '';\n    let out = '';\n    let rest = text;\n    for (;;) {\n        const start = rest.indexOf(TP_PROFILE_MARKER_START);\n        if (start === -1)\n            return out + rest;\n        out += rest.slice(0, start) + TP_PROFILE_REDACTED;\n        const end = rest.indexOf(TP_PROFILE_MARKER_END, start + TP_PROFILE_MARKER_START.length);\n        if (end === -1)\n            return out;\n        rest = rest.slice(end + TP_PROFILE_MARKER_END.length);\n    }\n}\nfunction coerceText(v) {\n    if (typeof v === 'string')\n        return v;\n    if (v === null || v === undefined)\n        return '';\n    try {\n        const s = JSON.stringify(v);\n        return typeof s === 'string' ? s : String(v);\n    }\n    catch {\n        return String(v);\n    }\n}\nfunction buildTrainingPair(opts) {\n    let input = redactProfileBlock(coerceText(opts.input));\n    let output = redactProfileBlock(coerceText(opts.output));\n    let truncated = null;\n    if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {\n        truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };\n        const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);\n        let inKeep = input.length;\n        let outKeep = output.length;\n        if (outKeep <= half)\n            inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;\n        else if (inKeep <= half)\n            outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;\n        else {\n            inKeep = half;\n            outKeep = TRAINPAIR_MAX_IO_CHARS - half;\n        }\n        if (inKeep < input.length)\n            input = input.slice(0, inKeep) + '\\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';\n        if (outKeep < output.length)\n            output = output.slice(0, outKeep) + '\\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';\n    }\n    const ev = opts.evaluation || {};\n    const pv = opts.provenance || {};\n    return {\n        schema: TRAINPAIR_SCHEMA_VERSION,\n        slug: opts.slug,\n        stage: opts.stage,\n        ts: opts.ts === undefined ? null : opts.ts,\n        input,\n        output,\n        evaluation: {\n            grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,\n            gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,\n            lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s) => typeof s === 'string' && s !== '') : [],\n        },\n        provenance: {\n            model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',\n            family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),\n            role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',\n            tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,\n            minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,\n        },\n        truncated,\n        captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',\n        resumed: opts.resumed === true,\n    };\n}\nfunction serializeTrainingPair(pair) {\n    try {\n        const line = JSON.stringify(pair);\n        return typeof line === 'string' ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction trainingPairAppendCmd(repoAbs, slug, stage, line) {\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs));\n}\nconst TP_BACKFILL_OK = 'TP-BACKFILL-OK';\nconst TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';\nconst TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';\nfunction trainingPairBackfillCmd(repoAbs, slug, stage, lines, markKey) {\n    if (typeof repoAbs !== 'string' || repoAbs === '')\n        return null;\n    if (typeof slug !== 'string' || slug === '')\n        return null;\n    if (typeof stage !== 'string' || stage === '')\n        return null;\n    if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== ''))\n        return null;\n    const dirAbs = repoAbs + '/.dz/fa-training/' + slug;\n    const readmeAbs = repoAbs + '/.dz/fa-training/README.md';\n    const fileAbs = dirAbs + '/' + stage + '.jsonl';\n    const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';\n    const markStage = stage.replace(/\\.\\./g, '_').replace(/\\//g, '_');\n    const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\\0' + lines.join('\\n')) : markKey;\n    const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;\n    const appends = lines\n        .map(line => \"printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + shellQuote(fileAbs))\n        .join(' && ');\n    return ('mkdir -p ' + shellQuote(dirAbs) +\n        ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \\'%s\\\\n\\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +\n        ' && mkdir -p ' + shellQuote(markDir) +\n        ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +\n        'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +\n        '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +\n        '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi');\n}",
   },
   "model-resolver": {
     name: "model-resolver",

package/src/mutation-gate.ts

@@ -45,12 +45,15 @@ export interface MutationRegistryEntry {
 export interface MutationRegistry {
   /** optional suite command override for the whole registry (default `npm test`). */
   readonly testCommand?: string;
+  /** opt-in proof that the suite harness reached its clean completion path. */
+  readonly requireCompletionReceipt?: boolean;
   readonly entries: readonly MutationRegistryEntry[];
 }
 
 export type MutationVerdict =
   | 'PROVEN' // mutation applied, suite went red, failing count (when known) >= minFailing
   | 'UNDEFENDED' // mutation applied, suite stayed GREEN — the property has no discriminating test
+  | 'RECEIPT_MISMATCH' // the suite harness declared a receipt error, or an opted-in completion receipt was absent — neither the exit code nor failing count may be read as discrimination
   | 'NOT_APPLIED' // `find` occurred 0 or >1 times — code drifted; nothing was tested (rule 1)
   | 'BELOW_MIN' // suite red, but a RELIABLE count came in under the entry's own minFailing contract
   | 'MUTATION_UNPARSEABLE' // the MUTATED file no longer parses — a registry/setup error: whole-suite redness from a load failure proves nothing (route a)
@@ -89,12 +92,22 @@ export interface MutationObservation {
    * failure), NEVER PROVEN: redness that cannot be attributed proves nothing.
    */
   readonly outputUnrecognised?: string;
+  /**
+   * set to the marker text when the suite harness declares its own execution-receipt contract
+   * violated, or to the missing-receipt detail for an opted-in registry. Either condition
+   * invalidates both green and count-based readings of the same run.
+   */
+  readonly receiptMismatch?: string;
+  /** named reason from spawnSync when no exit code exists (timeout, signal, maxBuffer, spawn). */
+  readonly runFailureReason?: string;
   /**
    * exit code of the suite re-run on the RESTORED tree after this entry (the attribution check
    * for flaky neighbours). undefined = not run; 0 = reproducibly green; any other value (or null)
    * = the "green" baseline is not reproducible, so the red under mutation is not attributable.
    */
   readonly rebaselineExitCode?: number | null;
+  /** named no-exit reason for the restored-tree attribution run, when it produced none. */
+  readonly rebaselineFailureReason?: string;
 }
 
 export interface MutationEntryResult {
@@ -135,7 +148,7 @@ export interface ParsedRegistry {
   readonly errors: readonly string[];
 }
 
-/** Parse + validate a registry JSON text. Accepts a bare array of entries or `{testCommand, entries}`. */
+/** Parse + validate a registry JSON text. Accepts a bare array or `{testCommand?, requireCompletionReceipt?, entries}`. */
 export function parseMutationRegistry(text: string): ParsedRegistry {
   let raw: unknown;
   try {
@@ -146,10 +159,11 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
 
   let entriesRaw: unknown;
   let testCommand: string | undefined;
+  let requireCompletionReceipt: boolean | undefined;
   if (Array.isArray(raw)) {
     entriesRaw = raw;
   } else if (raw && typeof raw === 'object') {
-    const obj = raw as { testCommand?: unknown; entries?: unknown };
+    const obj = raw as { testCommand?: unknown; requireCompletionReceipt?: unknown; entries?: unknown };
     entriesRaw = obj.entries;
     if (obj.testCommand !== undefined) {
       if (typeof obj.testCommand !== 'string' || obj.testCommand.trim() === '') {
@@ -157,9 +171,15 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
       }
       testCommand = obj.testCommand.trim();
     }
+    if (obj.requireCompletionReceipt !== undefined) {
+      if (typeof obj.requireCompletionReceipt !== 'boolean') {
+        return { registry: null, errors: ['requireCompletionReceipt must be a boolean when present'] };
+      }
+      requireCompletionReceipt = obj.requireCompletionReceipt;
+    }
   }
   if (!Array.isArray(entriesRaw)) {
-    return { registry: null, errors: ['registry must be an array of entries or {testCommand?, entries: [...]}'] };
+    return { registry: null, errors: ['registry must be an array of entries or {testCommand?, requireCompletionReceipt?, entries: [...]}'] };
   }
   if (entriesRaw.length === 0) {
     // An empty registry "passes" by testing nothing — the same silent hole as a skipped mutation.
@@ -237,9 +257,14 @@ export function parseMutationRegistry(text: string): ParsedRegistry {
   });
 
   if (errors.length > 0) return { registry: null, errors };
-  return testCommand !== undefined
-    ? { registry: { testCommand, entries }, errors: [] }
-    : { registry: { entries }, errors: [] };
+  return {
+    registry: {
+      ...(testCommand !== undefined ? { testCommand } : {}),
+      ...(requireCompletionReceipt !== undefined ? { requireCompletionReceipt } : {}),
+      entries,
+    },
+    errors: [],
+  };
 }
 
 // ── Mutation application — exact text surgery, exactly once (rule 1) ──────────────────────────
@@ -315,6 +340,21 @@ function stripSgr(s: string): string {
   return s.replace(SGR, '');
 }
 
+/** Return the first suite-harness receipt error at column 0, with SGR removed. */
+export function detectSuiteReceiptMismatch(rawOutput: string): string | undefined {
+  const match = /^mutation-suite-receipt-error:[^\S\r\n]*(.*)$/m.exec(stripSgr(rawOutput));
+  return match === null ? undefined : (match[1] ?? '').trim();
+}
+
+/** Return the first suite-harness clean-completion receipt at column 0, with SGR removed. */
+export function detectSuiteCompletionReceipt(rawOutput: string): { lanes: number; names: number } | undefined {
+  const match = /^mutation-suite-receipt-ok:[^\S\r\n]*lanes=(\d+)[^\S\r\n]+names=(\d+)[^\S\r\n]*$/m.exec(stripSgr(rawOutput));
+  if (match === null) return undefined;
+  const lanes = Number(match[1]);
+  const names = Number(match[2]);
+  return Number.isSafeInteger(lanes) && Number.isSafeInteger(names) ? { lanes, names } : undefined;
+}
+
 export type RunnerKind = 'node-test' | 'vitest' | 'unknown';
 
 /**
@@ -464,10 +504,10 @@ export interface BaselineResult {
  * A RED baseline in the scratch copy is a SETUP error, never a mutation result: every subsequent
  * "red under mutation" would be noise, and every "green" a lie about an unrunnable copy.
  */
-export function classifyBaseline(exitCode: number | null): BaselineResult {
+export function classifyBaseline(exitCode: number | null, runFailureReason?: string): BaselineResult {
   if (exitCode === 0) return { ok: true, detail: 'baseline suite green in the scratch copy' };
   if (exitCode === null) {
-    return { ok: false, detail: 'baseline suite produced no exit code (timeout/spawn failure) — the copy is not runnable; fix the copy, do not read this as a mutation result' };
+    return { ok: false, detail: `baseline suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; fix the copy, do not read this as a mutation result` };
   }
   return { ok: false, detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — a broken copy cannot prove anything; fix the copy (node_modules link? path-dependent test?) before trusting any verdict` };
 }
@@ -489,13 +529,16 @@ export function classifyBaseline(exitCode: number | null): BaselineResult {
  *                               the flaky-rebaseline check (a structurally-broken run needs no
  *                               attribution analysis);
  *   4. INCONCLUSIVE (no exit) — the run produced nothing to classify at all;
- *   5. UNDEFENDED (exit 0)    — the disjoint GREEN arm: mutually exclusive with every red-based
+ *   5. RECEIPT_MISMATCH       — the harness declared its own receipt contract broken, which
+ *                               invalidates BOTH the green reading and every count-based reading
+ *                               of the same run;
+ *   6. UNDEFENDED (exit 0)    — the disjoint GREEN arm: mutually exclusive with every red-based
  *                               verdict below;
- *   6. INCONCLUSIVE (unrecognised output) — red, but the shape is unreadable: counts parsed out of
+ *   7. INCONCLUSIVE (unrecognised output) — red, but the shape is unreadable: counts parsed out of
  *                               unrecognised output must not reach BELOW_MIN/OVER_FAILING/PROVEN;
- *   7. INCONCLUSIVE (flaky rebaseline)    — red, readable, but not attributable;
- *   8. BELOW_MIN → 9. OVER_FAILING        — reliable-count contract checks, both failing;
- *  10. PROVEN                 — applied, red, behavioural, attributable, within bounds.
+ *   8. INCONCLUSIVE (flaky rebaseline)    — red, readable, but not attributable;
+ *   9. BELOW_MIN → 10. OVER_FAILING       — reliable-count contract checks, both failing;
+ *  11. PROVEN                 — applied, red, behavioural, attributable, within bounds.
  *
  * THE DROP DECISION (SPEC §Reporting, decided here + justified): `failing < observed` but still
  * `>= minFailing` is a LOUD WARNING, not a failure. Two reasons, both load-bearing:
@@ -568,7 +611,18 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
       applied: true,
       verdict: 'INCONCLUSIVE',
       drop: false,
-      detail: 'suite produced NO exit code under the mutation (timeout / spawn failure) — inconclusive is a FAILURE, never a pass',
+      detail: `suite produced NO exit code under the mutation (${obs.runFailureReason ?? 'unknown timeout / spawn failure'}) — inconclusive is a FAILURE, never a pass`,
+    };
+  }
+
+  if (obs.receiptMismatch !== undefined) {
+    const boundedReceipt = Array.from(obs.receiptMismatch).slice(0, 220).join('');
+    return {
+      ...base,
+      applied: true,
+      verdict: 'RECEIPT_MISMATCH',
+      drop: false,
+      detail: `the suite harness declared its own receipt contract violated (${boundedReceipt}) — neither this run's exit code nor its failing count may be read as discrimination; RECEIPT_MISMATCH is a FAILURE, never PROVEN`,
     };
   }
 
@@ -604,7 +658,7 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
       applied: true,
       verdict: 'INCONCLUSIVE',
       drop: false,
-      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? 'no exit code' : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
+      detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
     };
   }
 
@@ -645,7 +699,7 @@ export function classifyMutationOutcome(obs: MutationObservation): MutationEntry
 }
 
 /** Verdicts that fail the gate. INCONCLUSIVE and NOT_APPLIED fail (inconclusive ≠ pass). */
-const FAILING_VERDICTS: ReadonlySet<MutationVerdict> = new Set(['UNDEFENDED', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
+const FAILING_VERDICTS: ReadonlySet<MutationVerdict> = new Set(['UNDEFENDED', 'RECEIPT_MISMATCH', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
 
 /** Exit contract: 0 all proven · 1 any entry failed (or red baseline) · (2 = usage/setup, CLI-side). */
 export function mutationGateExitCode(results: readonly MutationEntryResult[], baselineOk: boolean): number {
@@ -660,6 +714,7 @@ export interface MutationGateSummary {
   readonly total: number;
   readonly proven: number;
   readonly undefended: number;
+  readonly receiptMismatch: number;
   readonly notApplied: number;
   readonly belowMin: number;
   readonly unparseable: number;
@@ -678,6 +733,7 @@ export function summarizeMutationResults(results: readonly MutationEntryResult[]
     total: results.length,
     proven: results.filter((r) => r.verdict === 'PROVEN').length,
     undefended: results.filter((r) => r.verdict === 'UNDEFENDED').length,
+    receiptMismatch: results.filter((r) => r.verdict === 'RECEIPT_MISMATCH').length,
     notApplied: results.filter((r) => r.verdict === 'NOT_APPLIED').length,
     belowMin: results.filter((r) => r.verdict === 'BELOW_MIN').length,
     unparseable: results.filter((r) => r.verdict === 'MUTATION_UNPARSEABLE').length,
@@ -692,6 +748,7 @@ export function summarizeMutationResults(results: readonly MutationEntryResult[]
 const VERDICT_MARK: Record<MutationVerdict, string> = {
   PROVEN: '✓',
   UNDEFENDED: '✗',
+  RECEIPT_MISMATCH: '✗',
   NOT_APPLIED: '✗',
   BELOW_MIN: '✗',
   MUTATION_UNPARSEABLE: '✗',
@@ -715,7 +772,7 @@ export function renderMutationReport(
     if (r.verdict !== 'PROVEN' || r.drop) lines.push(`      ${r.detail}`);
   }
   const s = summarizeMutationResults(results);
-  lines.push(`  summary: ${s.proven}/${s.total} proven · ${s.undefended} undefended · ${s.notApplied} not-applied · ${s.belowMin} below-min · ${s.unparseable} unparseable · ${s.loadFatal} load-fatal · ${s.overFailing} over-failing · ${s.inconclusive} inconclusive · ${s.drops} coverage drop(s) among ${s.dropComparable}/${s.total} observed-anchored entries (a drop is undetectable without an \`observed\` anchor)`);
+  lines.push(`  summary: ${s.proven}/${s.total} proven · ${s.undefended} undefended · ${s.receiptMismatch} receipt-mismatch · ${s.notApplied} not-applied · ${s.belowMin} below-min · ${s.unparseable} unparseable · ${s.loadFatal} load-fatal · ${s.overFailing} over-failing · ${s.inconclusive} inconclusive · ${s.drops} coverage drop(s) among ${s.dropComparable}/${s.total} observed-anchored entries (a drop is undetectable without an \`observed\` anchor)`);
   lines.push(mutationGateExitCode(results, baseline.ok) === 0
     ? '  verdict: PASS — every named protection has a test that goes red when the protection is deleted'
     : '  verdict: FAIL — at least one named protection is undefended, unmutable, or unproven');

package/src/named-lock.ts

@@ -33,7 +33,7 @@ import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
 import { lockSync } from 'proper-lockfile';
 
-import { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from './store-lock.js';
+import { LOCK_TIMEOUT_MS, resolveStaleMs } from './store-lock.js';
 import type { StoreLockOptions } from './store-lock.js';
 
 /** `proper-lockfile` silently clamps `stale` up to this minimum. */
@@ -99,7 +99,7 @@ const sleepSync = (ms: number): void => {
 
 function resolveOpts(opts: StoreLockOptions): { staleMs: number; timeoutMs: number; pollMs: number } {
   return {
-    staleMs: Math.max(opts.staleMs ?? STALE_LOCK_MS, MIN_STALE_MS),
+    staleMs: Math.max(opts.staleMs ?? resolveStaleMs(), MIN_STALE_MS),
     timeoutMs: opts.timeoutMs ?? defaultTimeoutMs(),
     pollMs: opts.pollMs ?? 25,
   };
@@ -206,12 +206,14 @@ function tryAcquire(
           // NEVER remove a lock directory we cannot prove is ours — including at process exit.
           return disarmExitRemoval(resourceKey) ? 'stolen' : 'stolen-undisarmed';
         }
-        try {
-          release();
-        } catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
+        // Load-bearing order: remove our marker while the directory still excludes waiters. If we
+        // unlock first, a successor can acquire and publish its marker before our cleanup runs.
         try {
           rmSync(ownerMarkerPath(lockPath), { force: true });
         } catch { /* best effort: a stale marker is overwritten by the next holder anyway */ }
+        try {
+          release();
+        } catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
         return 'released';
       },
     };
@@ -257,9 +259,9 @@ export function withNamedLockSync<T>(
           lockPath,
           compromised ??
             new Error(
-              'the lock directory no longer carries this holder\u2019s ownership token — a waiter broke it as stale ' +
-              'while the critical section was still running (a synchronous body cannot heartbeat). The successor\u2019s ' +
-              'lock was left untouched; THIS run must be treated as having raced and retried.' +
+              'the lock directory no longer carries this holder\u2019s ownership token; a waiter may have broken it ' +
+              'as stale, or another holder\u2019s release may have removed it. The current holder left the observed ' +
+              'lock untouched; THIS run must be treated as having raced and retried.' +
               (outcome === 'stolen-undisarmed'
                 ? ' WARNING: proper-lockfile\u2019s exit-time lock removal could NOT be disarmed (its getLocks() accessor ' +
                   'is unavailable in this version), so this process may still remove the successor\u2019s lock when it exits.'