@remnic/core 9.7.15 → 9.9.0

package/dist/{chunk-TXLGHDHS.js → chunk-W4XJFLAL.js}

@@ -1,13 +1,13 @@
 import {
   isTemporalQuery,
   recencyWindowBoundsFromPrompt
-} from "./chunk-2VN4JAX7.js";
-import {
-  log
-} from "./chunk-37CTGERM.js";
+} from "./chunk-ZOKZIR5K.js";
 import {
   isAbortError
 } from "./chunk-PVGDJXVK.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
 
 // src/retrieval-agents.ts
 import path from "path";
@@ -56,7 +56,11 @@ async function resolveContainedRegularFile(memoryDir, candidatePath, canonicalRo
     return null;
   }
 }
-async function runDirectAgent(query, memoryDir, maxResults = 10) {
+function namespaceRelativeResult(result, _memoryDir, namespaceFromPath) {
+  if (!namespaceFromPath || !result.path || result.namespace) return result;
+  return { ...result, namespace: namespaceFromPath(result.path) };
+}
+async function runDirectAgent(query, memoryDir, maxResults = 10, namespaceFromPath) {
   try {
     const canonicalRoot = await realpath(memoryDir);
     const entitiesDir = path.join(memoryDir, "entities");
@@ -78,15 +82,21 @@ async function runDirectAgent(query, memoryDir, maxResults = 10) {
       const fullPath = path.join(entitiesDir, entry);
       const safePath = await resolveContainedRegularFile(memoryDir, fullPath, canonicalRoot);
       if (!safePath) continue;
-      results.push({
-        docid: nameWithoutExt,
-        path: safePath,
-        snippet: "",
-        // populated by augmentWithDirectAndTemporal after merge
-        score,
-        transport: "scoped_prefilter",
-        agentSource: "direct"
-      });
+      results.push(
+        namespaceRelativeResult(
+          {
+            docid: nameWithoutExt,
+            path: safePath,
+            snippet: "",
+            // populated by augmentWithDirectAndTemporal after merge
+            score,
+            transport: "scoped_prefilter",
+            agentSource: "direct"
+          },
+          memoryDir,
+          namespaceFromPath
+        )
+      );
     }
     return results.sort((a, b) => b.score - a.score).slice(0, maxResults);
   } catch (err) {
@@ -94,7 +104,7 @@ async function runDirectAgent(query, memoryDir, maxResults = 10) {
     return [];
   }
 }
-async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePaths) {
+async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePaths, namespaceFromPath) {
   try {
     const canonicalRoot = await realpath(memoryDir);
     let dateIndex = {};
@@ -231,15 +241,21 @@ async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePath
       }
       const score = recencyScore * (1 + topicBoost * 0.3);
       const baseName = path.basename(safePath, ".md");
-      results.push({
-        docid: baseName,
-        path: safePath,
-        snippet: "",
-        // populated by augmentWithDirectAndTemporal after merge
-        score,
-        transport: "scoped_prefilter",
-        agentSource: "temporal"
-      });
+      results.push(
+        namespaceRelativeResult(
+          {
+            docid: baseName,
+            path: safePath,
+            snippet: "",
+            // populated by augmentWithDirectAndTemporal after merge
+            score,
+            transport: "scoped_prefilter",
+            agentSource: "temporal"
+          },
+          memoryDir,
+          namespaceFromPath
+        )
+      );
     }
     return results.sort((a, b) => b.score - a.score).slice(0, maxResults);
   } catch (err) {
@@ -262,16 +278,18 @@ async function runContextualAgent(query, qmd, collection, maxResults, signal) {
     return [];
   }
 }
-function mergeAgentResults(allResults, weights, maxResults) {
+function mergeAgentResults(allResults, weights, maxResults, resolveNamespace) {
   const merged = /* @__PURE__ */ new Map();
   for (const result of allResults) {
-    const key = result.path || result.docid;
+    const namespace = result.namespace ?? (resolveNamespace && result.path ? resolveNamespace(result.path) : void 0);
+    const key = `${namespace ?? ""}\0${result.path || result.docid}`;
     const weightedScore = result.score * weights[result.agentSource];
     const existing = merged.get(key);
     if (!existing || weightedScore > existing.score) {
       merged.set(key, {
         docid: result.docid,
         path: result.path,
+        namespace,
         // Preserve any snippet from the existing entry when the new one has none
         snippet: result.snippet || existing?.snippet || "",
         score: weightedScore,
@@ -311,7 +329,7 @@ async function populateEmptySnippets(results, memoryDir) {
   if (snippetMap.size === 0) return results;
   return results.map((r) => r.path && snippetMap.has(r.path) ? { ...r, snippet: snippetMap.get(r.path) } : r);
 }
-async function mergeWithAgentResults(contextualResults, directResults, temporalResults, weights, maxResults, memoryDir) {
+async function mergeWithAgentResults(contextualResults, directResults, temporalResults, weights, maxResults, memoryDir, resolveNamespace) {
   if (directResults.length === 0 && temporalResults.length === 0) {
     return contextualResults.slice(0, maxResults);
   }
@@ -322,11 +340,12 @@ async function mergeWithAgentResults(contextualResults, directResults, temporalR
   const merged = mergeAgentResults(
     [...contextualTagged, ...directResults, ...temporalResults],
     weights,
-    maxResults
+    maxResults,
+    resolveNamespace
   );
   return populateEmptySnippets(merged, memoryDir);
 }
-async function augmentWithDirectAndTemporal(query, memoryDir, contextualResults, weights, maxPerAgent, maxResults, candidatePaths) {
+async function augmentWithDirectAndTemporal(query, memoryDir, contextualResults, weights, maxPerAgent, maxResults, candidatePaths, resolveNamespace) {
   if (maxPerAgent === 0) return contextualResults;
   const knownEntityCount = (query.match(/\b[A-Z][a-z]{1,}/g) ?? []).length;
   const runDirect = shouldRunAgent("direct", query, knownEntityCount);
@@ -357,7 +376,8 @@ async function augmentWithDirectAndTemporal(query, memoryDir, contextualResults,
   const merged = mergeAgentResults(
     [...contextualTagged, ...scopedDirect, ...temporalResults],
     weights,
-    maxResults
+    maxResults,
+    resolveNamespace
   );
   return populateEmptySnippets(merged, memoryDir);
 }
@@ -391,7 +411,8 @@ async function parallelRetrieval(query, qmd, memoryDir, options = {}) {
   const merged = mergeAgentResults(
     [...contextualResults, ...directResults, ...temporalResults],
     options.agentWeights ?? PARALLEL_AGENT_WEIGHTS,
-    maxResults
+    maxResults,
+    options.resolveNamespace
   );
   return populateEmptySnippets(merged, memoryDir);
 }
@@ -406,4 +427,4 @@ export {
   augmentWithDirectAndTemporal,
   parallelRetrieval
 };
-//# sourceMappingURL=chunk-TXLGHDHS.js.map
+//# sourceMappingURL=chunk-W4XJFLAL.js.map

package/dist/chunk-W4XJFLAL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retrieval-agents.ts"],"sourcesContent":["/**\n * Parallel Specialized Retrieval (v9.1 — ASMR-inspired)\n *\n * Replaces single-pass hybrid search with three parallel specialized agents:\n *\n *   1. DirectFactAgent  — entity-first lookup via entity filename index (<5ms)\n *   2. ContextualAgent  — existing hybridSearch (same cost as current single-pass)\n *   3. TemporalAgent    — temporal index prefilter + recency scoring (<10ms)\n *\n * All agents run via Promise.all(), so total latency = max(agents), not sum.\n * No new LLM inference is introduced — agents reuse existing search primitives.\n *\n * Graceful degradation: any agent error/timeout does not block the others.\n *\n * References:\n *   - Supermemory ASMR: https://blog.supermemory.ai/...\n *   - Spec: docs/ideas/parallel-specialized-retrieval.md\n */\n\nimport path from \"node:path\";\nimport { lstat, readdir, readFile, realpath, stat } from \"node:fs/promises\";\nimport { log } from \"./logger.js\";\nimport type { QmdSearchResult } from \"./types.js\";\nimport type { QmdClient } from \"./qmd.js\";\nimport { isTemporalQuery, recencyWindowBoundsFromPrompt } from \"./temporal-index.js\";\nimport { isAbortError } from \"./abort-error.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport type SearchAgentSource = \"direct\" | \"contextual\" | \"temporal\";\n\nexport interface ParallelSearchResult extends QmdSearchResult {\n  /** Which retrieval agent produced this result. */\n  agentSource: SearchAgentSource;\n}\n\n/** Source-based weights applied during merge. Higher = higher confidence/precision. */\nexport const PARALLEL_AGENT_WEIGHTS: Record<SearchAgentSource, number> = {\n  direct: 1.0, // entity-first: high precision\n  temporal: 0.85, // recency-boosted: relevant but broader\n  contextual: 0.7, // semantic: broadest, lower precision\n};\n\n// ─── Query classification ────────────────────────────────────────────────────\n\n/**\n * Decide whether a given agent should run for this query.\n * Agent 1 (direct) is the only one that may be skipped — when the query\n * contains no proper-noun-like tokens, entity lookups will return nothing.\n * Agents 2 (contextual) and 3 (temporal) always run.\n */\nexport function shouldRunAgent(\n  agent: SearchAgentSource,\n  query: string,\n  knownEntityCount: number,\n): boolean {\n  switch (agent) {\n    case \"direct\":\n      // Skip only if query has no word-like tokens at all. Both capitalized and\n      // lowercase entity names are stored (normalizeEntityName lowercases them),\n      // so gating on capitalization would silently skip most real entity lookups.\n      return knownEntityCount > 0 || /\\b\\w{2,}/.test(query);\n    case \"temporal\":\n      // Only run temporal agent when the query actually asks about a time window.\n      // Running it for every query injects recency bias into semantic searches.\n      return isTemporalQuery(query);\n    case \"contextual\":\n      return true;\n    default:\n      return true;\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nfunction tokenize(value: string): string[] {\n  return value\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \" \")\n    .trim()\n    .split(/\\s+/)\n    .filter((t) => t.length >= 2);\n}\n\nfunction overlapScore(queryTokens: string[], candidateTokens: string[]): number {\n  if (queryTokens.length === 0 || candidateTokens.length === 0) return 0;\n  const candidateSet = new Set(candidateTokens);\n  const hits = queryTokens.filter((t) => candidateSet.has(t)).length;\n  return hits / Math.max(queryTokens.length, candidateTokens.length);\n}\n\nasync function resolveContainedRegularFile(\n  memoryDir: string,\n  candidatePath: string,\n  canonicalRoot?: string,\n): Promise<string | null> {\n  try {\n    const root = canonicalRoot ?? await realpath(memoryDir);\n    const absolute = path.isAbsolute(candidatePath)\n      ? path.resolve(candidatePath)\n      : path.resolve(memoryDir, candidatePath);\n    const entryStat = await lstat(absolute);\n    if (entryStat.isSymbolicLink()) return null;\n    const fileStat = await stat(absolute);\n    if (!fileStat.isFile()) return null;\n    const canonical = await realpath(absolute);\n    if (canonical !== root && !canonical.startsWith(root + path.sep)) return null;\n    return absolute;\n  } catch {\n    return null;\n  }\n}\n\n// ─── Agent 1: Direct Facts ───────────────────────────────────────────────────\n\n/**\n * Direct Facts Agent — entity-first retrieval.\n *\n * Reads entity filenames from the entities directory and scores them by\n * keyword overlap with the query. Returns matching entity file paths as\n * QmdSearchResult[]. Zero LLM inference; pure file I/O.\n *\n * Cost: readdir on entities/ + filename scoring. Typically <5ms.\n *\n */\n// Agents scan one namespace storage dir and return absolute paths. Contextual\n// fanout hits are also absolute (globally-unique identity), so we keep the\n// agent path absolute and only stamp the owning namespace here — that carries\n// the namespace through merge/tracking without re-deriving it (#2020). No-op\n// without a resolver.\nfunction namespaceRelativeResult(\n  result: ParallelSearchResult,\n  _memoryDir: string,\n  namespaceFromPath?: (p: string) => string,\n): ParallelSearchResult {\n  if (!namespaceFromPath || !result.path || result.namespace) return result;\n  return { ...result, namespace: namespaceFromPath(result.path) };\n}\n\nexport async function runDirectAgent(\n  query: string,\n  memoryDir: string,\n  maxResults = 10,\n  namespaceFromPath?: (p: string) => string,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const canonicalRoot = await realpath(memoryDir);\n    const entitiesDir = path.join(memoryDir, \"entities\");\n    let entries: string[];\n    try {\n      entries = await readdir(entitiesDir);\n    } catch {\n      return []; // entities dir missing or unreadable — not an error\n    }\n\n    const queryTokens = tokenize(query);\n    if (queryTokens.length === 0) return [];\n\n    const results: ParallelSearchResult[] = [];\n    for (const entry of entries) {\n      if (!entry.endsWith(\".md\")) continue;\n\n      // Filename tokens: split on hyphens (normalizeEntityName uses hyphens)\n      const nameWithoutExt = entry.slice(0, -3);\n      const entityTokens = nameWithoutExt.split(\"-\").filter((t) => t.length >= 2).map((t) => t.toLowerCase());\n\n      const score = overlapScore(queryTokens, entityTokens);\n      if (score <= 0) continue;\n\n      const fullPath = path.join(entitiesDir, entry);\n      const safePath = await resolveContainedRegularFile(memoryDir, fullPath, canonicalRoot);\n      if (!safePath) continue;\n\n      results.push(\n        namespaceRelativeResult(\n          {\n            docid: nameWithoutExt,\n            path: safePath,\n            snippet: \"\", // populated by augmentWithDirectAndTemporal after merge\n            score,\n            transport: \"scoped_prefilter\",\n            agentSource: \"direct\",\n          },\n          memoryDir,\n          namespaceFromPath,\n        ),\n      );\n    }\n\n    return results\n      .sort((a, b) => b.score - a.score)\n      .slice(0, maxResults);\n  } catch (err) {\n    log.debug(`DirectFactAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Agent 3: Temporal ───────────────────────────────────────────────────────\n\n/**\n * Temporal Agent — recency-focused retrieval.\n *\n * Uses the temporal index (index_time.json) to find memories from the\n * recent time window derived from the query (default: last 7 days).\n * Combines recency decay with query-filename token overlap so results stay\n * relevant to the query content, not just recency. Zero LLM inference; File I/O + math.\n *\n * Cost: read index_time.json + date range scan. Typically <10ms.\n */\nexport async function runTemporalAgent(\n  query: string,\n  memoryDir: string,\n  maxResults = 20,\n  /** Optional candidate set from query-aware prefilter. Applied BEFORE the top-K cap so\n   * in-scope entries are not displaced by newer out-of-scope entries. */\n  candidatePaths?: Set<string> | null,\n  namespaceFromPath?: (p: string) => string,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const canonicalRoot = await realpath(memoryDir);\n    // Read index_time.json once — used for both date-range filtering and recency scoring.\n    let dateIndex: Record<string, string[]> = {};\n    try {\n      const indexPath = path.join(memoryDir, \"state\", \"index_time.json\");\n      const raw = await readFile(indexPath, \"utf-8\");\n      const parsed = JSON.parse(raw) as { dates?: Record<string, string[]> };\n      dateIndex = parsed.dates ?? {};\n    } catch {\n      return []; // Index missing or unreadable — nothing to return\n    }\n\n    // Derive both window edges from the same function so fromDate/toDate always use\n    // consistent pattern-matching and priority ordering.\n    const { fromDate, toDate } = recencyWindowBoundsFromPrompt(query);\n\n    // Build path → date map, filtering to the recency window in one pass.\n    // Apply candidatePaths here (before scoring + top-K) so in-scope entries are\n    // not displaced by newer out-of-scope entries at the slice boundary.\n    const pathToDate = new Map<string, string>();\n    for (const [date, datePaths] of Object.entries(dateIndex)) {\n      // toDate is an exclusive upper bound (the first day NOT included in the window).\n      // e.g. \"3 days ago\" → fromDate=\"2026-03-12\", toDate=\"2026-03-13\" → only includes 2026-03-12.\n      if (date >= fromDate && date < toDate) {\n        for (const p of datePaths) {\n          // Skip paths excluded by the query-aware prefilter scope\n          if (candidatePaths && !candidatePaths.has(p)) continue;\n          if (!pathToDate.has(p)) pathToDate.set(p, date);\n        }\n      }\n    }\n\n    if (pathToDate.size === 0) return [];\n\n    const todayMs = Date.now();\n\n    // Extract non-temporal topic tokens for tag-based relevance boost.\n    // Purely temporal words (dates, relative time) and common stopwords are stripped\n    // so the signal reflects the subject the user is asking about (e.g. \"auth\" in\n    // \"what changed in auth last week\"), not the time window itself.\n    const TEMPORAL_STOPWORDS = new Set([\n      \"today\", \"yesterday\", \"this\", \"last\", \"week\", \"month\", \"year\",\n      \"morning\", \"night\", \"now\", \"earlier\", \"since\", \"after\", \"before\",\n      \"ago\", \"hours\", \"days\", \"weeks\", \"months\",\n      \"january\", \"february\", \"march\", \"april\", \"may\", \"june\",\n      \"july\", \"august\", \"september\", \"october\", \"november\", \"december\",\n      \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\",\n      \"what\", \"when\", \"where\", \"who\", \"why\", \"how\", \"the\", \"a\", \"an\",\n      \"and\", \"or\", \"in\", \"on\", \"at\", \"to\", \"of\", \"for\", \"with\", \"by\",\n      \"from\", \"changed\", \"happened\", \"was\", \"were\", \"is\", \"are\", \"did\",\n      \"about\", \"that\", \"have\", \"had\", \"has\", \"been\", \"any\", \"all\",\n    ]);\n    const topicTokens = tokenize(query).filter((t) => !TEMPORAL_STOPWORDS.has(t));\n\n    // Load tag index for topical scoring, in parallel with existence checks.\n    // Fail-open: if the tag index is unavailable, topicBoost = 0 and scores\n    // degrade gracefully to recency-only ordering (existing behaviour).\n    const entries = [...pathToDate.entries()];\n    const tagIndexPromise: Promise<Map<string, string[]>> = topicTokens.length > 0\n      ? readFile(path.join(memoryDir, \"state\", \"index_tags.json\"), \"utf-8\")\n          .then((raw) => {\n            const parsed = JSON.parse(raw) as { tags?: Record<string, { paths?: string[] } | string[]> };\n            const result = new Map<string, string[]>();\n            for (const [tag, node] of Object.entries(parsed.tags ?? {})) {\n              const tagPaths = Array.isArray(node) ? node : (node.paths ?? []);\n              for (const tp of tagPaths) {\n                const existing = result.get(tp);\n                if (existing) existing.push(tag);\n                else result.set(tp, [tag]);\n              }\n            }\n            return result;\n          })\n          .catch(() => new Map<string, string[]>())\n      : Promise.resolve(new Map<string, string[]>());\n\n    // Parallel: existence checks + tag index read.\n    const [safePathResults, pathToTags] = await Promise.all([\n      Promise.all(entries.map(([p]) => resolveContainedRegularFile(memoryDir, p, canonicalRoot))),\n      tagIndexPromise,\n    ]);\n\n    const results: ParallelSearchResult[] = [];\n\n    for (let i = 0; i < entries.length; i++) {\n      const [p, dateStr] = entries[i];\n      const safePath = safePathResults[i];\n      if (!safePath) continue; // skip stale or out-of-root index entry\n      const ageMs = todayMs - new Date(dateStr).getTime();\n      const ageDays = ageMs / 86_400_000;\n      // Exponential recency decay with half-life of ~30 days.\n      // score ≈ 1.0 at day 0, ≈ 0.79 at 7 days, ≈ 0.36 at 30 days, ≈ 0.13 at 60 days.\n      const recencyScore = Math.exp(-ageDays / 30);\n\n      // Topical boost: fraction of non-temporal query tokens matched by this file's tags.\n      // Adds up to +30% on recency score for a perfect tag match; zero when query is\n      // purely temporal (no topic tokens) or the tag index doesn't cover the file.\n      let topicBoost = 0;\n      if (topicTokens.length > 0) {\n        const tags = pathToTags.get(p) ?? pathToTags.get(safePath);\n        if (tags && tags.length > 0) {\n          const tagSet = new Set(tags.flatMap((t) => tokenize(t)));\n          const hits = topicTokens.filter((t) => tagSet.has(t)).length;\n          topicBoost = hits / topicTokens.length;\n        }\n      }\n      const score = recencyScore * (1 + topicBoost * 0.3);\n\n      const baseName = path.basename(safePath, \".md\");\n\n      results.push(\n        namespaceRelativeResult(\n          {\n            docid: baseName,\n            path: safePath,\n            snippet: \"\", // populated by augmentWithDirectAndTemporal after merge\n            score,\n            transport: \"scoped_prefilter\",\n            agentSource: \"temporal\",\n          },\n          memoryDir,\n          namespaceFromPath,\n        ),\n      );\n    }\n\n    return results\n      .sort((a, b) => b.score - a.score)\n      .slice(0, maxResults);\n  } catch (err) {\n    log.debug(`TemporalAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Agent 2: Contextual ─────────────────────────────────────────────────────\n\n/**\n * Contextual Agent — broad semantic/hybrid search.\n *\n * Delegates to the existing hybridSearch (BM25 + vector). Same cost as the\n * current single-pass retrieval — this agent introduces no additional LLM calls.\n */\nexport async function runContextualAgent(\n  query: string,\n  qmd: QmdClient,\n  collection: string | undefined,\n  maxResults: number,\n  signal?: AbortSignal,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const results = await qmd.hybridSearch(\n      query,\n      collection,\n      maxResults,\n      signal ? { signal } : undefined,\n    );\n    return results.map((r: QmdSearchResult) => ({ ...r, agentSource: \"contextual\" as const }));\n  } catch (err) {\n    if (isAbortError(err)) throw err;\n    log.debug(`ContextualAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Merge helper ─────────────────────────────────────────────────────────────\n\n/**\n * Merge results from multiple agents into a single deduplicated, weighted list.\n * Deduplicates by (namespace, path). Contextual results carry a `namespace`\n * (from the namespace-fanout search); direct/temporal results do not. When a\n * `resolveNamespace` resolver is supplied, the missing namespace is derived from\n * the result path the same canonical way the contextual side derives it\n * (`result.namespace ?? resolveNamespace(result.path)`), so a direct/temporal hit\n * and a contextual hit for the same (namespace, path) collapse to ONE merge key\n * instead of being injected and access-counted twice. Preserves snippets: if a\n * higher-scoring result lacks a snippet, the existing snippet from a lower-scoring\n * source is retained.\n */\nfunction mergeAgentResults(\n  allResults: ParallelSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxResults: number,\n  resolveNamespace?: (path: string) => string,\n): QmdSearchResult[] {\n  const merged = new Map<string, QmdSearchResult>();\n  for (const result of allResults) {\n    const namespace =\n      result.namespace ?? (resolveNamespace && result.path ? resolveNamespace(result.path) : undefined);\n    const key = `${namespace ?? \"\"}\\0${result.path || result.docid}`;\n    const weightedScore = result.score * weights[result.agentSource];\n    const existing = merged.get(key);\n    if (!existing || weightedScore > existing.score) {\n      merged.set(key, {\n        docid: result.docid,\n        path: result.path,\n        namespace,\n        // Preserve any snippet from the existing entry when the new one has none\n        snippet: result.snippet || existing?.snippet || \"\",\n        score: weightedScore,\n        transport: \"hybrid\",\n      });\n    }\n  }\n  return [...merged.values()]\n    .sort((a, b) => b.score - a.score)\n    .slice(0, maxResults);\n}\n\n/**\n * For merged results that have an empty snippet, attempt to read the first\n * 200 characters of the file as a fallback preview. Bounded to MAX_SNIPPET_READS\n * to cap I/O when many specialized-agent results are present.\n */\nconst SNIPPET_PREVIEW_CHARS = 200;\nconst MAX_SNIPPET_READS = 8;\n\n/** Strip YAML frontmatter (---...---) and return the document body. */\nfunction stripFrontmatter(raw: string): string {\n  if (!raw.startsWith(\"---\")) return raw;\n  const end = raw.indexOf(\"\\n---\", 3);\n  if (end === -1) return raw;\n  // Skip the closing \"---\" line and any leading blank lines\n  return raw.slice(end + 4).replace(/^\\n+/, \"\");\n}\n\nasync function populateEmptySnippets(results: QmdSearchResult[], memoryDir?: string): Promise<QmdSearchResult[]> {\n  const needsSnippet = results.filter((r) => !r.snippet && r.path);\n  if (needsSnippet.length === 0) return results;\n  const canonicalRoot = memoryDir ? await realpath(memoryDir).catch(() => null) : null;\n\n  const toRead = needsSnippet.slice(0, MAX_SNIPPET_READS);\n  const snippetMap = new Map<string, string>();\n\n  await Promise.all(\n    toRead.map(async (r) => {\n      try {\n        const safePath = canonicalRoot && r.path\n          ? await resolveContainedRegularFile(memoryDir!, r.path, canonicalRoot)\n          : null;\n        if (!safePath) return;\n        const raw = await readFile(safePath, \"utf-8\");\n        // Memory files start with YAML frontmatter — skip it so the snippet\n        // contains actual memory content, not metadata fields.\n        const body = stripFrontmatter(raw);\n        const preview = body.slice(0, SNIPPET_PREVIEW_CHARS).replace(/\\s+/g, \" \").trim();\n        if (preview) snippetMap.set(r.path, preview);\n      } catch {\n        // File unreadable — leave snippet empty\n      }\n    }),\n  );\n\n  if (snippetMap.size === 0) return results;\n  return results.map((r) => (r.path && snippetMap.has(r.path) ? { ...r, snippet: snippetMap.get(r.path)! } : r));\n}\n\n/**\n * Merge pre-computed direct and temporal agent results with contextual results.\n *\n * This is the merge half of augmentWithDirectAndTemporal. Expose it separately so\n * callers that started agents concurrently with the contextual search (for true\n * parallel latency) can merge after all three complete, without re-running agents.\n *\n * Handles the same cases as augmentWithDirectAndTemporal:\n * - Returns contextual unchanged (no reweighting) when both agents return nothing\n * - Applies maxResults cap in all paths\n * - Populates snippets for results discovered only by specialized agents\n */\nexport async function mergeWithAgentResults(\n  contextualResults: QmdSearchResult[],\n  directResults: ParallelSearchResult[],\n  temporalResults: ParallelSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxResults: number,\n  memoryDir?: string,\n  /** Optional namespace resolver. Direct/temporal results lack a namespace under\n   * namespace fanout; deriving it from the path lets them collapse onto the same\n   * merge key as the contextual result for the same (namespace, path). */\n  resolveNamespace?: (path: string) => string,\n): Promise<QmdSearchResult[]> {\n  if (directResults.length === 0 && temporalResults.length === 0) {\n    return contextualResults.slice(0, maxResults);\n  }\n\n  const contextualTagged: ParallelSearchResult[] = contextualResults.map((r) => ({\n    ...r,\n    agentSource: \"contextual\" as const,\n  }));\n\n  const merged = mergeAgentResults(\n    [...contextualTagged, ...directResults, ...temporalResults],\n    weights,\n    maxResults,\n    resolveNamespace,\n  );\n  return populateEmptySnippets(merged, memoryDir);\n}\n\n// ─── Augmentation helper (used by tests; orchestrator uses inline logic) ─────\n//\n// NOTE: This function passes the same `memoryDir` to both direct and temporal\n// agents. The orchestrator's inline implementation differs: it passes a\n// namespace-specific storage dir to runDirectAgent and the shared root to\n// runTemporalAgent. augmentWithDirectAndTemporal is intentionally simpler\n// (single-dir assumption) and is exercised by unit tests where both agents\n// operate on the same temporary directory.\n\n/**\n * Augment a set of contextual (hybridSearch) results with direct and temporal\n * agent results, returning a merged, deduplicated list.\n *\n * **Test helper** — production recall uses the inline orchestrator path which\n * passes namespace-specific directories to each agent. This function uses a\n * simplified single-directory contract suitable for unit tests.\n *\n * Direct and temporal agents run in parallel, then all three are merged with\n * configurable weights.\n *\n * Contextual weight is always applied to `contextualResults` so scoring is\n * consistent regardless of whether direct/temporal agents return anything.\n *\n * Snippets: snippets from contextual results are preserved during merge. For\n * results discovered only by direct/temporal agents (no contextual match),\n * the first ~200 chars of the file are read as a fallback preview so downstream\n * formatters and rerankers have content to work with, not just a path.\n */\nexport async function augmentWithDirectAndTemporal(\n  query: string,\n  memoryDir: string,\n  contextualResults: QmdSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxPerAgent: number,\n  maxResults: number,\n  /** Optional candidate set from query-aware prefilter (time/tag scoped). Agents' results are\n   * filtered to this set when provided so recall stays within the operator-specified scope. */\n  candidatePaths?: Set<string> | null,\n  /** Optional namespace resolver so direct/temporal results collapse onto the same\n   * (namespace, path) merge key as their contextual counterpart. */\n  resolveNamespace?: (path: string) => string,\n): Promise<QmdSearchResult[]> {\n  // maxPerAgent=0 is a hard disable: skip agents entirely and return contextual unchanged\n  if (maxPerAgent === 0) return contextualResults;\n\n  const knownEntityCount = (query.match(/\\b[A-Z][a-z]{1,}/g) ?? []).length;\n  const runDirect = shouldRunAgent(\"direct\", query, knownEntityCount);\n  const runTemporal = shouldRunAgent(\"temporal\", query, knownEntityCount);\n\n  const startMs = Date.now();\n  const [directResults, temporalResults] = await Promise.all([\n    runDirect\n      ? runDirectAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`augmentWithDirectAndTemporal: DirectAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runTemporal\n      // Pass candidatePaths so scope-filtering happens before the top-K cap inside runTemporalAgent,\n      // preventing out-of-scope newer entries from displacing in-scope ones at the slice boundary.\n      ? runTemporalAgent(query, memoryDir, maxPerAgent, candidatePaths).catch((err) => {\n        log.debug(`augmentWithDirectAndTemporal: TemporalAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n  ]);\n  const durationMs = Date.now() - startMs;\n\n  // Direct agent results (entities/) intentionally bypass candidatePaths.\n  //\n  // Why: candidatePaths is built from temporal + tag indexes, which never include\n  // entity files (entities/*.md). Applying the filter here would silently drop ALL\n  // direct-agent results for any scoped query, making the direct agent a no-op.\n  // Entity files are identified by filename matching (query tokens vs. entity name),\n  // so they are already query-scoped independently of the time/tag prefilter.\n  // Temporal results are scoped inside runTemporalAgent() before the top-K cap.\n  const scopedDirect = directResults;\n\n  // Tag contextual results with their source so they can participate in weighted merge.\n  // We do NOT cap contextual here: contextualResults comes from fetchQmdMemoryResultsWithArtifactTopUp\n  // which intentionally over-fetches so downstream phases (graph expansion, lifecycle filtering,\n  // reranking) can drop candidates. Capping before the merge would remove that headroom.\n  const contextualTagged: ParallelSearchResult[] = contextualResults.map((r) => ({\n    ...r,\n    agentSource: \"contextual\" as const,\n  }));\n\n  log.debug(\n    `augmentWithDirectAndTemporal: direct=${scopedDirect.length} temporal=${temporalResults.length} contextual=${contextualTagged.length} agentMs=${durationMs}ms`,\n  );\n\n  // If no specialized agents contributed anything (e.g. fresh setup without entities/ or temporal\n  // index), skip reweighting entirely — applying the contextual weight penalty with zero benefit\n  // would silently reduce every result score by ~30% compared to the non-augmented path.\n  if (scopedDirect.length === 0 && temporalResults.length === 0) {\n    return (contextualResults as QmdSearchResult[]).slice(0, maxResults);\n  }\n\n  // Merge all three; contextual first so its snippets are preserved when a higher-scoring\n  // direct/temporal result overrides the same path (see mergeAgentResults snippet logic).\n  // Note: maxPerAgent=0 is handled by the early-return guard above; we never reach here with 0.\n  const merged = mergeAgentResults(\n    [...contextualTagged, ...scopedDirect, ...temporalResults],\n    weights,\n    maxResults,\n    resolveNamespace,\n  );\n\n  // Populate snippets for results discovered only by direct/temporal (no contextual preview)\n  return populateEmptySnippets(merged, memoryDir);\n}\n\n// ─── Orchestrator ─────────────────────────────────────────────────────────────\n\nexport interface ParallelRetrievalOptions {\n  collection?: string;\n  maxResults?: number;\n  signal?: AbortSignal;\n  /** If true, skip the contextual agent (hybridSearch is already running externally). */\n  skipContextual?: boolean;\n  /** Max results per agent (capped before merge). */\n  maxResultsPerAgent?: number;\n  /** Override default agent weights. Falls back to PARALLEL_AGENT_WEIGHTS when absent. */\n  agentWeights?: Record<SearchAgentSource, number>;\n  /** Optional namespace resolver so direct/temporal results collapse onto the same\n   * (namespace, path) merge key as the contextual result for the same path. */\n  resolveNamespace?: (path: string) => string;\n}\n\n/**\n * Run parallel specialized retrieval agents and merge results.\n *\n * When `skipContextual` is true, only the direct and temporal agents run.\n * This is the intended usage inside the orchestrator, where hybridSearch\n * already runs as the primary search — we augment with the cheap extra agents.\n *\n * Total latency = max(agent_latencies), not sum.\n * Agent errors are isolated — others still return results.\n */\nexport async function parallelRetrieval(\n  query: string,\n  qmd: QmdClient,\n  memoryDir: string,\n  options: ParallelRetrievalOptions = {},\n): Promise<QmdSearchResult[]> {\n  const maxResults = options.maxResults ?? 20;\n  const maxPerAgent = options.maxResultsPerAgent ?? maxResults;\n  const startMs = Date.now();\n\n  // Rough entity detection: count proper-noun-like tokens in query\n  const knownEntityCount = (query.match(/\\b[A-Z][a-z]{1,}/g) ?? []).length;\n\n  const runDirect = shouldRunAgent(\"direct\", query, knownEntityCount);\n  const runTemporal = shouldRunAgent(\"temporal\", query, knownEntityCount);\n  const runContextual = !options.skipContextual && shouldRunAgent(\"contextual\", query, knownEntityCount);\n\n  const [directResults, temporalResults, contextualResults] = await Promise.all([\n    runDirect\n      ? runDirectAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`parallelRetrieval: DirectAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runTemporal\n      ? runTemporalAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`parallelRetrieval: TemporalAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runContextual\n      ? runContextualAgent(query, qmd, options.collection, maxPerAgent, options.signal).catch((err) => {\n        if (isAbortError(err)) throw err;\n        log.debug(`parallelRetrieval: ContextualAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n  ]);\n\n  const durationMs = Date.now() - startMs;\n  log.debug(\n    `parallelRetrieval: direct=${directResults.length} temporal=${temporalResults.length} contextual=${contextualResults.length} durationMs=${durationMs}ms`,\n  );\n\n  // Contextual results go first so their snippets are preserved when a higher-scoring\n  // direct/temporal result overrides the same path in mergeAgentResults.\n  const merged = mergeAgentResults(\n    [...contextualResults, ...directResults, ...temporalResults],\n    options.agentWeights ?? PARALLEL_AGENT_WEIGHTS,\n    maxResults,\n    options.resolveNamespace,\n  );\n  return populateEmptySnippets(merged, memoryDir);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-6SXVCD7W.js → chunk-W7IGLX4G.js}

@@ -1,6 +1,6 @@
 import {
   assertPathInsideRoot
-} from "./chunk-VSMRDBFT.js";
+} from "./chunk-GCASGYIO.js";
 import {
   RECALL_FALLBACK_DIRS
 } from "./chunk-VS2IYZRU.js";
@@ -92,4 +92,4 @@ async function scanMemoryDir(memoryDir) {
 export {
   scanMemoryDir
 };
-//# sourceMappingURL=chunk-6SXVCD7W.js.map
+//# sourceMappingURL=chunk-W7IGLX4G.js.map

package/dist/{chunk-KQDNAXOM.js → chunk-WG5HSQ4P.js}

@@ -2,9 +2,12 @@ import {
   readPair,
   resolvePair
 } from "./chunk-35NN3ZFA.js";
+import {
+  composeMemoryEnvelope
+} from "./chunk-CGASUJVP.js";
 import {
   log
-} from "./chunk-37CTGERM.js";
+} from "./chunk-3WCASNQZ.js";
 
 // src/contradiction/resolution.ts
 var VALID_VERBS = ["keep-a", "keep-b", "merge", "both-valid", "needs-more-context"];
@@ -235,11 +238,21 @@ async function prepareMergeReplacement(storage, pairId, idA, idB, options) {
   const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);
   let mergedId;
   try {
-    const mergeResult = await storage.writeMemory(category, mergedContent, {
+    const mergeEnvelope = composeMemoryEnvelope(
+      {
+        content: mergedContent,
+        category,
+        confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
+        tags: ["contradiction-resolution", "merge"]
+      },
+      { source: "contradiction-resolution" },
+      { salvage: true }
+    );
+    if (mergeEnvelope.salvageNotes.length > 0) {
+      log.warn(`contradiction-resolution write salvaged invalid fields: ${mergeEnvelope.salvageNotes.join("; ")}`);
+    }
+    const mergeResult = await storage.writeSealedMemory(mergeEnvelope, {
       actor: "contradiction-resolution",
-      confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
-      tags: ["contradiction-resolution", "merge"],
-      source: "contradiction-resolution",
       lineage: [idA, idB],
       derivedVia: "merge"
     });
@@ -386,4 +399,4 @@ export {
   isValidResolutionVerb,
   executeResolution
 };
-//# sourceMappingURL=chunk-KQDNAXOM.js.map
+//# sourceMappingURL=chunk-WG5HSQ4P.js.map

package/dist/chunk-WG5HSQ4P.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contradiction/resolution.ts"],"sourcesContent":["/**\n * Resolution Verbs — executes user-chosen resolution actions on contradiction pairs (issue #520).\n *\n * All resolution paths delegate to StorageManager.supersedeMemory. Do not\n * reimplement supersession logic here (rule 22: deduplicate resolution).\n */\n\nimport { log } from \"../logger.js\";\nimport { composeMemoryEnvelope } from \"../write-envelope.js\";\nimport type { StorageManager } from \"../storage.js\";\nimport type { MemoryCategory, MemoryFile } from \"../types.js\";\nimport type { ResolutionVerb } from \"./contradiction-review.js\";\nimport { readPair, resolvePair } from \"./contradiction-review.js\";\n\nexport interface ResolutionResult {\n  pairId: string;\n  verb: ResolutionVerb;\n  /** Memory IDs affected by the resolution. */\n  affectedIds: string[];\n  /** Human-readable status. */\n  message: string;\n}\n\nexport interface ExecuteResolutionOptions {\n  /** Existing merged memory to supersede both source memories to. */\n  mergedMemoryId?: string;\n  /** Content for a new merged memory. Required for merge when mergedMemoryId is omitted. */\n  mergedContent?: string;\n  /** Category for a newly created merged memory. Defaults to the shared source category, or fact. */\n  mergedCategory?: MemoryCategory;\n  /** Resolve storage for the pair namespace, or the default namespace for legacy unscoped pairs. */\n  storageForNamespace?: (namespace: string | undefined) => StorageManager | Promise<StorageManager>;\n  /**\n   * Best-effort hook invoked after a contradiction resolution leaves a durable\n   * mutation in the namespace's memory files (issue #1499 sweep, NH1dX / NH3X3).\n   * Every mutating verb — `merge` (creates a new memory and supersedes both\n   * sources), `keep-a`, and `keep-b` (supersede the losing source + rewrite\n   * frontmatter) — writes directly to the pair's (possibly DYNAMIC) namespace\n   * storage, bypassing the extraction write path that records catalog writes. So\n   * without this the namespace's `lastWriteAt` stays stale and QMD maintenance /\n   * `writtenSince` can skip a namespace whose only post-write mutation is\n   * resolving a contradiction. It fires after the resolution commits, or after a\n   * failed resolution/rollback path when durable memory changes are still left on\n   * disk. If a failure rolls back cleanly, this is never called, so the catalog\n   * never records a write that did not survive (rule #25). Non-mutating verbs\n   * (`both-valid`, `needs-more-context`) never trigger it. Callers wire this to\n   * `Orchestrator.recordCatalogWrite(namespace, storageDir)`. Must be\n   * failure-tolerant: it is fire-and-forget and must never affect resolution.\n   */\n  onMergedMemoryWritten?: (namespace: string | undefined, storageDir: string) => void;\n}\n\nconst VALID_VERBS: ResolutionVerb[] = [\"keep-a\", \"keep-b\", \"merge\", \"both-valid\", \"needs-more-context\"];\n\nexport function isValidResolutionVerb(value: string): value is ResolutionVerb {\n  return VALID_VERBS.includes(value as ResolutionVerb);\n}\n\n/**\n * Execute a resolution verb on a contradiction pair.\n *\n * - `keep-a`: Supersede B, keep A active.\n * - `keep-b`: Supersede A, keep B active.\n * - `merge`: Create or verify a real merged memory, then supersede both inputs.\n * - `both-valid`: Mark pair as reviewed; no memories are superseded.\n * - `needs-more-context`: Defer; no action, short cooldown.\n */\nexport async function executeResolution(\n  memoryDir: string,\n  storage: StorageManager,\n  pairId: string,\n  verb: ResolutionVerb,\n  options: ExecuteResolutionOptions = {},\n): Promise<ResolutionResult> {\n  if (typeof verb !== \"string\" || !isValidResolutionVerb(verb)) {\n    throw new Error(`Invalid contradiction resolution verb: ${String(verb)}`);\n  }\n\n  const pair = readPair(memoryDir, pairId);\n  if (!pair) {\n    return { pairId, verb, affectedIds: [], message: `Pair ${pairId} not found` };\n  }\n\n  if (pair.namespace && !options.storageForNamespace) {\n    throw new Error(\n      \"contradiction resolution requires storageForNamespace for namespaced pairs so callers resolve the correct namespace storage\",\n    );\n  }\n\n  const resolutionStorage = options.storageForNamespace\n    ? await options.storageForNamespace(pair.namespace)\n    : storage;\n\n  if (pair.resolution && pair.resolution !== \"needs-more-context\") {\n    return { pairId, verb, affectedIds: [], message: `Pair already resolved with verb \"${pair.resolution}\"` };\n  }\n\n  const [idA, idB] = pair.memoryIds;\n  const affectedIds: string[] = [];\n  let message = \"\";\n  let supersedeFailed = false;\n  let rollbackAfterResolveFailure: (() => Promise<boolean>) | null = null;\n  // Deferred catalog-write touch for any resolution that leaves durable namespace\n  // memory mutations (issue #1499 sweep, NH1dX / NH3X3). Rule #25: never record a\n  // catalog touch for a write that is fully rolled back. Successful mutating\n  // resolutions invoke it after `resolvePair` persists. Failed paths invoke it\n  // only when rollback inspection shows the namespace still differs from the\n  // pre-mutation snapshot.\n  let recordCatalogWriteTouch: (() => void) | null = null;\n  // Returns the deferred touch fn for a mutating verb (or null when the caller\n  // wired no catalog hook), so each branch assigns `recordCatalogWriteTouch`\n  // directly in the function body — keeping TS control-flow narrowing intact at\n  // the post-commit invocation below.\n  const buildCatalogTouch = (): (() => void) | null => {\n    if (!options.onMergedMemoryWritten) return null;\n    const onMergedMemoryWritten = options.onMergedMemoryWritten;\n    const namespace = pair.namespace;\n    const storageDir = resolutionStorage.dir;\n    return () => onMergedMemoryWritten(namespace, storageDir);\n  };\n  const catalogWriteTouch = buildCatalogTouch();\n  const recordCatalogWriteTouchSafely = (context: string, touch = catalogWriteTouch): void => {\n    if (!touch) return;\n    try {\n      touch();\n    } catch (err) {\n      log.warn(\n        \"[contradiction-resolution] catalog write touch failed for pair=%s context=%s: %s\",\n        pairId,\n        context,\n        err instanceof Error ? err.message : err,\n      );\n    }\n  };\n  const touchCatalogIfRollbackLeftChange = async (\n    context: string,\n    snapshots: MemoryFile[],\n    replacement?: Extract<MergeReplacement, { ok: true }>,\n  ): Promise<void> => {\n    if (!catalogWriteTouch) return;\n    if (await rollbackLeftDurableMutation(resolutionStorage, snapshots, replacement)) {\n      recordCatalogWriteTouchSafely(context);\n    }\n  };\n\n  switch (verb) {\n    case \"keep-a\": {\n      const keepTarget = await validateKeepTarget(resolutionStorage, pairId, idA);\n      if (!keepTarget.ok) {\n        supersedeFailed = true;\n        message = keepTarget.message;\n        break;\n      }\n      const sourceB = await loadSourceSnapshot(resolutionStorage, idB);\n      const ok = sourceB\n        ? await supersedeSafe(resolutionStorage, idB, idA, \"contradiction-resolution:keep-a\")\n        : false;\n      if (ok) {\n        affectedIds.push(idB);\n        rollbackAfterResolveFailure = async () =>\n          restoreMemorySnapshot(resolutionStorage, sourceB!, \"contradiction-resolution:keep-a-rollback\");\n        // keep-a superseded idB in this namespace — record a catalog touch once\n        // the resolution durably commits (NH3X3).\n        recordCatalogWriteTouch = catalogWriteTouch;\n        message = `Kept ${idA}, superseded ${idB}`;\n      }\n      else {\n        supersedeFailed = true;\n        const rolledBack = sourceB\n          ? await restoreMemorySnapshot(resolutionStorage, sourceB, \"contradiction-resolution:keep-a-rollback\")\n          : false;\n        if (sourceB && !rolledBack) {\n          await touchCatalogIfRollbackLeftChange(\"keep-a-rollback-incomplete\", [sourceB]);\n        }\n        message = rolledBack\n          ? `Supersede failed for ${idB}; restored ${idB} and did not resolve`\n          : `Supersede failed for ${idB}; rollback incomplete for ${idB} and pair is not resolved`;\n      }\n      break;\n    }\n    case \"keep-b\": {\n      const keepTarget = await validateKeepTarget(resolutionStorage, pairId, idB);\n      if (!keepTarget.ok) {\n        supersedeFailed = true;\n        message = keepTarget.message;\n        break;\n      }\n      const sourceA = await loadSourceSnapshot(resolutionStorage, idA);\n      const ok = sourceA\n        ? await supersedeSafe(resolutionStorage, idA, idB, \"contradiction-resolution:keep-b\")\n        : false;\n      if (ok) {\n        affectedIds.push(idA);\n        rollbackAfterResolveFailure = async () =>\n          restoreMemorySnapshot(resolutionStorage, sourceA!, \"contradiction-resolution:keep-b-rollback\");\n        // keep-b superseded idA in this namespace — record a catalog touch once\n        // the resolution durably commits (NH3X3).\n        recordCatalogWriteTouch = catalogWriteTouch;\n        message = `Kept ${idB}, superseded ${idA}`;\n      }\n      else {\n        supersedeFailed = true;\n        const rolledBack = sourceA\n          ? await restoreMemorySnapshot(resolutionStorage, sourceA, \"contradiction-resolution:keep-b-rollback\")\n          : false;\n        if (sourceA && !rolledBack) {\n          await touchCatalogIfRollbackLeftChange(\"keep-b-rollback-incomplete\", [sourceA]);\n        }\n        message = rolledBack\n          ? `Supersede failed for ${idA}; restored ${idA} and did not resolve`\n          : `Supersede failed for ${idA}; rollback incomplete for ${idA} and pair is not resolved`;\n      }\n      break;\n    }\n    case \"merge\": {\n      const replacement = await prepareMergeReplacement(resolutionStorage, pairId, idA, idB, options);\n      if (!replacement.ok) {\n        supersedeFailed = true;\n        message = replacement.message;\n        break;\n      }\n\n      const okA = await supersedeSafe(resolutionStorage, idA, replacement.mergedId, \"contradiction-resolution:merge\");\n      if (!okA) {\n        supersedeFailed = true;\n        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);\n        message = rolledBackA\n          ? `Merge failed for ${idA}; restored ${idA} and did not resolve`\n          : `Merge failed for ${idA}; rollback incomplete for ${idA} and pair is not resolved`;\n        if (rolledBackA) {\n          await cleanupCreatedReplacement(resolutionStorage, replacement);\n        }\n        else {\n          await touchCatalogIfRollbackLeftChange(\"merge-first-rollback-incomplete\", [replacement.sourceA], replacement);\n        }\n        break;\n      }\n\n      const okB = await supersedeSafe(resolutionStorage, idB, replacement.mergedId, \"contradiction-resolution:merge\");\n      if (!okB) {\n        supersedeFailed = true;\n        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);\n        const rolledBackB = await restoreMemorySnapshot(resolutionStorage, replacement.sourceB);\n        message = rolledBackA && rolledBackB\n          ? `Merge failed for ${idB}; restored ${idA} and ${idB} and did not resolve`\n          : `Merge failed for ${idB}; rollback incomplete for ${[\n            rolledBackA ? undefined : idA,\n            rolledBackB ? undefined : idB,\n          ].filter(Boolean).join(\", \")} and pair is not resolved`;\n        if (rolledBackA && rolledBackB) {\n          await cleanupCreatedReplacement(resolutionStorage, replacement);\n        }\n        else {\n          await touchCatalogIfRollbackLeftChange(\n            \"merge-second-rollback-incomplete\",\n            [replacement.sourceA, replacement.sourceB],\n            replacement,\n          );\n        }\n        break;\n      }\n\n      affectedIds.push(idA, idB);\n      rollbackAfterResolveFailure = async () => {\n        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);\n        const rolledBackB = await restoreMemorySnapshot(resolutionStorage, replacement.sourceB);\n        if (rolledBackA && rolledBackB) {\n          await cleanupCreatedReplacement(resolutionStorage, replacement);\n        }\n        return rolledBackA && rolledBackB;\n      };\n      // Catalog write touch (issue #1499 sweep): the merge supersedes BOTH sources\n      // (and, when created, writes a fresh merged memory) in the pair's (possibly\n      // dynamic) namespace storage — but the resolution is not durable yet\n      // (resolvePair persists below, and a failure rolls the merge back). Defer\n      // the touch so it fires ONLY after the resolution commits past the rollback\n      // point (NH1dX, rule #25). Arm it for EVERY successful merge — even reusing\n      // an existing merged-id still supersedes both sources, a namespace mutation\n      // that must refresh `lastWriteAt` (NH3X3). Otherwise a dynamic namespace\n      // whose only durable mutation is a contradiction merge stays invisible to\n      // QMD maintenance / `writtenSince`. Best-effort on the caller side.\n      recordCatalogWriteTouch = catalogWriteTouch;\n      message = `Both memories superseded by merged ${replacement.mergedId}`;\n      break;\n    }\n    case \"both-valid\": {\n      message = \"Pair marked as both-valid; cooldown applied\";\n      break;\n    }\n    case \"needs-more-context\": {\n      message = \"Deferred; no action taken, short cooldown applied\";\n      break;\n    }\n  }\n\n  if (!supersedeFailed) {\n    let resolved = false;\n    try {\n      resolved = resolvePair(memoryDir, pairId, verb) !== null;\n    } catch (err) {\n      log.warn(\n        \"[contradiction-resolution] failed to persist pair=%s verb=%s: %s\",\n        pairId,\n        verb,\n        err instanceof Error ? err.message : err,\n      );\n    }\n    if (!resolved) {\n      if (rollbackAfterResolveFailure) {\n        const rolledBack = await rollbackAfterResolveFailure();\n        affectedIds.length = 0;\n        message = rolledBack\n          ? `Resolution persistence failed; rolled back memory changes and did not resolve ${pairId}`\n          : \"Resolution persistence failed; rollback incomplete and pair is not resolved\";\n        if (!rolledBack && recordCatalogWriteTouch) {\n          recordCatalogWriteTouchSafely(\"resolve-persistence-rollback-incomplete\", recordCatalogWriteTouch);\n        }\n      } else {\n        message = \"Resolution persistence failed; pair is not resolved\";\n      }\n    } else if (recordCatalogWriteTouch) {\n      // The resolution durably committed (memory mutated AND the resolution\n      // persisted past the rollback point). Only now is it safe to record the\n      // catalog write for the namespace mutation (NH1dX / NH3X3, rule #25).\n      // Best-effort: the caller's callback swallows errors; guard here so a\n      // throwing callback never derails a successful resolution.\n      recordCatalogWriteTouchSafely(\"resolved\", recordCatalogWriteTouch);\n    }\n  }\n  log.info(\"[contradiction-resolution] pair=%s verb=%s affected=%d\", pairId, verb, affectedIds.length);\n  return { pairId, verb, affectedIds, message };\n}\n\ntype MergeReplacement =\n  | {\n      ok: true;\n      mergedId: string;\n      sourceA: MemoryFile;\n      sourceB: MemoryFile;\n      created: boolean;\n    }\n  | {\n      ok: false;\n      message: string;\n    };\n\nasync function prepareMergeReplacement(\n  storage: StorageManager,\n  pairId: string,\n  idA: string,\n  idB: string,\n  options: ExecuteResolutionOptions,\n): Promise<MergeReplacement> {\n  const sourceA = await storage.getMemoryById(idA);\n  const sourceB = await storage.getMemoryById(idB);\n  if (!sourceA || !sourceB) {\n    return { ok: false, message: `Merge requires both source memories to exist; not resolving ${pairId}` };\n  }\n\n  const requestedMergedId = options.mergedMemoryId?.trim();\n  if (requestedMergedId) {\n    if (requestedMergedId === idA || requestedMergedId === idB) {\n      return { ok: false, message: \"Merge replacement must be distinct from both source memories; not resolving\" };\n    }\n    const replacement = await storage.getMemoryById(requestedMergedId);\n    if (!replacement) {\n      return { ok: false, message: `Merged memory ${requestedMergedId} not found; not resolving` };\n    }\n    const replacementStatus = replacement.frontmatter.status ?? \"active\";\n    if (replacementStatus !== \"active\") {\n      return {\n        ok: false,\n        message: `Merged memory ${requestedMergedId} is ${replacementStatus}; not resolving`,\n      };\n    }\n    return { ok: true, mergedId: requestedMergedId, sourceA, sourceB, created: false };\n  }\n\n  const mergedContent = options.mergedContent;\n  if (typeof mergedContent !== \"string\" || mergedContent.trim().length === 0) {\n    return {\n      ok: false,\n      message: \"Merge requires mergedMemoryId or mergedContent; no memories changed\",\n    };\n  }\n\n  const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);\n  let mergedId: string;\n  try {\n    // Sealed-envelope write (issue #1989 PR4): merged content is\n    // LLM-produced — salvage; drops are warn-logged.\n    const mergeEnvelope = composeMemoryEnvelope(\n      {\n        content: mergedContent,\n        category,\n        confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),\n        tags: [\"contradiction-resolution\", \"merge\"],\n      },\n      { source: \"contradiction-resolution\" },\n      { salvage: true },\n    );\n    if (mergeEnvelope.salvageNotes.length > 0) {\n      log.warn(`contradiction-resolution write salvaged invalid fields: ${mergeEnvelope.salvageNotes.join(\"; \")}`);\n    }\n    const mergeResult = await storage.writeSealedMemory(mergeEnvelope, {\n      actor: \"contradiction-resolution\",\n      lineage: [idA, idB],\n      derivedVia: \"merge\",\n    });\n    mergedId = mergeResult.id;\n    if (mergeResult.tombstoneBlocked) {\n      // #1645: merged content matched a tombstone (pending_review). Don't\n      // supersede both sources to a non-active replacement — that retires\n      // the only active copies. Clean up the pending merge and abort the pair.\n      await cleanupMemoryId(storage, mergedId);\n      return { ok: false, message: `Merged memory for ${pairId} was tombstone-blocked (pending_review); not resolving — sources kept active` };\n    }\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] merged memory creation failed for %s: %s\",\n      pairId,\n      err instanceof Error ? err.message : err,\n    );\n    return { ok: false, message: `Merged memory could not be created; not resolving ${pairId}` };\n  }\n  const replacement = await storage.getMemoryById(mergedId);\n  if (!replacement) {\n    await cleanupMemoryId(storage, mergedId);\n    return { ok: false, message: `Merged memory ${mergedId} could not be verified; not resolving` };\n  }\n  return { ok: true, mergedId, sourceA, sourceB, created: true };\n}\n\nfunction mergedMemoryCategory(sourceA: MemoryFile, sourceB: MemoryFile): MemoryCategory {\n  return sourceA.frontmatter.category === sourceB.frontmatter.category\n    ? sourceA.frontmatter.category\n    : \"fact\";\n}\n\ntype KeepTargetValidation =\n  | { ok: true }\n  | { ok: false; message: string };\n\nasync function validateKeepTarget(\n  storage: StorageManager,\n  pairId: string,\n  keepId: string,\n): Promise<KeepTargetValidation> {\n  const target = await loadSourceSnapshot(storage, keepId);\n  if (!target) {\n    return { ok: false, message: `Kept memory ${keepId} not found; not resolving ${pairId}` };\n  }\n\n  const status = target.frontmatter.status ?? \"active\";\n  if (status !== \"active\") {\n    return { ok: false, message: `Kept memory ${keepId} is ${status}; not resolving ${pairId}` };\n  }\n\n  return { ok: true };\n}\n\nasync function loadSourceSnapshot(storage: StorageManager, memoryId: string): Promise<MemoryFile | null> {\n  try {\n    return await storage.getMemoryById(memoryId);\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] source snapshot failed for %s: %s\",\n      memoryId,\n      err instanceof Error ? err.message : err,\n    );\n    return null;\n  }\n}\n\nasync function restoreMemorySnapshot(\n  storage: StorageManager,\n  memory: MemoryFile,\n  reasonCode = \"contradiction-resolution:merge-rollback\",\n): Promise<boolean> {\n  try {\n    const current = await storage.getMemoryById(memory.frontmatter.id);\n    if (!current) return false;\n    const restoredFrontmatter: Partial<MemoryFile[\"frontmatter\"]> = {\n      ...memory.frontmatter,\n      status: memory.frontmatter.status,\n      supersededBy: memory.frontmatter.supersededBy,\n      supersededAt: memory.frontmatter.supersededAt,\n    };\n    return await storage.writeMemoryFrontmatter(current, restoredFrontmatter, {\n      actor: \"contradiction-resolution\",\n      reasonCode,\n    });\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] rollback failed for %s: %s\",\n      memory.frontmatter.id,\n      err instanceof Error ? err.message : err,\n    );\n    return false;\n  }\n}\n\nasync function rollbackLeftDurableMutation(\n  storage: StorageManager,\n  snapshots: MemoryFile[],\n  replacement?: Extract<MergeReplacement, { ok: true }>,\n): Promise<boolean> {\n  for (const snapshot of snapshots) {\n    try {\n      const current = await storage.getMemoryById(snapshot.frontmatter.id);\n      if (!current) return true;\n      if (supersessionStateChanged(current, snapshot)) return true;\n    } catch (err) {\n      log.warn(\n        \"[contradiction-resolution] rollback inspection failed for %s: %s\",\n        snapshot.frontmatter.id,\n        err instanceof Error ? err.message : err,\n      );\n      return true;\n    }\n  }\n\n  if (replacement?.created) {\n    try {\n      return (await storage.getMemoryById(replacement.mergedId)) !== null;\n    } catch (err) {\n      log.warn(\n        \"[contradiction-resolution] rollback replacement inspection failed for %s: %s\",\n        replacement.mergedId,\n        err instanceof Error ? err.message : err,\n      );\n      return true;\n    }\n  }\n\n  return false;\n}\n\nfunction supersessionStateChanged(current: MemoryFile, snapshot: MemoryFile): boolean {\n  return (\n    current.frontmatter.status !== snapshot.frontmatter.status ||\n    current.frontmatter.supersededBy !== snapshot.frontmatter.supersededBy ||\n    current.frontmatter.supersededAt !== snapshot.frontmatter.supersededAt\n  );\n}\n\nasync function cleanupCreatedReplacement(storage: StorageManager, replacement: Extract<MergeReplacement, { ok: true }>): Promise<void> {\n  if (!replacement.created) return;\n  await cleanupMemoryId(storage, replacement.mergedId);\n}\n\nasync function cleanupMemoryId(storage: StorageManager, memoryId: string): Promise<void> {\n  try {\n    const memory = await storage.getMemoryById(memoryId);\n    const invalidated = await storage.invalidateMemory(memoryId);\n    if (invalidated && memory?.frontmatter.category === \"fact\") {\n      await storage.removeFactContentHashesForMemories([memory]);\n    }\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] cleanup failed for merged memory %s: %s\",\n      memoryId,\n      err instanceof Error ? err.message : err,\n    );\n  }\n}\n\nasync function supersedeSafe(\n  storage: StorageManager,\n  oldId: string,\n  newId: string,\n  reason: string,\n): Promise<boolean> {\n  try {\n    const result = await storage.supersedeMemory(oldId, newId, reason);\n    if (result === false) {\n      log.warn(\"[contradiction-resolution] supersede returned false for %s → %s\", oldId, newId);\n      return false;\n    }\n    return true;\n  } catch (err) {\n    log.warn(\n      \"[contradiction-resolution] supersede failed %s → %s: %s\",\n      oldId,\n      newId,\n      err instanceof Error ? err.message : err,\n    );\n    return false;\n  }\n}\n"],"mappings":"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","names":["replacement"]}

package/dist/{chunk-LTJAMRGI.js → chunk-WL5EBRDH.js}

@@ -101,7 +101,7 @@ async function withHeldFileLock(lockPath, opts, task) {
   const lockDir = path.dirname(lockPath);
   const held = await acquireLock(lockPath, lockDir, ownerId, opts, maxWaitMs, pollMs);
   if (!held) {
-    return task(false);
+    return task(false, { refresh: async () => false });
   }
   const heartbeat = setInterval(() => {
     lockHeldBySelf(held).then((ours) => {
@@ -112,8 +112,11 @@ async function withHeldFileLock(lockPath, opts, task) {
     });
   }, heartbeatMs);
   heartbeat.unref?.();
+  const controller = {
+    refresh: () => refreshHeldLock(held, warn, opts.onBeforeRefreshUtimesForTest)
+  };
   try {
-    return await task(true);
+    return await task(true, controller);
   } finally {
     clearInterval(heartbeat);
     await releaseLock(held, warn, opts.onAfterReleaseRenameForTest);
@@ -272,6 +275,17 @@ async function lockHeldBySelf(held) {
     return false;
   }
 }
+async function refreshHeldLock(held, warn, onBeforeRefreshUtimesForTest) {
+  if (!await lockHeldBySelf(held)) return false;
+  if (onBeforeRefreshUtimesForTest) await onBeforeRefreshUtimesForTest();
+  try {
+    await utimes(held.path, /* @__PURE__ */ new Date(), /* @__PURE__ */ new Date());
+  } catch (err) {
+    warn("withHeldFileLock manual refresh failed", err);
+    return false;
+  }
+  return lockHeldBySelf(held);
+}
 function sleep(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -283,4 +297,4 @@ export {
   serializeMutations,
   withHeldFileLock
 };
-//# sourceMappingURL=chunk-LTJAMRGI.js.map
+//# sourceMappingURL=chunk-WL5EBRDH.js.map

package/dist/chunk-WL5EBRDH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/serialize-mutations.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// Shared serialized-mutation utilities for TOCTOU hotspots (issue #1524).\n//\n// Two complementary primitives that the namespace catalog (`queueCritical` +\n// `withHeldCatalogLock`), the storage router's resolve-hook serialization, and\n// the summary-snapshot writer each re-implement today:\n//\n//   1. `serializeMutations(key, task)` — keyed IN-PROCESS async serialization\n//      that recovers after a rejection (CLAUDE.md rule #40). One failed task\n//      never poisons the tasks queued behind it; the failed task's error is\n//      still surfaced to ITS caller.\n//\n//   2. `withHeldFileLock(lockPath, opts, task)` — a held CROSS-PROCESS file\n//      lock with replacement-safe stale breaking (the NG7Bg invariant from\n//      #1506 round 28) and ownership-checked release.\n//\n// This is the UTILITY module only. Per-issue PR split: one PR for the utility\n// + tests (this file), then one PR per adoption hotspot (catalog, router\n// provenance, summary snapshot). No adoptions live here.\n// ---------------------------------------------------------------------------\n\nimport { randomUUID } from \"node:crypto\";\nimport { link, mkdir, open, readFile, rename, stat, unlink, utimes } from \"node:fs/promises\";\nimport path from \"node:path\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// 1. serializeMutations — keyed async serialization with rejection recovery\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * One entry in the per-key serialization map. `tail` is the recovered promise\n * the next queued task chains off of; it never rejects (both settle handlers\n * swallow), so a prior task's failure can never break subsequent ones.\n */\ninterface MutationChainEntry {\n  tail: Promise<void>;\n}\n\n/**\n * Instance-scoped keyed serializer. Holds the per-key chain map so that all\n * tasks queued under the same key on the SAME serializer run strictly in order.\n *\n * The map is instance-scoped (not module-level) so tests can construct a fresh\n * serializer per case and avoid cross-test contamination, and so adopters that\n * want isolation (e.g. one serializer per storage root) can have it. The free\n * {@link serializeMutations} export delegates to a single shared default\n * instance for callers that want process-wide serialization.\n */\nexport class MutationSerializer {\n  private readonly chains = new Map<string, MutationChainEntry>();\n\n  /**\n   * Run `task` strictly after every other task already queued under `key` on\n   * this serializer has settled.\n   *\n   * Rejection recovery (rule #40, mirroring the catalog's `queueCritical`):\n   * if a prior task rejects, later tasks STILL RUN, while the rejecting task's\n   * error is surfaced to ITS OWN caller. Concretely, the recovered tail is\n   * `run.then(noop, noop)` — never a bare `.then(fn)`, which would let one\n   * failure kill every queued task behind it.\n   *\n   * No unbounded growth: when a chain's last task settles and no newer task\n   * chained onto it, its entry is deleted (the storage router's\n   * `inFlightResolved` marker-then-clear discipline).\n   */\n  serialize<T>(key: string, task: () => Promise<T>): Promise<T> {\n    if (typeof key !== \"string\" || key.length === 0) {\n      throw new TypeError(\"MutationSerializer.serialize: key must be a non-empty string\");\n    }\n    if (typeof task !== \"function\") {\n      throw new TypeError(\"MutationSerializer.serialize: task must be a function returning a promise\");\n    }\n\n    let entry = this.chains.get(key);\n    if (!entry) {\n      entry = { tail: Promise.resolve() };\n      this.chains.set(key, entry);\n    }\n\n    // Chain this task off the prior tail. `tail.then(task)` runs task only once\n    // the previous task has settled, preserving read-modify-write ordering.\n    const run = entry.tail.then(task);\n\n    // Recover the tail after a rejection so a failed task never poisons later\n    // ones. Both handlers swallow; `run` still carries the original resolution\n    // (or rejection) to THIS caller. This is the line a naive `.then(fn)`\n    // implementation omits — see the \"naive poison chain\" prove-fail test.\n    const recovered = run.then(settleNoop, settleNoop);\n    entry.tail = recovered;\n\n    // Self-cleaning: once our recovered tail settles, if no newer task chained\n    // onto us the entry still points at `recovered` and is safe to delete. A\n    // concurrent `serialize()` call enqueues synchronously and would have\n    // replaced `entry.tail` BEFORE this microtask runs, so the identity check\n    // is race-free (no newer task's entry can be wrongly removed).\n    //\n    // `recovered` cannot reject in correct operation (both handlers above\n    // swallow) and the cleanup body cannot throw — but we attach a rejection\n    // handler anyway so that IF the recovery invariant is ever broken, the\n    // failure surfaces as a behavioral assertion (skipped tasks) rather than an\n    // unhandled-rejection storm that masks which task failed. The handler is a\n    // no-op: cleanup only runs on fulfillment.\n    void recovered.then(\n      () => {\n        if (entry && entry.tail === recovered) {\n          this.chains.delete(key);\n        }\n      },\n      () => undefined,\n    );\n\n    return run;\n  }\n\n  /**\n   * Test-only: the number of keys with a not-yet-cleaned chain. Used to assert\n   * the no-unbounded-growth invariant. Not part of the public contract.\n   */\n  pendingKeysForTest(): number {\n    return this.chains.size;\n  }\n}\n\n/**\n * Recovery handler shared by both settle arms. Named (not inline\n * `() => undefined`) so the chain assignment stays self-documenting in stack\n * traces and the review-patterns poison-chain check can see the chain is\n * recovered, not bare `.then(fn)`.\n */\nfunction settleNoop(): void {\n  /* swallow — the original resolution/rejection is carried by `run` */\n}\n\n/**\n * Process-wide default serializer backing the free {@link serializeMutations}\n * export. Lazy so it is only created when first used (tests that construct\n * their own `MutationSerializer` pay nothing).\n */\nlet defaultSerializer: MutationSerializer | undefined;\n\n/**\n * Free-function entry point (issue #1524 signature). Serializes `task` against\n * every other task queued under `key` across the whole process, via a shared\n * default {@link MutationSerializer}. For isolated/testable serialization,\n * construct a `MutationSerializer` directly.\n */\nexport function serializeMutations<T>(key: string, task: () => Promise<T>): Promise<T> {\n  if (!defaultSerializer) defaultSerializer = new MutationSerializer();\n  return defaultSerializer.serialize(key, task);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// 2. withHeldFileLock — cross-process held file lock with stale breaking\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Options for {@link withHeldFileLock}. */\nexport interface HeldFileLockOptions {\n  /**\n   * A lock whose mtime is older than this (in ms) is treated as a crashed\n   * holder and broken. Required — there is no safe default, since the right\n   * value depends on how long the guarded critical section can legitimately\n   * run.\n   */\n  readonly staleMs: number;\n  /**\n   * Bounded acquisition: give up trying to acquire a busy lock after this long\n   * (ms) and invoke `task(false)` best-effort WITHOUT holding the lock, rather\n   * than blocking forever or crashing the primary op. Default 5000ms (matches\n   * the namespace catalog's `REBUILD_LOCK_MAX_WAIT_MS`).\n   */\n  readonly maxWaitMs?: number;\n  /**\n   * Poll interval (ms) while waiting for a busy lock to clear. Default 50ms.\n   */\n  readonly pollMs?: number;\n  /**\n   * While WE hold the lock, refresh its mtime on this cadence (ms) so a\n   * legitimately long task is not mistaken for a crashed holder and broken out\n   * from under. Default `floor(staleMs / 3)` (at least 100ms), mirroring the\n   * catalog heartbeat ratio. Must be comfortably below `staleMs`.\n   */\n  readonly heartbeatMs?: number;\n  /**\n   * Test seam (NG7Bg, #1506 round 28): fires AFTER a lock is judged stale and\n   * BEFORE the re-verify + unlink, simulating a replacement lock being created\n   * in the race window. No-op in production.\n   */\n  readonly onBeforeBreakStaleUnlinkForTest?: () => Promise<void> | void;\n  /**\n   * Test seam (codex P2): fires AFTER the release rename moves the lock to a\n   * trash path and BEFORE the ownership re-verify/restore — simulating a third\n   * contender acquiring the (now-empty) lockPath in the race window. No-op in\n   * production. Used to prove the pre-check prevents the rename entirely.\n   */\n  readonly onAfterReleaseRenameForTest?: () => Promise<void> | void;\n  /**\n   * Test seam (#2033): fires inside {@link HeldFileLockController.refresh} AFTER\n   * the ownership pre-check passes and BEFORE the `utimes` mtime bump —\n   * simulating a peer that deletes the lock (making the bump throw) or replaces\n   * it (a different owner the post-bump re-check must catch). No-op in\n   * production; proves refresh reports LOST rather than clobbering a peer.\n   */\n  readonly onBeforeRefreshUtimesForTest?: () => Promise<void> | void;\n  /**\n   * Best-effort hook for non-fatal lock warnings (heartbeat refresh failure,\n   * release-time ownership check failure). Never throws into the caller. If\n   * omitted, warnings are swallowed (the lock is advisory; release/heartbeat\n   * failures must never crash the guarded op).\n   */\n  readonly onLockWarning?: (message: string, err: unknown) => void;\n}\n\n/**\n * Control surface handed to a held-lock task so a long, CPU-bound critical\n * section can re-assert ownership immediately before its destructive write.\n */\nexport interface HeldFileLockController {\n  /**\n   * Re-verify THIS acquirer still owns the lock and, when it does, refresh the\n   * lock's mtime. Returns `true` only while we still hold it.\n   *\n   * The timer heartbeat cannot fire while a synchronous, CPU-bound section\n   * (a large parse/merge/sort/serialize) blocks the event loop, so a peer can\n   * judge the lock stale, break it, and start its own write within the stale\n   * window. A caller about to perform a destructive rewrite MUST call this\n   * first: `false` means the lock was stale-broken/replaced and the caller MUST\n   * abort rather than clobber the peer that now holds it; `true` also re-stamps\n   * the mtime so the bounded write that immediately follows cannot itself be\n   * judged stale mid-write. On the best-effort unlocked path (`acquired` was\n   * `false`) this always resolves `false` — there is no lock to hold.\n   */\n  refresh(): Promise<boolean>;\n}\n\n/** Default bounded acquisition wait, mirroring the catalog. */\nconst DEFAULT_MAX_WAIT_MS = 5_000;\n/** Default busy-lock poll interval, mirroring the catalog. */\nconst DEFAULT_POLL_MS = 50;\n/** Floor for the derived heartbeat cadence. */\nconst MIN_HEARTBEAT_MS = 100;\n/** Node's setTimeout/setInterval 32-bit signed-int ceiling (2^31 − 1 ms ≈ 24.8\n * days). Delays above this are silently clamped to 1ms by the Node timer, so\n * timer-backed options (pollMs, heartbeatMs) must be rejected at this boundary\n * (chatgpt-codex-connector P2). */\nconst MAX_TIMER_DELAY_MS = 2_147_483_647;\n\n/** Internal handle for a lock we successfully acquired. */\ninterface HeldLock {\n  readonly path: string;\n  readonly ownerId: string;\n}\n\n/**\n * Run `task` under an exclusive on-disk lock at `lockPath`.\n *\n * Cross-process mutex via `open(lockPath, \"wx\")` (atomic exclusive create).\n * While held, a heartbeat timer refreshes the lock's mtime so a legitimately\n * long task is not mistaken for a crashed holder and broken out from under. A\n * lock older than `opts.staleMs` is treated as stale and broken — but\n * REPLACEMENT-SAFE (NG7Bg): we capture the stale lock's identity (full content\n * line: `<pid> <owner-uuid> <iso>`) when judging it stale, then RE-READ and\n * RE-STAT immediately before `unlink`, deleting only if byte-identical AND\n * still stale. A replacement lock created in the window has a different owner\n * id / timestamp, so its content differs and is left untouched.\n *\n * `task` receives `acquired: boolean` — `true` when we hold the lock, `false`\n * when acquisition timed out (best-effort). The signature takes\n * `(acquired) => Promise<T>` rather than the issue's sketched `() => Promise<T>`\n * so this can be the SINGLE lock home (issue: \"do NOT leave two lock\n * implementations; pick one home\"): the catalog's touch path needs to DROP on\n * timeout, which requires knowing whether the lock was acquired. A caller that\n * ignores the flag is still assignable (`() => Promise<T>` ⊆\n * `(acquired: boolean) => Promise<T>` in TypeScript).\n *\n * Release is ownership-checked: we only `unlink` a lock whose content still\n * identifies THIS acquirer (same owner id), so a replacement created after we\n * stopped heartbeating is never destroyed — mirroring the catalog's\n * `rebuildLockHeldBySelf`.\n *\n * ADOPTION NOTE: lock only the brief final read-merge-write window, never a\n * long scan — a scan-length lock makes concurrent writers time out and\n * silently drop work (catalog round 5, codex/cursor P2).\n */\nexport async function withHeldFileLock<T>(\n  lockPath: string,\n  opts: HeldFileLockOptions,\n  task: (acquired: boolean, lock: HeldFileLockController) => Promise<T>,\n): Promise<T> {\n  if (typeof lockPath !== \"string\" || lockPath.length === 0) {\n    throw new TypeError(\"withHeldFileLock: lockPath must be a non-empty string\");\n  }\n  if (typeof opts?.staleMs !== \"number\" || !Number.isFinite(opts.staleMs) || opts.staleMs <= 0) {\n    throw new TypeError(\n      `withHeldFileLock: opts.staleMs must be a positive finite number ` +\n        `(valid range: > 0 ms, finite; got ${formatInvalidNumber(opts?.staleMs)}).`,\n    );\n  }\n\n  // Validate optional timings: a NaN/Infinity here is a real hazard (e.g.\n  // `Date.now() + NaN` === NaN, so `Date.now() >= deadline` is always false and\n  // the bounded acquire loop would wait forever instead of falling back to\n  // best-effort). Reject invalid input rather than silently defaulting it\n  // (codex P2 review). Omitting an option still picks its default.\n  const maxWaitMs = optionalPositiveMs(opts.maxWaitMs, \"maxWaitMs\", DEFAULT_MAX_WAIT_MS, MAX_TIMER_DELAY_MS);\n  const pollMs = optionalPositiveMs(opts.pollMs, \"pollMs\", DEFAULT_POLL_MS, MAX_TIMER_DELAY_MS);\n  const heartbeatMs = optionalPositiveMs(\n    opts.heartbeatMs,\n    \"heartbeatMs\",\n    Math.max(MIN_HEARTBEAT_MS, Math.floor(opts.staleMs / 3)),\n    MAX_TIMER_DELAY_MS,\n  );\n  if (heartbeatMs >= opts.staleMs) {\n    throw new TypeError(\n      `withHeldFileLock: heartbeatMs (${heartbeatMs}) must be below staleMs (${opts.staleMs}) ` +\n        `(valid range: > 0 and < staleMs ms) so at least one heartbeat lands per stale window.`,\n    );\n  }\n  if (heartbeatMs > MAX_TIMER_DELAY_MS) {\n    throw new TypeError(\n      `withHeldFileLock: derived heartbeatMs (${heartbeatMs} = floor(staleMs/3)) exceeds ` +\n        `Node's setTimeout ceiling (${MAX_TIMER_DELAY_MS} ms). Use an explicit opts.heartbeatMs ` +\n        `at or below ${MAX_TIMER_DELAY_MS} ms.`,\n    );\n  }\n  // Wrap the consumer's warning hook so a throwing callback never turns a\n  // non-fatal advisory lock warning into an unhandled rejection (heartbeat\n  // catch handler) or overrides the task's result (release path). The option\n  // is documented as never throwing into the caller; enforce that here\n  // (codex P2 review).\n  const rawWarn = opts.onLockWarning;\n  const warn = (message: string, err: unknown): void => {\n    if (!rawWarn) return;\n    try {\n      rawWarn(message, err);\n    } catch {\n      /* swallow — a throwing advisory hook must not crash the guarded op */\n    }\n  };\n\n  // Per-call owner identity. Two withHeldFileLock calls in the SAME process\n  // get different ids, so neither mistakes the other's lock for its own\n  // (stronger than the catalog's per-instance id, which is what we want for a\n  // stateless utility).\n  const ownerId = randomUUID();\n  const lockDir = path.dirname(lockPath);\n\n  const held = await acquireLock(lockPath, lockDir, ownerId, opts, maxWaitMs, pollMs);\n  if (!held) {\n    // Best-effort: run the task WITHOUT the lock. The caller decides what to\n    // do (the catalog touch path will drop its append); we never crash the\n    // primary op on contention.\n    return task(false, { refresh: async () => false });\n  }\n\n  // Heartbeat: while WE hold the lock, refresh its mtime so age-based stale\n  // detection sees an active holder and does not break us out from under\n  // (catalog round 5). Failures are swallowed (advisory lock); the timer is\n  // always cleared in the finally.\n  //\n  // OWNERSHIP CHECK (codex P2): if our event loop was paused long enough that\n  // another process judged us stale, broke our lock, and created a replacement,\n  // we must NOT refresh the replacement's mtime — that would keep a (possibly\n  // crashed) replacement looking fresh. Verify lockHeldBySelf before each\n  // utimes; if ownership is lost, stop heartbeating (our lock is gone).\n  const heartbeat = setInterval(() => {\n    lockHeldBySelf(held)\n      .then((ours) => {\n        if (!ours) return; // broken/replaced — stop refreshing\n        return utimes(held.path, new Date(), new Date());\n      })\n      .catch((err: unknown) => {\n        warn(\"withHeldFileLock heartbeat refresh failed\", err);\n      });\n  }, heartbeatMs);\n  // Don't keep the event loop alive solely for the heartbeat.\n  heartbeat.unref?.();\n  const controller: HeldFileLockController = {\n    refresh: () => refreshHeldLock(held, warn, opts.onBeforeRefreshUtimesForTest),\n  };\n  try {\n    return await task(true, controller);\n  } finally {\n    clearInterval(heartbeat);\n    await releaseLock(held, warn, opts.onAfterReleaseRenameForTest);\n  }\n}\n\n/**\n * Resolve an optional millisecond timing option, REJECTING invalid values\n * (NaN, Infinity, non-positive, or above `maxMs`) rather than silently defaulting\n * them. A NaN or Infinity maxWaitMs would make the bounded acquire loop wait\n * forever (`Date.now() + NaN` is NaN); a non-positive poll/heartbeat makes no\n * sense. Timer-backed options (pollMs, heartbeatMs) are bounded to Node's\n * setTimeout ceiling (`MAX_TIMER_DELAY_MS`): a value above 2^31−1 is silently\n * clamped to 1ms by the timer, turning a typo into tight polling (codex P2).\n * Omitting the option (`undefined`) picks `fallback`. Non-number types are also\n * rejected (defensive against config/env coercion).\n */\nfunction optionalPositiveMs(\n  value: number | undefined,\n  name: \"maxWaitMs\" | \"pollMs\" | \"heartbeatMs\",\n  fallback: number,\n  maxMs: number,\n): number {\n  if (value === undefined) return fallback;\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new TypeError(\n      `withHeldFileLock: opts.${name} must be a positive finite number ` +\n        `(valid range: > 0 ms, finite; got ${formatInvalidNumber(value)}). ` +\n        `Omit the option to use the default of ${fallback} ms.`,\n    );\n  }\n  if (value > maxMs) {\n    throw new TypeError(\n      `withHeldFileLock: opts.${name} (${value} ms) exceeds the ${maxMs} ms ` +\n        `ceiling (Node's setTimeout clamps larger delays to 1ms, turning a ` +\n        `typo into tight polling). Omit the option to use the default of ${fallback} ms.`,\n    );\n  }\n  return value;\n}\n\n/**\n * Human-readable label for a rejected numeric input. Makes the error message\n * immediately actionable for NaN/Infinity (which print as \"NaN\"/\"Infinity\" via\n * String() but are easier to triage with an explicit sign), and surfaces the\n * actual type for non-number values (defensive against config/env coercion).\n */\nfunction formatInvalidNumber(value: unknown): string {\n  if (typeof value === \"number\") {\n    if (Number.isNaN(value)) return \"NaN\";\n    if (value === Infinity) return \"+Infinity\";\n    if (value === -Infinity) return \"-Infinity\";\n    return String(value);\n  }\n  return `${typeof value} ${JSON.stringify(value)}`;\n}\n\n/**\n * Atomically create the lock file, looping until acquired/stale-broken/timeout.\n * Returns the held-lock handle on success, or `undefined` on bounded-timeout.\n * Unexpected FS errors proceed best-effort (return undefined) rather than\n * crashing the guarded op, matching the catalog.\n */\nasync function acquireLock(\n  lockPath: string,\n  lockDir: string,\n  ownerId: string,\n  opts: HeldFileLockOptions,\n  maxWaitMs: number,\n  pollMs: number,\n): Promise<HeldLock | undefined> {\n  try {\n    await mkdir(lockDir, { recursive: true });\n  } catch {\n    // Lock-directory setup failure (e.g. an intermediate path is a file, or\n    // permissions deny mkdir) must NOT crash the guarded op — the advisory\n    // lock contract is best-effort. Return undefined so task(false) runs\n    // instead of rejecting (codex P2 review).\n    return undefined;\n  }\n  const deadline = Date.now() + maxWaitMs;\n  for (;;) {\n    try {\n      const handle = await open(lockPath, \"wx\");\n      let wroteMeta = true;\n      try {\n        await handle.writeFile(`${process.pid} ${ownerId} ${new Date().toISOString()}\\n`, \"utf8\");\n      } catch {\n        // The metadata write failed; the lock file may be empty or partial.\n        // Our ownership check on release would NOT find this ownerId, leaving\n        // a malformed lock that lingers until stale and blocks other callers\n        // out of the mutex (codex P2). Undo our exclusive create and report\n        // acquisition failure so the caller runs best-effort instead.\n        wroteMeta = false;\n      } finally {\n        try {\n          await handle.close();\n        } catch {\n          // close() can report a deferred I/O error (e.g. write that appeared\n          // to succeed but failed on flush). The lock file may be malformed —\n          // treat it as a metadata-write failure so the cleanup path unlinks\n          // the orphaned lock (codex P2 review).\n          wroteMeta = false;\n        }\n      }\n      if (!wroteMeta) {\n        await unlink(lockPath).catch(() => undefined);\n        return undefined;\n      }\n      return { path: lockPath, ownerId };\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException | undefined)?.code !== \"EEXIST\") {\n        // Unexpected FS error — proceed best-effort without the lock.\n        return undefined;\n      }\n      // Lock exists: break it if stale, then poll. breakStaleLock is\n      // replacement-safe (NG7Bg) and never throws.\n      await breakStaleLock(lockPath, opts.staleMs, opts.onBeforeBreakStaleUnlinkForTest);\n      if (Date.now() >= deadline) return undefined;\n      // Cap the sleep to the remaining budget so a large pollMs cannot block\n      // acquisition far past maxWaitMs (e.g. maxWaitMs=1000, pollMs=60000\n      // would otherwise block ~60s instead of 1s — codex P2).\n      await sleep(Math.min(pollMs, deadline - Date.now()));\n    }\n  }\n}\n\n/**\n * Replacement-safe stale-lock breaking (NG7Bg, #1506 round 28). Capture the\n * lock's identity when judging it stale, then ATOMICALLY rename it to a unique\n * trash path and verify the moved content matches. A replacement lock created\n * in the race window is either left untouched (different identity at\n * lockPath, so the rename moves the stale lock — not the replacement) or\n * restored (if the rename accidentally moves a replacement, the verify\n * detects the mismatch and renames it back).\n *\n * ATOMICITY (codex P2): `rename` is atomic on POSIX — only ONE contender can\n * successfully rename a given file. This eliminates the TOCTOU between the\n * identity/stat checks and the deletion that a bare `unlink` leaves open:\n * without rename, contender A could verify identity X, pause, then unlink\n * contender B's freshly acquired replacement Y. With rename, A moves whatever\n * is at lockPath, then checks: if it is X, A broke the stale lock; if it is\n * not X (a replacement appeared between A's last check and the rename), A\n * restores it.\n */\nasync function breakStaleLock(\n  lockPath: string,\n  staleMs: number,\n  onBeforeBreakStaleUnlinkForTest: (() => Promise<void> | void) | undefined,\n): Promise<void> {\n  let staleIdentity: string;\n  try {\n    const info = await stat(lockPath);\n    if (Date.now() - info.mtimeMs <= staleMs) {\n      // Not stale (a live holder's heartbeat keeps it fresh) — leave it.\n      return;\n    }\n    staleIdentity = await readFile(lockPath, \"utf8\");\n  } catch {\n    // Lock vanished (released by holder) or stat/read failed — nothing to do.\n    return;\n  }\n  // Test seam: simulate a replacement lock being created in the race window\n  // between the staleness judgment and the atomic break. No-op in production.\n  if (onBeforeBreakStaleUnlinkForTest) {\n    await onBeforeBreakStaleUnlinkForTest();\n  }\n  try {\n    // Re-validate immediately before breaking: the lock must still carry the\n    // SAME identity AND still be stale.\n    const current = await readFile(lockPath, \"utf8\");\n    if (current !== staleIdentity) return; // replaced — leave the fresh lock\n    const recheck = await stat(lockPath);\n    if (Date.now() - recheck.mtimeMs <= staleMs) return; // heartbeat refreshed it\n\n    // ATOMIC BREAK: rename is atomic on POSIX. Only one contender succeeds;\n    // others get ENOENT (the file is already gone). After the rename, verify\n    // the moved content: if it matches staleIdentity we broke the right lock;\n    // if it does not, a replacement appeared in the window and we restore it.\n    const trashPath = `${lockPath}.breaking.${process.pid}.${Date.now()}`;\n    await rename(lockPath, trashPath);\n    try {\n      const moved = await readFile(trashPath, \"utf8\");\n      if (moved !== staleIdentity) {\n        // We accidentally moved a replacement lock (created between our last\n        // check and the rename). Restore it so the replacement holder's lock\n        // survives. Use link (not rename) to AVOID overwriting a fresh lock\n        // that a third contender may have acquired at lockPath while the file\n        // was in trash: link fails with EEXIST if lockPath exists, leaving\n        // the third contender's lock intact (codex P2 review).\n        try {\n          await link(trashPath, lockPath);\n          // link succeeded — remove the redundant trash hard link. The lock\n          // now lives only at lockPath.\n          await unlink(trashPath).catch(() => undefined);\n        } catch {\n          // lockPath already exists (a third contender acquired it). Do NOT\n          // unlink the moved file — it may be a LIVE lock whose holder is\n          // still in its critical section. Destroying it would leave the\n          // holder running with no visible lock, breaking mutual exclusion\n          // (codex P2). Leave it in trash as a breadcrumb; it is not at\n          // lockPath so it does not block other contenders.\n        }\n      } else {\n        // Content matches — but verify the moved file is STILL stale. The\n        // original holder may have resumed and heartbeated between our\n        // pre-rename stat() and the rename, refreshing the mtime. If so, the\n        // holder is live: restore the lock instead of deleting it (codex P2).\n        const movedStat = await stat(trashPath);\n        if (Date.now() - movedStat.mtimeMs <= staleMs) {\n          // Mtime was refreshed — the holder resumed. Restore the lock.\n          try {\n            await link(trashPath, lockPath);\n            await unlink(trashPath).catch(() => undefined);\n          } catch {\n            // lockPath already exists — another contender acquired it. Do NOT\n            // unlink the moved file (it may be a live lock). Leave it in trash.\n          }\n        } else {\n          // Still stale — we broke the right lock. Clean up the trash.\n          await unlink(trashPath).catch(() => undefined);\n        }\n      }\n    } catch {\n      // Could not read the trash file — clean it up best-effort.\n      await unlink(trashPath).catch(() => undefined);\n    }\n  } catch {\n    // The lock changed/vanished between checks — another process handled it.\n  }\n}\n\n/**\n * Release the lock ONLY if its content still identifies THIS acquirer (same\n * owner id). Two-stage ownership check:\n *\n *   1. PRE-CHECK (chatgpt-codex-connector P2): read lockPath BEFORE renaming.\n *      If the lock is already a replacement (a contender broke our stale lock),\n *      return WITHOUT renaming — renaming a replacement out of lockPath leaves\n *      it empty, letting a third contender acquire while the replacement holder\n *      is still active. The replacement is safe at lockPath; leave it alone.\n *\n *   2. ATOMIC CLAIM: if the pre-check saw our ownerId, rename lockPath→trash\n *      (POSIX-atomic) and re-verify on the moved file. A replacement could\n *      appear between the pre-check and the rename; if the moved file is no\n *      longer ours, restore it via link (non-overwriting). This ties the\n *      ownership check to the deletion so a bare readFile-then-unlink TOCTOU\n *      cannot delete a fresh replacement (codex P2).\n */\nasync function releaseLock(\n  held: HeldLock,\n  warn: (message: string, err: unknown) => void,\n  onAfterReleaseRenameForTest: (() => Promise<void> | void) | undefined,\n): Promise<void> {\n  try {\n    // PRE-CHECK (chatgpt-codex-connector P2): read lockPath before renaming. If\n    // the lock is no longer ours, a contender broke our stale lock and created a\n    // replacement. Return WITHOUT renaming — renaming the replacement out of\n    // lockPath leaves it empty, so a third contender could acquire while the\n    // replacement holder is still active. The replacement is safe at lockPath.\n    let precheck: string;\n    try {\n      precheck = await readFile(held.path, \"utf8\");\n    } catch {\n      return; // lock vanished — nothing to release.\n    }\n    if (!precheck.includes(held.ownerId)) {\n      return; // replacement lock — leave it untouched for its holder.\n    }\n    // It was ours when we read it. Atomically claim via rename, then re-verify\n    // on the moved file: a replacement could appear between the pre-check read\n    // above and this rename.\n    const trashPath = `${held.path}.releasing.${process.pid}.${Date.now()}`;\n    await rename(held.path, trashPath);\n    // Test seam: simulate a third contender acquiring the now-empty lockPath\n    // in the rename-to-restore window. No-op in production.\n    if (onAfterReleaseRenameForTest) {\n      await onAfterReleaseRenameForTest();\n    }\n    try {\n      const moved = await readFile(trashPath, \"utf8\");\n      if (moved.includes(held.ownerId)) {\n        // Still our lock — safe to delete.\n        await unlink(trashPath).catch(() => undefined);\n      } else {\n        // Not ours: a replacement appeared between the pre-check and the rename.\n        // Restore it via link (non-overwriting — if lockPath already has a newer\n        // lock, leave it).\n        try {\n          await link(trashPath, held.path);\n        } catch {\n          // lockPath already exists — a newer holder is active. Leave the\n          // moved file in trash rather than destroying a live lock (codex P2).\n          return;\n        }\n        await unlink(trashPath).catch(() => undefined);\n      }\n    } catch {\n      // Could not read the moved file — clean it up best-effort.\n      await unlink(trashPath).catch(() => undefined);\n    }\n  } catch (err) {\n    // Best-effort release; a stale lock will be broken on the next acquire.\n    warn(\"withHeldFileLock release failed\", err);\n  }\n}\n\n/**\n * Whether the lock file at `held.path` was written by THIS acquirer (same owner\n * id). Reads the content and matches the `<pid> <owner-uuid>` prefix; the iso\n * timestamp varies so it is not part of the identity check.\n */\nasync function lockHeldBySelf(held: HeldLock): Promise<boolean> {\n  try {\n    const body = await readFile(held.path, \"utf8\");\n    const parts = body.trim().split(/\\s+/);\n    const fileOwner = parts[1];\n    return typeof fileOwner === \"string\" && fileOwner === held.ownerId;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Re-assert ownership and refresh the lock mtime for {@link HeldFileLockController.refresh}.\n * Returns `true` only while THIS acquirer still owns the lock. When ownership\n * was lost (a peer stale-broke and replaced the lock while a CPU-bound section\n * blocked the event loop), returns `false` WITHOUT touching the replacement's\n * mtime — mirroring the heartbeat's ownership guard.\n *\n * FAIL-CLOSED on the mtime bump (#2033): a `utimes` failure means we cannot\n * prove the lock is still ours AND fresh — the file may have been stale-broken,\n * deleted, or replaced between the ownership check and the bump — so we report\n * lost ownership rather than let the caller rewrite the ledger on an unrefreshed\n * (soon-stale) or already-replaced lock. After a successful bump we RE-CHECK\n * ownership: a peer could have broken and replaced the lock in the window, in\n * which case `utimes` just refreshed the replacement's mtime and we must not\n * report held.\n */\nasync function refreshHeldLock(\n  held: HeldLock,\n  warn: (message: string, err: unknown) => void,\n  onBeforeRefreshUtimesForTest?: () => Promise<void> | void,\n): Promise<boolean> {\n  if (!(await lockHeldBySelf(held))) return false;\n  if (onBeforeRefreshUtimesForTest) await onBeforeRefreshUtimesForTest();\n  try {\n    await utimes(held.path, new Date(), new Date());\n  } catch (err) {\n    warn(\"withHeldFileLock manual refresh failed\", err);\n    return false;\n  }\n  return lockHeldBySelf(held);\n}\n\nfunction sleep(ms: number): Promise<void> {\n  // Manual deferred instead of Promise.withResolvers (ES2024) — plugin-openclaw's\n  // standalone tsconfig targets ES2022 lib and this module is reachable from its\n  // type graph, so withResolvers would TS2550 there (same fix as\n  // extraction-faithfulness.ts:467).\n  return new Promise<void>((resolve) => {\n    // NOT unref'd: this polls inside an awaited acquire loop, so the caller's\n    // await chain keeps the loop alive; unref would let Node exit mid-poll when\n    // nothing else is pending (the heartbeat interval IS unref'd separately).\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-KAWTOYAW.js → chunk-WLZYGLJ4.js}

@@ -1,6 +1,6 @@
 import {
   log
-} from "./chunk-37CTGERM.js";
+} from "./chunk-3WCASNQZ.js";
 
 // src/model-registry.ts
 import fs from "fs";
@@ -236,4 +236,4 @@ var ModelRegistry = class {
 export {
   ModelRegistry
 };
-//# sourceMappingURL=chunk-KAWTOYAW.js.map
+//# sourceMappingURL=chunk-WLZYGLJ4.js.map

package/dist/{chunk-RO4LQGT3.js → chunk-WON4APQY.js}

@@ -1,19 +1,19 @@
 import {
   hasCodexMaterializeSentinel,
   materializeForNamespace
-} from "./chunk-QLULYKWZ.js";
+} from "./chunk-KSXJOC4F.js";
 import {
   resolveNamespaceChildRoot
 } from "./chunk-3UXOZBHV.js";
 import {
   StorageManager
-} from "./chunk-K7LOWSLU.js";
+} from "./chunk-4BJQODZF.js";
 import {
   isSafeRouteNamespace
 } from "./chunk-U3PN77QT.js";
 import {
   log
-} from "./chunk-37CTGERM.js";
+} from "./chunk-3WCASNQZ.js";
 
 // src/connectors/codex-materialize-runner.ts
 import { existsSync } from "fs";
@@ -118,4 +118,4 @@ export {
   runCodexMaterialize,
   runPostConsolidationMaterialize
 };
-//# sourceMappingURL=chunk-RO4LQGT3.js.map
+//# sourceMappingURL=chunk-WON4APQY.js.map