@duckmind/dm-linux-x64 0.65.4 → 0.65.6

package/extensions/dm-lens/dist/clients/observed-mutation.js

@@ -0,0 +1,709 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { BoundedFifoMap, BoundedSet } from "./bounded-cache.js";
+import { emitBounded } from "./bounded-telemetry.js";
+import { freshnessFromMtime } from "./freshness.js";
+import { logLatency } from "./latency-logger.js";
+import { noteObservedClean, noteObservedMutation, noteObservedUnverifiable, shouldArmObservationForTool } from "./mutation-attribution.js";
+import { captureFileStatsForPaths, diffFileStats } from "./opaque-mutation-scan.js";
+import { normalizeMapKey } from "./path-utils.js";
+import { getProcessSingleton } from "./process-singletons.js";
+import { bounded } from "./deadline-utils.js";
+import { lineContentHash } from "./read-guard.js";
+const OBSERVED_CAPTURE_BUDGET_MS = 200;
+export const OBSERVED_TURN_BUDGET_MS = 600;
+const OBSERVED_SETTLE_DEADLINE_MS = 50;
+export const OBSERVED_TARGET_DIR_MAX_ENTRIES = 64;
+export const OBSERVED_TRACKED_MAX_FILES = 400;
+const OBSERVED_LEDGER_SETTLE_MS = 150;
+export const OBSERVED_HANDLED_MAX = 1000;
+export const OBSERVED_SWEEP_STAT_WINDOW = 128;
+const OBSERVED_HASH_BUDGET_BYTES = 2 * 1024 * 1024;
+export const OBSERVED_SWEEP_HASH_BUDGET_BYTES = 2 * 1024 * 1024;
+const OBSERVED_SWEEP_RANGE_BUDGET_BYTES = 1024 * 1024;
+const OBSERVED_LINE_HASH_MAX_BYTES = 512 * 1024;
+const OBSERVED_MAX_EDIT_RANGES = 32;
+const OBSERVED_PENDING_MAX = 32;
+const OBSERVED_LEDGER_MAX = 1000;
+const OBSERVED_FAMILY = "observed-mutation-net";
+const OBSERVED_VERSION = 3;
+function state() {
+  return getProcessSingleton(OBSERVED_FAMILY, OBSERVED_VERSION, () => ({
+    pending: new BoundedFifoMap(OBSERVED_PENDING_MAX),
+    ledger: new BoundedFifoMap(OBSERVED_LEDGER_MAX),
+    handled: new BoundedSet(OBSERVED_HANDLED_MAX),
+    turnIndex: -1,
+    turnSpentMs: 0,
+    sweepCursor: 0
+  }));
+}
+export function resetObservedMutationNet() {
+  const current = state();
+  current.pending.clear();
+  current.ledger.clear();
+  current.handled.clear();
+  current.turnIndex = -1;
+  current.turnSpentMs = 0;
+  current.sweepCursor = 0;
+}
+export function _observedMutationStateForTests() {
+  const current = state();
+  return {
+    pending: [...current.pending.keys()],
+    ledger: [...current.ledger.keys()],
+    handled: [...current.handled],
+    turnSpentMs: current.turnSpentMs,
+    sweepCursor: current.sweepCursor
+  };
+}
+export function noteMutationHandled(filePath) {
+  try {
+    const handled = state().handled;
+    const key = normalizeMapKey(path.resolve(filePath));
+    const evicted = handled.add(key);
+    for (const oldest of evicted) {
+      emitBounded("observed_handled_evicted", oldest, {
+        filePath: oldest,
+        durationMs: 0,
+        result: `cap:${OBSERVED_HANDLED_MAX}`
+      }, {
+        ledgerKind: "observed-mutation-budget",
+        reason: `the handled set is full at ${OBSERVED_HANDLED_MAX}; the oldest dm-lens-authored file lost its mark, so its next drift is reported as third-party`,
+        capPerTurn: { limit: 2, turnIndex: state().turnIndex }
+      });
+    }
+  } catch {}
+}
+export function hasPendingObservation(toolCallId) {
+  return toolCallId !== undefined && state().pending.has(toolCallId);
+}
+function remainingTurnBudgetMs(turnIndex) {
+  const current = state();
+  if (current.turnIndex !== turnIndex) {
+    current.turnIndex = turnIndex;
+    current.turnSpentMs = 0;
+  }
+  return Math.max(0, OBSERVED_TURN_BUDGET_MS - current.turnSpentMs);
+}
+function chargeTurnBudget(turnIndex, spentMs) {
+  const current = state();
+  if (current.turnIndex !== turnIndex) {
+    current.turnIndex = turnIndex;
+    current.turnSpentMs = 0;
+  }
+  current.turnSpentMs += Math.max(0, spentMs);
+}
+export function _setObservedTurnBudgetForTests(turnIndex, spentMs) {
+  const current = state();
+  current.turnIndex = turnIndex;
+  current.turnSpentMs = spentMs;
+}
+async function withBounds(work, timeoutMs, signal, site) {
+  const isAborted = () => signal !== undefined && signal.aborted;
+  if (isAborted())
+    return { ok: false, reason: "aborted" };
+  try {
+    const settled = await bounded(work(), {
+      ms: timeoutMs,
+      signal,
+      hook: site.hook,
+      label: site.label
+    });
+    if (settled !== undefined)
+      return { ok: true, value: settled };
+    return { ok: false, reason: isAborted() ? "aborted" : "timeout" };
+  } catch {
+    return { ok: false, reason: "failed" };
+  }
+}
+export const _withBoundsForTests = withBounds;
+function splitLines(text) {
+  return text.split(/\r?\n/);
+}
+async function captureLineHashes(filePath, budget) {
+  try {
+    const size = (await fs.promises.stat(filePath)).size;
+    if (size > OBSERVED_LINE_HASH_MAX_BYTES)
+      return;
+    if (budget) {
+      if (budget.remainingBytes < size)
+        return;
+      budget.remainingBytes -= size;
+    }
+    const lines = splitLines(await fs.promises.readFile(filePath, "utf-8"));
+    const hashes = new Map;
+    for (let index = 0;index < lines.length; index += 1) {
+      hashes.set(index + 1, lineContentHash(lines[index] ?? ""));
+    }
+    return hashes;
+  } catch {
+    return;
+  }
+}
+function denseLineBaseline(before) {
+  if (before === undefined)
+    return;
+  const entries = before instanceof Map ? [...before.entries()] : Object.entries(before).map(([line, hash]) => [Number(line), hash]);
+  const count = entries.length;
+  if (count === 0)
+    return;
+  const ordered = [];
+  ordered.length = count;
+  for (const [line, hash] of entries) {
+    if (!Number.isInteger(line) || line < 1 || line > count)
+      return;
+    ordered[line - 1] = hash;
+  }
+  for (const value of ordered)
+    if (value === undefined)
+      return;
+  return ordered;
+}
+export async function deriveObservedEditRanges(filePath, before, budget) {
+  const baseline = denseLineBaseline(before);
+  if (baseline === undefined)
+    return;
+  const after = await captureLineHashes(filePath, budget);
+  if (after === undefined)
+    return;
+  if (after.size !== baseline.length)
+    return;
+  const changed = [];
+  for (let line = 1;line <= baseline.length; line += 1) {
+    if (after.get(line) !== baseline[line - 1])
+      changed.push(line);
+  }
+  if (changed.length === 0)
+    return;
+  const ranges = [];
+  let start = changed[0];
+  let end = changed[0];
+  for (const line of changed.slice(1)) {
+    if (line === end + 1) {
+      end = line;
+      continue;
+    }
+    ranges.push([start, end]);
+    start = line;
+    end = line;
+  }
+  ranges.push([start, end]);
+  if (ranges.length > OBSERVED_MAX_EDIT_RANGES) {
+    return [[ranges[0][0], ranges[ranges.length - 1][1]]];
+  }
+  return ranges;
+}
+function boundingBox(ranges) {
+  return [
+    Math.min(...ranges.map(([start]) => start)),
+    Math.max(...ranges.map(([, end]) => end))
+  ];
+}
+function putPending(key, value) {
+  state().pending.set(key, value);
+}
+function putLedger(key, value) {
+  state().ledger.set(key, value);
+}
+function seedLedger(snapshot) {
+  const seenAtMs = Date.now();
+  for (const [key, entry] of snapshot) {
+    putLedger(key, {
+      hash: entry.hash,
+      hashKind: entry.hash === undefined ? undefined : "content",
+      size: entry.size,
+      mtimeMs: entry.mtimeMs,
+      seenAtMs
+    });
+  }
+}
+function linesDigest(ordered) {
+  return createHash("sha256").update(ordered.join(`
+`)).digest("hex");
+}
+function linesDigestOfContent(content) {
+  return linesDigest(splitLines(content).map((line) => lineContentHash(line)));
+}
+export async function armObservedMutation(args) {
+  if (!shouldArmObservationForTool(args.toolName))
+    return { armed: false, reason: "not-eligible" };
+  if (!args.toolCallId)
+    return { armed: false, reason: "no-tool-call-id" };
+  const remaining = remainingTurnBudgetMs(args.turnIndex);
+  if (remaining <= 0) {
+    emitBounded("observed_mutation_budget_exhausted", args.toolName, {
+      filePath: args.targetPath,
+      durationMs: 0,
+      result: `turn-budget:${OBSERVED_TURN_BUDGET_MS}ms`
+    }, {
+      ledgerKind: "observed-mutation-budget",
+      reason: "per-turn observational snapshot budget exhausted",
+      capPerTurn: { limit: 2, turnIndex: args.turnIndex }
+    });
+    return { armed: false, reason: "budget-exhausted" };
+  }
+  const started = Date.now();
+  const timeoutMs = Math.min(remaining, OBSERVED_CAPTURE_BUDGET_MS);
+  const outcome = await withBounds(async () => {
+    const universe = await collectObservationUniverse(args.targetPath);
+    const captured = await captureFileStatsForPaths(universe.paths, {
+      withHashes: true,
+      hashBudgetBytes: OBSERVED_HASH_BUDGET_BYTES
+    });
+    const lineHashes = await captureLineHashes(args.targetPath);
+    return {
+      paths: universe.paths,
+      capped: universe.capped,
+      stats: captured.snapshot,
+      lineHashes
+    };
+  }, timeoutMs, args.signal, { hook: "tool_call", label: "armObservedMutation" });
+  chargeTurnBudget(args.turnIndex, Date.now() - started);
+  if (!outcome.ok) {
+    emitBounded("observed_mutation_budget_exhausted", args.toolName, {
+      filePath: args.targetPath,
+      durationMs: Date.now() - started,
+      result: outcome.reason
+    }, {
+      ledgerKind: "observed-mutation-budget",
+      reason: `observational pre-snapshot ${outcome.reason}`,
+      capPerTurn: { limit: 2, turnIndex: args.turnIndex }
+    });
+    return { armed: false, reason: outcome.reason };
+  }
+  const targetKey = normalizeMapKey(path.resolve(args.targetPath));
+  seedLedger(outcome.value.stats);
+  if (outcome.value.capped) {
+    emitBounded("observed_target_dir_capped", args.toolName, {
+      filePath: args.targetPath,
+      durationMs: Date.now() - started,
+      result: `entries:${OBSERVED_TARGET_DIR_MAX_ENTRIES}`
+    }, {
+      ledgerKind: "observed-mutation-dir-cap",
+      reason: `directory target has more than ${OBSERVED_TARGET_DIR_MAX_ENTRIES} entries; the observation covers only the first ${OBSERVED_TARGET_DIR_MAX_ENTRIES}`,
+      capPerTurn: { limit: 2, turnIndex: args.turnIndex }
+    });
+  }
+  putPending(args.toolCallId, {
+    toolName: args.toolName,
+    startedAt: started,
+    cwd: args.cwd,
+    sessionGeneration: args.sessionGeneration,
+    paths: outcome.value.paths,
+    stats: outcome.value.stats,
+    targetKey,
+    targetLineHashes: outcome.value.lineHashes,
+    targetDirCapped: outcome.value.capped
+  });
+  const durationMs = Date.now() - started;
+  logLatency({
+    type: "phase",
+    toolName: args.toolName,
+    phase: "observed_mutation_prescan",
+    filePath: args.targetPath,
+    durationMs,
+    result: `scanned:${outcome.value.stats.size}`
+  });
+  return { armed: true, scannedCount: outcome.value.stats.size, durationMs };
+}
+async function collectObservationUniverse(targetPath) {
+  const target = path.resolve(targetPath);
+  try {
+    const stat = await fs.promises.stat(target);
+    if (stat.isDirectory()) {
+      const entries = await fs.promises.readdir(target, {
+        withFileTypes: true
+      });
+      const files = [];
+      let capped = false;
+      for (const entry of entries) {
+        if (files.length >= OBSERVED_TARGET_DIR_MAX_ENTRIES) {
+          capped = true;
+          break;
+        }
+        if (entry.isFile())
+          files.push(path.join(target, entry.name));
+      }
+      return { paths: files, capped };
+    }
+  } catch {}
+  return { paths: [target], capped: false };
+}
+export async function settleObservedMutation(args) {
+  const key = args.toolCallId;
+  if (!key)
+    return {
+      settled: false,
+      changedPaths: [],
+      unverifiablePaths: [],
+      replayed: 0,
+      scanned: 0,
+      stoppedEarly: false,
+      reason: "no-tool-call-id"
+    };
+  const pending = state().pending.get(key);
+  if (!pending) {
+    return {
+      settled: false,
+      changedPaths: [],
+      unverifiablePaths: [],
+      replayed: 0,
+      scanned: 0,
+      stoppedEarly: false,
+      reason: "no-pending-baseline"
+    };
+  }
+  state().pending.delete(key);
+  if (pending.sessionGeneration !== args.sessionGeneration) {
+    return {
+      settled: false,
+      changedPaths: [],
+      unverifiablePaths: [],
+      replayed: 0,
+      scanned: 0,
+      stoppedEarly: false,
+      reason: "session-generation-advanced"
+    };
+  }
+  const started = Date.now();
+  const capture = await withBounds(() => captureFileStatsForPaths(pending.paths, {
+    withHashes: true,
+    hashBudgetBytes: OBSERVED_HASH_BUDGET_BYTES,
+    deadlineMs: started + OBSERVED_SETTLE_DEADLINE_MS,
+    signal: args.signal
+  }), OBSERVED_SETTLE_DEADLINE_MS * 4, args.signal, { hook: "tool_result_edit", label: "settleObservedMutation" });
+  chargeTurnBudget(args.turnIndex, Date.now() - started);
+  if (!capture.ok) {
+    noteObservedUnverifiable(args.toolName);
+    return {
+      settled: false,
+      changedPaths: [],
+      unverifiablePaths: [],
+      replayed: 0,
+      scanned: 0,
+      stoppedEarly: true,
+      reason: capture.reason
+    };
+  }
+  const captured = capture.value;
+  seedLedger(captured.snapshot);
+  const diff = diffObservedStats(pending.stats, captured.snapshot);
+  const changed = diff.changed.filter((candidate) => args.isRecordable?.(candidate) !== false);
+  const unverifiablePaths = diff.unverifiable.filter((candidate) => args.isRecordable?.(candidate) !== false);
+  const truncated = pending.targetDirCapped || captured.stoppedEarly;
+  const cutReason = pending.targetDirCapped ? "target-dir-cap-exceeded" : captured.stoppedEarly ? "capture-cut-short" : undefined;
+  if (unverifiablePaths.length > 0) {
+    noteObservedUnverifiable(args.toolName);
+    logLatency({
+      type: "phase",
+      toolName: args.toolName,
+      phase: "observed_mutation_coverage_unknown",
+      filePath: unverifiablePaths.slice(0, 5).join(","),
+      durationMs: Date.now() - started,
+      result: `unverifiable:${unverifiablePaths.length}`
+    });
+  }
+  if (changed.length === 0) {
+    if (truncated)
+      noteObservedUnverifiable(args.toolName);
+    else if (unverifiablePaths.length === 0)
+      noteObservedClean(args.toolName);
+    return {
+      settled: true,
+      changedPaths: [],
+      unverifiablePaths,
+      replayed: 0,
+      scanned: captured.snapshot.size,
+      stoppedEarly: truncated,
+      reason: cutReason
+    };
+  }
+  const rangeBudget = {
+    remainingBytes: OBSERVED_HASH_BUDGET_BYTES
+  };
+  let replayed = 0;
+  for (const filePath of changed) {
+    const baseline = filePath === pending.targetKey ? pending.targetLineHashes : args.getStoredLineHashes?.(filePath);
+    const editRanges = await deriveObservedEditRanges(filePath, baseline, rangeBudget);
+    const accepted = args.record({
+      filePath,
+      kind: "edit",
+      touchedLines: editRanges ? boundingBox(editRanges) : undefined,
+      editRanges: editRanges && editRanges.length > 1 ? editRanges : undefined,
+      consumer: args.toolName,
+      provenance: "observed"
+    });
+    if (accepted) {
+      replayed += 1;
+      noteMutationHandled(filePath);
+    }
+  }
+  if (replayed > 0) {
+    const attribution = noteObservedMutation(args.toolName, pending.cwd);
+    logLatency({
+      type: "phase",
+      toolName: args.toolName,
+      phase: "observed_mutation_recovered",
+      filePath: changed.slice(0, 5).join(","),
+      durationMs: Date.now() - started,
+      result: `changed:${changed.length} observations:${attribution.observations}${attribution.persisted ? " persisted" : ""}`
+    });
+  } else {
+    logLatency({
+      type: "phase",
+      toolName: args.toolName,
+      phase: "observed_mutation_coverage_unknown",
+      filePath: changed.slice(0, 5).join(","),
+      durationMs: Date.now() - started,
+      result: `refused:${changed.length}`
+    });
+  }
+  return {
+    settled: true,
+    changedPaths: changed,
+    unverifiablePaths,
+    replayed,
+    scanned: captured.snapshot.size,
+    stoppedEarly: truncated,
+    reason: cutReason
+  };
+}
+function diffObservedStats(before, after) {
+  const changed = new Set(diffFileStats(before, after));
+  const unverifiable = new Set;
+  for (const [key, stat] of after) {
+    const previous = before.get(key);
+    if (previous && (previous.hash === undefined || stat.hash === undefined)) {
+      changed.delete(key);
+      unverifiable.add(key);
+    }
+  }
+  return { changed: [...changed], unverifiable: [...unverifiable] };
+}
+async function readBytesSafe(filePath) {
+  try {
+    return await fs.promises.readFile(filePath);
+  } catch {
+    return;
+  }
+}
+async function scanTrackedIncrementally(args, options) {
+  const current = state();
+  let tracked;
+  if (options.report) {
+    try {
+      tracked = (args.getTrackedPaths?.() ?? []).slice(0, OBSERVED_TRACKED_MAX_FILES);
+    } catch {
+      tracked = [];
+    }
+  } else {
+    tracked = [...current.handled];
+  }
+  const total = tracked.length;
+  if (total === 0) {
+    current.sweepCursor = 0;
+    return {
+      scanned: 0,
+      tracked: 0,
+      cursor: 0,
+      drifted: [],
+      unverifiable: [],
+      stoppedEarly: false
+    };
+  }
+  const startCursor = options.report ? (current.sweepCursor % total + total) % total : 0;
+  const window = options.report ? Math.min(OBSERVED_SWEEP_STAT_WINDOW, total) : total;
+  let hashBytesLeft = OBSERVED_SWEEP_HASH_BUDGET_BYTES;
+  const drifted = [];
+  const unverifiable = [];
+  let scanned = 0;
+  let stoppedEarly = false;
+  let steps = 0;
+  const rebaseline = (ledgerKey, entry) => {
+    putLedger(ledgerKey, entry);
+    if (!options.report)
+      current.handled.delete(ledgerKey);
+  };
+  for (;steps < window; steps += 1) {
+    if (args.signal?.aborted === true) {
+      stoppedEarly = true;
+      break;
+    }
+    if (Date.now() >= options.deadlineMs) {
+      stoppedEarly = true;
+      break;
+    }
+    const filePath = tracked[(startCursor + steps) % total];
+    let key;
+    try {
+      key = normalizeMapKey(path.resolve(filePath));
+    } catch {
+      continue;
+    }
+    let stat;
+    try {
+      stat = await fs.promises.stat(filePath);
+    } catch {
+      scanned += 1;
+      continue;
+    }
+    if (!stat.isFile()) {
+      scanned += 1;
+      continue;
+    }
+    scanned += 1;
+    const previous = current.ledger.get(key);
+    const next = {
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      hash: previous?.hash,
+      hashKind: previous?.hashKind,
+      seenAtMs: Date.now()
+    };
+    if (previous === undefined) {
+      const dense = denseLineBaseline(args.getStoredLineHashes?.(key));
+      if (dense) {
+        next.hash = linesDigest(dense);
+        next.hashKind = "lines";
+      } else if (stat.size <= hashBytesLeft) {
+        const content = await readBytesSafe(filePath);
+        if (content !== undefined) {
+          hashBytesLeft -= stat.size;
+          next.hash = createHash("sha256").update(content).digest("hex");
+          next.hashKind = "content";
+        }
+      }
+      rebaseline(key, next);
+      continue;
+    }
+    const baselineSettled = freshnessFromMtime({
+      mtimeMs: stat.mtimeMs,
+      referenceMs: previous.seenAtMs - OBSERVED_LEDGER_SETTLE_MS,
+      toleranceMs: 0
+    }).verdict === "fresh";
+    if (previous.size === stat.size && previous.mtimeMs === stat.mtimeMs && baselineSettled) {
+      rebaseline(key, next);
+      continue;
+    }
+    const sizeChanged = previous.size !== stat.size;
+    let verdict = sizeChanged ? "drift" : "unverifiable";
+    if (stat.size <= hashBytesLeft) {
+      const content = await readBytesSafe(filePath);
+      if (content !== undefined) {
+        hashBytesLeft -= stat.size;
+        const contentHash = createHash("sha256").update(content).digest("hex");
+        if (previous.hash === undefined) {
+          verdict = sizeChanged ? "drift" : "unverifiable";
+        } else if (previous.hashKind === "lines") {
+          verdict = linesDigestOfContent(content.toString("utf-8")) !== previous.hash ? "drift" : "clean";
+        } else {
+          verdict = contentHash !== previous.hash ? "drift" : "clean";
+        }
+        next.hash = contentHash;
+        next.hashKind = "content";
+      }
+    }
+    rebaseline(key, next);
+    if (!options.report)
+      continue;
+    if (current.handled.has(key))
+      continue;
+    if (args.isRecordable?.(key) === false)
+      continue;
+    if (verdict === "drift")
+      drifted.push(key);
+    else if (verdict === "unverifiable")
+      unverifiable.push(key);
+  }
+  if (options.report)
+    current.sweepCursor = (startCursor + steps) % total;
+  return {
+    scanned,
+    tracked: total,
+    cursor: options.report ? current.sweepCursor : 0,
+    drifted,
+    unverifiable,
+    stoppedEarly
+  };
+}
+export async function runObservedSettledSweep(args) {
+  const started = Date.now();
+  const outcome = await withBounds(() => scanTrackedIncrementally(args, {
+    report: true,
+    deadlineMs: started + OBSERVED_CAPTURE_BUDGET_MS
+  }), OBSERVED_CAPTURE_BUDGET_MS * 2, args.signal, { hook: "agent_settled", label: "runObservedSettledSweep" });
+  if (!outcome.ok) {
+    emitBounded("observed_sweep_skipped_budget", "settled-sweep", { durationMs: Date.now() - started, result: outcome.reason }, {
+      ledgerKind: "observed-mutation-budget",
+      reason: `settled sweep ${outcome.reason}`,
+      capPerTurn: { limit: 2, turnIndex: args.turnIndex }
+    });
+    return {
+      scanned: 0,
+      notReachedThisPass: 0,
+      cursor: state().sweepCursor,
+      drifted: [],
+      unverifiable: [],
+      replayed: 0,
+      reason: outcome.reason
+    };
+  }
+  const scan = outcome.value;
+  const rangeBudget = {
+    remainingBytes: OBSERVED_SWEEP_RANGE_BUDGET_BYTES
+  };
+  let replayed = 0;
+  for (const filePath of scan.drifted) {
+    if (args.signal?.aborted === true)
+      break;
+    const editRanges = await deriveObservedEditRanges(filePath, args.getStoredLineHashes?.(filePath), rangeBudget);
+    const accepted = args.record({
+      filePath,
+      kind: "edit",
+      touchedLines: editRanges ? boundingBox(editRanges) : undefined,
+      editRanges: editRanges && editRanges.length > 1 ? editRanges : undefined,
+      consumer: "settled-sweep",
+      provenance: "settled-sweep"
+    });
+    if (accepted)
+      replayed += 1;
+  }
+  const notReachedThisPass = Math.max(0, scan.tracked - scan.scanned);
+  if (scan.drifted.length > 0 || scan.unverifiable.length > 0) {
+    logLatency({
+      type: "phase",
+      phase: "observed_settled_sweep_drift",
+      filePath: scan.drifted.slice(0, 5).join(","),
+      durationMs: Date.now() - started,
+      result: `drifted:${scan.drifted.length} replayed:${replayed} unverifiable:${scan.unverifiable.length} scanned:${scan.scanned}/${scan.tracked} cursor:${scan.cursor}`
+    });
+  }
+  if (scan.unverifiable.length > 0) {
+    emitBounded("observed_sweep_unverifiable", "settled-sweep", {
+      durationMs: Date.now() - started,
+      result: `unverifiable:${scan.unverifiable.length}`,
+      filePath: scan.unverifiable.slice(0, 5).join(",")
+    }, {
+      ledgerKind: "observed-mutation-budget",
+      reason: "tracked file's size/mtime moved but no hashed baseline could confirm a content change",
+      capPerTurn: { limit: 2, turnIndex: args.turnIndex }
+    });
+  }
+  return {
+    scanned: scan.scanned,
+    notReachedThisPass,
+    cursor: scan.cursor,
+    drifted: scan.drifted,
+    unverifiable: scan.unverifiable,
+    replayed,
+    reason: scan.stoppedEarly ? "window-parked" : undefined
+  };
+}
+export async function refreshObservedMutationLedger(args) {
+  const outcome = await withBounds(() => scanTrackedIncrementally(args, {
+    report: false,
+    deadlineMs: Date.now() + OBSERVED_CAPTURE_BUDGET_MS
+  }), OBSERVED_CAPTURE_BUDGET_MS * 2, args.signal, { hook: "agent_settled", label: "refreshObservedMutationLedger" });
+  return outcome.ok ? outcome.value.scanned : 0;
+}