@duckmind/dm-darwin-x64 0.66.4 → 0.66.6

package/extensions/dm-lens/dist/clients/runtime-tool-call.js

@@ -0,0 +1,935 @@
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { loadBootstrapClients, requestBootstrapClients } from "./bootstrap.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { detectFileKind } from "./file-kinds.js";
+import { isPathIgnoredByProject } from "./file-utils.js";
+import { evaluateGitGuard, isGitCommitOrPushAttempt } from "./git-guard.js";
+import { dropHashlineAnchorMemo } from "./hashline-anchor.js";
+import { evaluateSharedCheckoutGuard } from "./shared-checkout-guard.js";
+import { logLatency } from "./latency-logger.js";
+import { toPosix } from "./path-utils.js";
+import { captureFileStats, getOpaqueBaselineStore, isGitWorktree, opaqueBaselineSlot } from "./opaque-mutation-scan.js";
+import { normalizeForGuardMatch } from "./host-edit-normalize.js";
+import { retargetReplacementIndentation } from "./indent-retarget.js";
+import { expectationFromToolInput, noteAgentCallEnd, noteAgentCallStart } from "./fix-run-restore.js";
+import { LANGUAGE_POLICY } from "./language-policy.js";
+import { isComplexitySupportedFile } from "./tree-sitter-shared.js";
+import { classifyMutatingTool, readMutationPathField } from "./mutating-tool.js";
+import { isProvisionalLearnedAttribution } from "./mutation-attribution.js";
+import { armObservedMutation } from "./observed-mutation.js";
+import { extractWrittenPathsFromCommand } from "./bash-file-access.js";
+import { getLSPService } from "./lsp/capabilities.js";
+import { findDocumentSymbolAtLine, getOpenDocumentSymbols, lspSymbolKindName, qualifiedLspSymbolName } from "./lsp-document-symbols.js";
+import { computeTrailingWhitespaceOldTextPatch, findUniqueMatchLineRange } from "./oldtext-autopatch.js";
+import { applyPartiallyApplicableEdits } from "./partial-edit-apply.js";
+import { isExternalOrVendorFile, resolveHostPathVariants, resolveHostToolPath } from "./path-utils.js";
+import { EXPANSION_BUDGET_MS, EXPANSION_LIMIT_LINES, tryExpandRead } from "./read-expansion.js";
+import { boundedIndexesForCount, createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent } from "./read-guard-logger.js";
+import { countFileLines, formatAlreadyAppliedNotes, getTouchedLinesForGuard, relocateEditRange, tryCorrectIndentationMismatch, tryCorrectIndentationMismatchFromContent } from "./read-guard-tool-lines.js";
+import { handleToolResult } from "./runtime-tool-result.js";
+import { resolveReadEvidenceCorrelationId, resolveToolCallCorrelationId } from "./tool-event.js";
+import { getSharedTreeSitterClient } from "./tree-sitter-shared.js";
+const LSP_TOOLCALL_NAV_TOUCH_BUDGET_MS = Math.max(0, Number.parseInt(process.env.DM_LENS_TOOLCALL_NAV_TOUCH_MS ?? process.env.DM_LENS_LSP_NAV_CLIENT_WAIT_MS ?? "1500", 10) || 1500);
+const LSP_TOOLCALL_TOUCH_BUDGET_MS = Math.max(0, Number.parseInt(process.env.DM_LENS_TOOLCALL_TOUCH_MS ?? "750", 10) || 750);
+function composePartialApplyReason(args) {
+  const parts = [];
+  const editSuffix = args.appliedCount === 1 ? "" : "s";
+  parts.push(args.postEditStatus === "failed" ? `⚠️ PARTIAL APPLY — ${args.appliedCount} edit${editSuffix} committed (${args.appliedIndices}). Post-edit analysis failed after the commit; the committed bytes stand and were not reverted. Do NOT resubmit the applied edits.` : `⚠️ PARTIAL APPLY — ${args.appliedCount} edit${editSuffix} committed (${args.appliedIndices}). Do NOT resubmit the applied edits.`);
+  if (args.preflightDetails && args.preflightDetails.length > 0) {
+    parts.push(args.preflightDetails.join(`
+
+`));
+  }
+  const alreadyNotes = formatAlreadyAppliedNotes(args.alreadyAppliedEdits);
+  if (alreadyNotes)
+    parts.push(alreadyNotes.trimStart());
+  if (args.postEditOutput && args.postEditStatus === "succeeded") {
+    parts.push(`Post-apply analysis:
+${args.postEditOutput}`);
+  }
+  return parts.join(`
+
+`);
+}
+function getToolCallRawFilePath(toolName, event) {
+  const inputObj = event.input ?? {};
+  const mutation = classifyMutatingTool({ ...event, toolName });
+  if (mutation)
+    return mutation.path;
+  if (toolName === "read") {
+    if (typeof inputObj.path === "string")
+      return inputObj.path;
+    if (typeof inputObj.filePath === "string")
+      return inputObj.filePath;
+    return;
+  }
+  if (toolName === "lsp_navigation") {
+    return typeof inputObj.filePath === "string" ? inputObj.filePath : undefined;
+  }
+  return;
+}
+function retireAstGrepApplyTargets(toolName, event, runtime, ctx) {
+  const input = event.input ?? {};
+  if (toolName !== "ast_grep_replace" || input.apply !== true)
+    return;
+  if (!Array.isArray(input.paths))
+    return;
+  const checked = [];
+  for (const rawPath of input.paths) {
+    if (typeof rawPath !== "string")
+      continue;
+    const resolved = resolveToolCallFilePath(rawPath, ctx.cwd, runtime.projectRoot)?.path;
+    if (!resolved)
+      continue;
+    runtime.readGuard?.retireChangedAuthorship?.(resolved);
+    checked.push(resolved);
+  }
+  runtime.readGuard?.noteCheckedPaths?.(resolveToolCallCorrelationId(event), checked);
+}
+function resolveToolCallFilePath(rawFilePath, cwd, projectRoot) {
+  if (!rawFilePath)
+    return;
+  return resolveHostPathVariants(resolveHostToolPath(rawFilePath, cwd ?? projectRoot));
+}
+function getReadToolInput(toolName, input) {
+  if (toolName !== "read")
+    return;
+  return input;
+}
+function getEffectiveReadLimit(filePath, readInput) {
+  if (!filePath || !readInput)
+    return;
+  const requestedOffset = Math.max(1, readInput.offset ?? 1);
+  const requestedLimit = readInput.limit;
+  return requestedLimit ?? Math.max(1, countFileLines(filePath) - requestedOffset + 1);
+}
+function isLspCapableFile(filePath) {
+  const kind = detectFileKind(filePath);
+  if (!kind)
+    return false;
+  return LANGUAGE_POLICY[kind]?.lspCapable !== false;
+}
+function shouldSkipLspAutoTouch(filePath, projectRoot) {
+  const normalized = toPosix(path.resolve(filePath)).toLowerCase();
+  const base = path.basename(filePath).toLowerCase();
+  if (normalized.includes("/.dm-lens/"))
+    return true;
+  if (normalized.includes("/.harness/"))
+    return true;
+  if (isExternalOrVendorFile(filePath, projectRoot))
+    return true;
+  if (base === "stdout.jsonl" || base === "stderr.txt" || base === "prompt.txt") {
+    return true;
+  }
+  if (base === "case.json" && normalized.includes("/cases/")) {
+    return true;
+  }
+  return false;
+}
+function normalizeOldTextForMatch(text) {
+  return normalizeForGuardMatch(text);
+}
+function countTextOccurrences(haystack, needle) {
+  if (!needle)
+    return 0;
+  let count = 0;
+  let pos = 0;
+  while (pos < haystack.length) {
+    const idx = haystack.indexOf(needle, pos);
+    if (idx === -1)
+      break;
+    count += 1;
+    pos = idx + needle.length;
+  }
+  return count;
+}
+function countOldTextMatches(filePath, oldText, cachedNormalizedContent) {
+  try {
+    const content = cachedNormalizedContent ?? normalizeOldTextForMatch(nodeFs.readFileSync(filePath, "utf-8"));
+    return countTextOccurrences(content, normalizeOldTextForMatch(oldText));
+  } catch {
+    return 0;
+  }
+}
+function isIndentationOnlyChange(before, after) {
+  const beforeLines = before.replace(/\r\n/g, `
+`).split(`
+`);
+  const afterLines = after.replace(/\r\n/g, `
+`).split(`
+`);
+  if (beforeLines.length !== afterLines.length)
+    return false;
+  return beforeLines.every((line, index) => line.trim() === afterLines[index].trim());
+}
+function getNewContentFromToolCall(event) {
+  const mutation = classifyMutatingTool(event);
+  if (mutation?.kind === "write") {
+    return event.input.content;
+  }
+  if (mutation?.kind === "edit") {
+    const edits = event.input.edits;
+    return edits?.map((edit) => edit.newText ?? "").join(`
+`);
+  }
+  return;
+}
+export async function handleToolCall(deps) {
+  try {
+    const result = await handleToolCallImpl(deps);
+    if (result && result.block) {
+      try {
+        const toolCallId = resolveToolCallCorrelationId(deps.event);
+        if (toolCallId !== undefined) {
+          deps.runtime.takeToolCallAttribution(toolCallId);
+        }
+        noteAgentCallEnd(toolCallId);
+      } catch (cleanupError) {
+        const reason = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        recordDegradationOnce({
+          kind: "tool-call-handler-throw",
+          subject: `attribution-cleanup:${deps.event?.toolName ?? "unknown"}`,
+          reason
+        });
+        try {
+          deps.dbg?.(`tool_call blocked-attribution cleanup threw (block verdict preserved): ${reason}`);
+        } catch {}
+      }
+    }
+    return result;
+  } catch (error) {
+    const toolName = deps.event?.toolName ?? "unknown";
+    const reason = error instanceof Error ? error.message : String(error);
+    recordDegradationOnce({
+      kind: "tool-call-handler-throw",
+      subject: toolName,
+      reason
+    });
+    try {
+      deps.dbg?.(`tool_call handler threw for ${toolName} (degraded, not blocking): ${reason}`);
+      if (error instanceof Error && error.stack) {
+        deps.dbg?.(`tool_call handler stack: ${error.stack}`);
+      }
+    } catch {}
+    return;
+  }
+}
+async function handleToolCallImpl(deps) {
+  const { event, ctx, lensEnabled, getFlag, dbg, runtime, cacheManager, ensureLSPConfigInitialized, updateLspStatus, resetLSPService, getTreeSitterClient = getSharedTreeSitterClient } = deps;
+  dropHashlineAnchorMemo();
+  const readGuardCorrelationId = getReadGuardCorrelationId(event);
+  let filePath;
+  const logToolReadGuardEvent = (entry) => logReadGuardEvent({ ...entry, correlationId: readGuardCorrelationId });
+  const toolName = event.toolName ?? "";
+  const mutation = classifyMutatingTool(event);
+  const editInputForTelemetry = event.input;
+  const requestedEditIndexes = mutation?.kind === "write" ? [0] : Array.isArray(editInputForTelemetry?.edits) ? boundedIndexesForCount(editInputForTelemetry.edits.length) : [0];
+  const requestedEditTotal = mutation?.kind === "write" ? 1 : Array.isArray(editInputForTelemetry?.edits) ? editInputForTelemetry.edits.length : 1;
+  const logBlockedEditSummary = (source) => logToolReadGuardEvent({
+    event: "edit_batch_summary",
+    filePath: filePath ?? "",
+    metadata: {
+      tool: toolName,
+      source,
+      editBatchSummary: createReadGuardEditBatchSummary({
+        requestedIndexes: requestedEditIndexes,
+        requestedTotal: requestedEditTotal,
+        rejectedReasons: requestedEditIndexes.map((index) => ({
+          index,
+          code: "preflight_blocked"
+        })),
+        rejectedTotal: requestedEditTotal,
+        terminalStatus: "blocked"
+      })
+    }
+  });
+  if (!lensEnabled)
+    return;
+  if (toolName === "bash") {
+    const commandInput = event.input;
+    if (typeof commandInput?.command === "string" && !getFlag("no-read-guard"))
+      for (const target of extractWrittenPathsFromCommand(commandInput.command, runtime.projectRoot || process.cwd()))
+        runtime.readGuard?.retireChangedAuthorship?.(target);
+    if (typeof commandInput?.command === "string" && commandInput.command) {
+      const scanRoot = ctx.cwd ?? runtime.projectRoot;
+      if (scanRoot) {
+        const started = Date.now();
+        const baselineSlot = opaqueBaselineSlot(scanRoot, runtime.sessionGeneration);
+        let baseline;
+        let resultNote;
+        if (await isGitWorktree(scanRoot)) {
+          baseline = { startedAt: started, strategy: "git" };
+          resultNote = "git";
+        } else {
+          const outcome = await captureFileStats(scanRoot, {
+            withHashes: true
+          });
+          baseline = outcome.snapshot ? {
+            startedAt: started,
+            strategy: "stat-diff",
+            stats: outcome.snapshot
+          } : {
+            startedAt: started,
+            strategy: "stat-diff",
+            statsUnknownReason: outcome.unknownReason ?? "walk-failed"
+          };
+          resultNote = outcome.unknownReason ?? `scanned:${outcome.scannedCount}`;
+        }
+        getOpaqueBaselineStore().record(baselineSlot, resolveToolCallCorrelationId(event), baseline, {
+          key: runtime.turnKey(deps.sessionId),
+          isLive: (key) => runtime.isLiveTurnKey(key)
+        });
+        logLatency({
+          type: "phase",
+          phase: "opaque_mutation_prescan",
+          filePath: commandInput.command.slice(0, 80),
+          durationMs: Date.now() - started,
+          result: resultNote
+        });
+      }
+    }
+  }
+  if ((mutation === undefined || isProvisionalLearnedAttribution(toolName)) && toolName !== "bash" && !getFlag("no-read-guard")) {
+    const observedRawPath = readMutationPathField(event);
+    const observedPath = observedRawPath ? resolveToolCallFilePath(observedRawPath, ctx.cwd, runtime.projectRoot)?.path : undefined;
+    if (observedPath) {
+      const observedCallId = resolveToolCallCorrelationId(event);
+      const retire = (target) => {
+        runtime.readGuard?.retireChangedAuthorship?.(target);
+      };
+      retire(observedPath);
+      runtime.readGuard?.noteCheckedPaths?.(observedCallId, [observedPath]);
+      await armObservedMutation({
+        toolCallId: observedCallId,
+        toolName,
+        targetPath: observedPath,
+        cwd: ctx.cwd ?? runtime.projectRoot,
+        sessionGeneration: runtime.sessionGeneration,
+        turnIndex: runtime.turnKey(deps.sessionId),
+        isLiveTurn: (key) => runtime.isLiveTurnKey(key),
+        onUniverse: (paths) => {
+          paths.forEach(retire);
+          runtime.readGuard?.noteCheckedPaths?.(observedCallId, paths);
+        },
+        signal: ctx.signal,
+        dbg
+      });
+    }
+  }
+  retireAstGrepApplyTargets(toolName, event, runtime, ctx);
+  if (getFlag("lens-guard") && isGitCommitOrPushAttempt(toolName, event.input)) {
+    const guard = evaluateGitGuard(runtime, cacheManager, ctx.cwd ?? runtime.projectRoot, ctx.host ?? "pi");
+    if (guard.block) {
+      return {
+        block: true,
+        reason: guard.reason
+      };
+    }
+  }
+  if (getFlag("lens-checkout-guard")) {
+    const sharedCheckout = await evaluateSharedCheckoutGuard(toolName, event.input, ctx.cwd ?? runtime.projectRoot ?? process.cwd());
+    if (sharedCheckout.block) {
+      return {
+        block: true,
+        reason: sharedCheckout.reason
+      };
+    }
+  }
+  const rawFilePath = getToolCallRawFilePath(toolName, event);
+  const pathResolution = resolveToolCallFilePath(rawFilePath, ctx.cwd, runtime.projectRoot);
+  filePath = pathResolution?.path;
+  if (pathResolution?.variant) {
+    dbg(`tool_call: path resolved via host ${pathResolution.variant} variant → ${filePath}`);
+  }
+  if (!getFlag("no-lsp")) {
+    try {
+      const configCwd = filePath ? path.dirname(filePath) : ctx.cwd ?? runtime.projectRoot ?? process.cwd();
+      await ensureLSPConfigInitialized(configCwd);
+    } catch (cfgErr) {
+      dbg(`lsp config init failed during tool_call: ${cfgErr}`);
+    }
+  }
+  if (!filePath)
+    return;
+  dbg(`tool_call fired for: ${filePath} (exists: ${nodeFs.existsSync(filePath)})`);
+  const toolCallId = resolveToolCallCorrelationId(event);
+  const attributesMutationTarget = toolCallId !== undefined && (mutation !== undefined || toolName === "read");
+  const targetMissing = !nodeFs.existsSync(filePath);
+  const targetIgnored = isPathIgnoredByProject(filePath, runtime.projectRoot, false);
+  if (attributesMutationTarget) {
+    runtime.recordToolCallAttribution(toolCallId, {
+      resolvedPath: filePath,
+      skipped: targetIgnored,
+      originCwd: ctx.cwd ?? runtime.projectRoot
+    });
+    if (mutation !== undefined)
+      noteAgentCallStart(toolCallId, filePath, expectationFromToolInput(event.input, mutation.kind));
+  }
+  if (targetMissing) {
+    if (mutation?.kind !== "write" && pathResolution?.unresolved) {
+      const tried = pathResolution.triedVariants.length > 0 ? `tried ${pathResolution.triedVariants.join(", ")}` : "no variant differed from the resolved path";
+      recordDegradationOnce({
+        kind: "path-variant-unresolved",
+        subject: filePath,
+        reason: `${toolName}: no file at the resolved path, and none of pi's variants matched (${tried})`
+      });
+    }
+    return;
+  }
+  if (targetIgnored) {
+    dbg(`tool_call: skipping gitignored file ${filePath}`);
+    return;
+  }
+  const isExternalOrVendor = isExternalOrVendorFile(filePath, runtime.projectRoot);
+  const lspCapableFile = isLspCapableFile(filePath);
+  const lspAutoTouchSkipped = shouldSkipLspAutoTouch(filePath, runtime.projectRoot);
+  const lspAutoTouchEligible = lspCapableFile && !lspAutoTouchSkipped;
+  const shouldWarmReadLsp = toolName === "read" && lspAutoTouchEligible && runtime.shouldWarmLspOnRead(filePath);
+  const shouldAutoTouch = (mutation !== undefined || toolName === "lsp_navigation" || shouldWarmReadLsp) && !getFlag("no-lsp") && lspAutoTouchEligible;
+  if (!lspCapableFile && !getFlag("no-lsp")) {
+    dbg(`lsp auto-touch skipped: ${path.basename(filePath)} (file kind not LSP-capable)`);
+  } else if (lspAutoTouchSkipped && !getFlag("no-lsp")) {
+    dbg(`lsp auto-touch skipped: ${path.basename(filePath)} (internal/support artifact)`);
+  }
+  if (toolName === "read" && !getFlag("no-lsp") && !shouldWarmReadLsp) {
+    const readSkipReason = !lspAutoTouchEligible ? "file not eligible for LSP warm" : "already warming or warmed recently";
+    dbg(`lsp read warm skipped: ${path.basename(filePath)} (${readSkipReason})`);
+  }
+  if (shouldAutoTouch) {
+    try {
+      const readStamp = performance.now();
+      const fileContent = nodeFs.readFileSync(filePath, "utf-8");
+      const maxClientWaitMs = toolName === "lsp_navigation" ? LSP_TOOLCALL_NAV_TOUCH_BUDGET_MS : LSP_TOOLCALL_TOUCH_BUDGET_MS;
+      if (toolName === "read") {
+        runtime.markLspReadWarmStarted(filePath);
+        dbg(`lsp read warm started: ${path.basename(filePath)}`);
+      }
+      getLSPService().touchFile(filePath, fileContent, {
+        diagnostics: "none",
+        source: `tool_call:${toolName}`,
+        clientScope: "primary",
+        maxClientWaitMs,
+        readStamp
+      }).then((result) => {
+        if (toolName === "read") {
+          if (result === undefined) {
+            runtime.clearLspReadWarmState(filePath);
+            dbg(`lsp read warm unavailable: ${path.basename(filePath)} (no LSP client ready)`);
+          } else {
+            runtime.markLspReadWarmCompleted(filePath);
+            dbg(`lsp read warm completed: ${path.basename(filePath)}`);
+          }
+        }
+        if (ctx.ui) {
+          updateLspStatus(ctx.ui.setStatus, ctx.ui.theme);
+        }
+      }).catch((err) => {
+        if (toolName === "read") {
+          runtime.clearLspReadWarmState(filePath);
+        }
+        dbg(`lsp auto-touch failed for ${filePath}: ${err}`);
+      });
+    } catch {
+      if (toolName === "read") {
+        runtime.clearLspReadWarmState(filePath);
+      }
+    }
+  }
+  const readInput = getReadToolInput(toolName, event.input);
+  const requestedReadOffset = Math.max(1, readInput?.offset ?? 1);
+  const requestedReadLimit = readInput?.limit;
+  let effectiveReadOffset = requestedReadOffset;
+  let effectiveReadLimit = getEffectiveReadLimit(filePath, readInput);
+  let enclosingSymbol;
+  if (toolName === "read" && toolCallId !== undefined)
+    runtime.takeReadWidening(toolCallId);
+  const readExpansionClient = toolName === "read" && !getFlag("no-lsp") && !getFlag("no-read-guard") && !isExternalOrVendor && filePath && readInput && requestedReadLimit != null && requestedReadLimit <= EXPANSION_LIMIT_LINES ? getTreeSitterClient() : null;
+  if (readExpansionClient && filePath && readInput && requestedReadLimit != null) {
+    const totalLines = effectiveReadLimit != null && requestedReadLimit == null ? effectiveReadLimit : countFileLines(filePath);
+    try {
+      const expansion = await tryExpandRead(filePath, requestedReadOffset, requestedReadLimit, totalLines, readExpansionClient);
+      if (expansion) {
+        readInput.offset = expansion.newOffset;
+        readInput.limit = expansion.newLimit;
+        effectiveReadOffset = expansion.newOffset;
+        effectiveReadLimit = expansion.newLimit;
+        let enriched = false;
+        let enrichedAncestry = expansion.ancestry;
+        const lspSymbols = await getOpenDocumentSymbols(filePath);
+        const located = lspSymbols ? findDocumentSymbolAtLine(lspSymbols, expansion.enclosingSymbol.startLine) : undefined;
+        if (located) {
+          enclosingSymbol = {
+            ...expansion.enclosingSymbol,
+            name: qualifiedLspSymbolName(located, lspSymbols),
+            kind: lspSymbolKindName(located.symbol.kind)
+          };
+          if (located.ancestry.length > 0) {
+            enrichedAncestry = located.ancestry.map((entry) => ({
+              name: entry.name,
+              kind: lspSymbolKindName(entry.kind),
+              startLine: ((entry.range ?? entry.location?.range)?.start.line ?? 0) + 1,
+              endLine: ((entry.range ?? entry.location?.range)?.end.line ?? 0) + 1
+            }));
+          }
+          enriched = true;
+        } else {
+          enclosingSymbol = expansion.enclosingSymbol;
+        }
+        if (toolCallId !== undefined) {
+          runtime.recordReadWidening(toolCallId, {
+            filePath,
+            inputPath: rawFilePath,
+            requested: {
+              offset: requestedReadOffset,
+              limit: requestedReadLimit
+            },
+            shown: { offset: expansion.newOffset, limit: expansion.newLimit },
+            boundary: expansion.enclosingSymbol.kind === "markdown_section" ? { heading: expansion.enclosingSymbol.name } : { symbol: enclosingSymbol }
+          });
+        }
+        logToolReadGuardEvent({
+          event: "ts_range_expanded",
+          sessionId: runtime.telemetrySessionId,
+          filePath,
+          requestedOffset: requestedReadOffset,
+          requestedLimit: requestedReadLimit,
+          effectiveOffset: expansion.newOffset,
+          effectiveLimit: expansion.newLimit,
+          symbol: enclosingSymbol.name,
+          symbolKind: enclosingSymbol.kind,
+          symbolStartLine: expansion.enclosingSymbol.startLine,
+          symbolEndLine: expansion.enclosingSymbol.endLine,
+          metadata: {
+            enriched,
+            durationMs: expansion.durationMs,
+            budgetMs: EXPANSION_BUDGET_MS
+          }
+        });
+        const symbolPath = [
+          ...(enrichedAncestry ?? []).map((a) => a.name),
+          enclosingSymbol.name
+        ].join(" → ");
+        dbg(`ts expanded read: ${path.basename(filePath)} ` + `lines ${requestedReadOffset}–${requestedReadOffset + requestedReadLimit - 1} ` + `→ ${symbolPath} ` + `(${expansion.newOffset}–${expansion.newOffset + expansion.newLimit - 1})`);
+      }
+    } catch {}
+  }
+  if (toolName === "read" && filePath && !isExternalOrVendor) {
+    const totalLines = countFileLines(filePath);
+    const deliveredLimit = effectiveReadLimit ?? 1;
+    logToolReadGuardEvent({
+      event: "read_pattern",
+      sessionId: runtime.telemetrySessionId,
+      filePath,
+      requestedOffset: requestedReadOffset,
+      requestedLimit: requestedReadLimit ?? deliveredLimit,
+      effectiveOffset: effectiveReadOffset,
+      effectiveLimit: deliveredLimit,
+      metadata: {
+        totalLines,
+        isPartial: requestedReadLimit != null && requestedReadLimit < totalLines,
+        fileKind: detectFileKind(filePath) ?? "unknown",
+        fractionRead: totalLines > 0 ? Math.round(deliveredLimit / totalLines * 100) / 100 : 1,
+        expandedByTs: enclosingSymbol !== undefined
+      }
+    });
+    runtime.readGuard.recordRead({
+      filePath,
+      requestedOffset: requestedReadOffset,
+      requestedLimit: requestedReadLimit ?? deliveredLimit,
+      effectiveOffset: effectiveReadOffset,
+      effectiveLimit: deliveredLimit,
+      expandedByLsp: enclosingSymbol !== undefined,
+      ...enclosingSymbol !== undefined && { enclosingSymbol },
+      turnIndex: runtime.turnIndex,
+      writeIndex: runtime.peekWriteIndex(),
+      timestamp: Date.now(),
+      provisional: true,
+      ...toolCallId !== undefined && {
+        source: `native-read:${toolCallId}:provisional`
+      }
+    });
+  }
+  if (!getFlag("no-complexity") && !isExternalOrVendor && filePath && !runtime.complexityBaselines.has(filePath) && isComplexitySupportedFile(filePath)) {
+    const complexityClient = (await requestBootstrapClients({
+      reason: "tool-call-complexity-baseline",
+      hook: "tool_call",
+      signal: deps.ctx.signal
+    }))?.complexityClient;
+    const baseline = await complexityClient?.analyzeFile(filePath);
+    if (baseline) {
+      runtime.complexityBaselines.set(filePath, baseline);
+      const { captureSnapshot } = await import("./metrics-history.js");
+      captureSnapshot(filePath, {
+        maintainabilityIndex: baseline.maintainabilityIndex,
+        cognitiveComplexity: baseline.cognitiveComplexity,
+        maxNestingDepth: baseline.maxNestingDepth,
+        linesOfCode: baseline.linesOfCode,
+        maxCyclomatic: baseline.maxCyclomaticComplexity,
+        entropy: baseline.codeEntropy
+      });
+    }
+  } else if (getFlag("no-complexity") && filePath && isComplexitySupportedFile(filePath)) {
+    recordDegradationOnce({
+      kind: "startup-analyzer-disabled",
+      subject: "complexity",
+      reason: "skipped (disabled by config)"
+    });
+  }
+  const isEditOnly = mutation?.kind === "edit";
+  const isWriteOrEdit = mutation !== undefined;
+  if (!isEditOnly && isWriteOrEdit && event.toolName !== "bash" && filePath && !getFlag("no-read-guard")) {
+    runtime.readGuard.noteCreatedFile(filePath, runtime.turnIndex, runtime.peekWriteIndex(), resolveReadEvidenceCorrelationId(event));
+  }
+  if (isEditOnly && filePath) {
+    const editInput = event.input;
+    const oldTexts = editInput.oldText ? [
+      {
+        label: "oldText",
+        value: editInput.oldText,
+        newText: editInput.newText,
+        apply: (corrected) => {
+          editInput.oldText = corrected;
+        },
+        applyNewText: (corrected) => {
+          editInput.newText = corrected;
+        }
+      }
+    ] : (editInput.edits ?? []).map((e, i) => e.oldText ? {
+      label: `edits[${i}].oldText`,
+      value: e.oldText,
+      newText: e.newText,
+      apply: (corrected) => {
+        e.oldText = corrected;
+      },
+      applyNewText: (corrected) => {
+        e.newText = corrected;
+      }
+    } : null).filter((entry) => entry !== null);
+    let crlfContent;
+    let matchNormalizedContent;
+    try {
+      const raw = nodeFs.readFileSync(filePath, "utf-8");
+      crlfContent = raw.replace(/\r\n/g, `
+`);
+      matchNormalizedContent = normalizeOldTextForMatch(raw);
+    } catch {}
+    if (matchNormalizedContent !== undefined) {
+      for (const entry of oldTexts) {
+        const v = entry.value;
+        if (!v.includes("\t") && !v.includes(`
+`))
+          continue;
+        if (countOldTextMatches(filePath, v, matchNormalizedContent) !== 0)
+          continue;
+        const escaped = v.replace(/\t/g, "\\t").replace(/\n/g, "\\n");
+        if (escaped === v)
+          continue;
+        if (countOldTextMatches(filePath, escaped, matchNormalizedContent) !== 1)
+          continue;
+        entry.apply(escaped);
+        entry.value = escaped;
+        logToolReadGuardEvent({
+          event: "oldtext_escape_autopatched",
+          sessionId: runtime.telemetrySessionId,
+          filePath,
+          metadata: { tool: "edit", label: entry.label }
+        });
+      }
+    }
+    if (crlfContent !== undefined) {
+      for (const entry of oldTexts) {
+        const patch = computeTrailingWhitespaceOldTextPatch({
+          oldText: entry.value,
+          newText: entry.newText,
+          fileContent: crlfContent
+        });
+        if (!patch)
+          continue;
+        entry.apply(patch.oldText);
+        entry.value = patch.oldText;
+        const newTextPatched = patch.newText !== undefined && patch.newText !== entry.newText;
+        if (newTextPatched) {
+          entry.applyNewText(patch.newText);
+          entry.newText = patch.newText;
+        }
+        logToolReadGuardEvent({
+          event: "oldtext_trailing_ws_autopatched",
+          sessionId: runtime.telemetrySessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            label: entry.label,
+            removedLineTrailingWhitespace: patch.removedLineTrailingWhitespace,
+            removedTrailingEmptyLineCount: patch.removedTrailingEmptyLineCount,
+            newTextTrailingEmptyLinesPatched: newTextPatched
+          }
+        });
+        if (matchNormalizedContent !== undefined && runtime.readGuard) {
+          const range = findUniqueMatchLineRange(matchNormalizedContent, patch.oldText);
+          if (range) {
+            runtime.readGuard.recordRead({
+              filePath,
+              requestedOffset: range.startLine,
+              requestedLimit: range.endLine - range.startLine + 1,
+              effectiveOffset: range.startLine,
+              effectiveLimit: range.endLine - range.startLine + 1,
+              expandedByLsp: false,
+              turnIndex: runtime.turnIndex,
+              writeIndex: 0,
+              timestamp: Date.now()
+            });
+          }
+        }
+      }
+    }
+    const correctedOldTexts = oldTexts.map(({ label, value, newText, apply, applyNewText }) => {
+      const corrected = crlfContent !== undefined ? tryCorrectIndentationMismatchFromContent(value, crlfContent) : tryCorrectIndentationMismatch(value, filePath);
+      return corrected === undefined ? undefined : {
+        label,
+        value,
+        newText,
+        corrected,
+        apply,
+        applyNewText,
+        currentMatchCount: countOldTextMatches(filePath, value, matchNormalizedContent),
+        correctedMatchCount: countOldTextMatches(filePath, corrected, matchNormalizedContent),
+        indentationOnly: isIndentationOnlyChange(value, corrected)
+      };
+    }).filter((entry) => entry !== undefined);
+    for (const entry of correctedOldTexts) {
+      if (entry.indentationOnly && entry.currentMatchCount === 0 && entry.correctedMatchCount === 1) {
+        entry.apply(entry.corrected);
+        const matchedRange = matchNormalizedContent !== undefined ? findUniqueMatchLineRange(matchNormalizedContent, entry.corrected) : undefined;
+        const correctedNewText = entry.newText ? retargetReplacementIndentation(entry.newText, entry.value, entry.corrected, matchNormalizedContent !== undefined && matchedRange ? {
+          content: matchNormalizedContent,
+          startLine: matchedRange.startLine
+        } : undefined) : undefined;
+        if (correctedNewText !== undefined) {
+          entry.applyNewText(correctedNewText);
+        }
+        logToolReadGuardEvent({
+          event: "oldtext_indent_autopatched",
+          sessionId: runtime.telemetrySessionId,
+          filePath,
+          metadata: {
+            tool: "edit",
+            label: entry.label,
+            correctedMatchCount: entry.correctedMatchCount,
+            newTextIndentationPatched: correctedNewText !== undefined
+          }
+        });
+        if (matchNormalizedContent !== undefined && runtime.readGuard) {
+          const range = matchedRange;
+          if (range) {
+            runtime.readGuard.recordRead({
+              filePath,
+              requestedOffset: range.startLine,
+              requestedLimit: range.endLine - range.startLine + 1,
+              effectiveOffset: range.startLine,
+              effectiveLimit: range.endLine - range.startLine + 1,
+              expandedByLsp: false,
+              turnIndex: runtime.turnIndex,
+              writeIndex: 0,
+              timestamp: Date.now()
+            });
+          }
+        }
+      }
+    }
+  }
+  if (isEditOnly && filePath && !getFlag("no-read-guard")) {
+    const readGuard = runtime.readGuard;
+    const isExistingFile = typeof readGuard?.isNewFile !== "function" || !readGuard.isNewFile(filePath);
+    if (readGuard && isExistingFile && !isExternalOrVendor) {
+      const { touchedLines, editRanges, preflightError, preflightDetails, alreadyAppliedEdits, partiallyApplicable, contentMatchValidated, editBatchSummary } = getTouchedLinesForGuard(event, filePath, runtime.telemetrySessionId, readGuardCorrelationId, runtime.partialApplyRecords, readGuard.contentMatchesLastRead(filePath));
+      if (preflightError) {
+        if (partiallyApplicable && partiallyApplicable.length > 0) {
+          const partialStamp = {
+            stampFileTime: readGuard.fileTimeMoved?.(filePath) !== true
+          };
+          try {
+            const partial = await applyPartiallyApplicableEdits({
+              filePath,
+              edits: partiallyApplicable,
+              summary: editBatchSummary,
+              correlationId: readGuardCorrelationId,
+              recordStore: runtime.partialApplyRecords,
+              afterWrite: async () => {
+                const { biomeClient, ruffClient, metricsClient, agentBehaviorClient } = await loadBootstrapClients();
+                const result = await handleToolResult({
+                  signal: deps.ctx.signal,
+                  event: {
+                    toolName: "write",
+                    input: { path: filePath },
+                    details: {
+                      piLensPartialApply: true,
+                      readGuardCorrelationId
+                    },
+                    content: []
+                  },
+                  getFlag: (name) => getFlag(name),
+                  dbg,
+                  runtime,
+                  cacheManager,
+                  biomeClient,
+                  ruffClient,
+                  metricsClient,
+                  resetLSPService,
+                  readGuard: runtime.readGuard,
+                  sessionId: deps.sessionId,
+                  _ownWriteStamp: partialStamp,
+                  agentBehaviorRecord: (toolName, analyzedPath) => agentBehaviorClient.recordToolCall(toolName, analyzedPath),
+                  formatBehaviorWarnings: (warnings) => agentBehaviorClient.formatWarnings(warnings)
+                });
+                if (result?.isError) {
+                  throw new Error("post-edit pipeline rejected synthetic partial apply");
+                }
+                return result?.content?.map((item) => item.text).filter((text) => !!text).join(`
+
+`);
+              }
+            });
+            if (partial.rejected) {
+              if (!editBatchSummary)
+                logBlockedEditSummary("preflight");
+              return {
+                block: true,
+                reason: `${preflightError}
+
+\uD83D\uDED1 Batch not applied: ${partial.rejected.detail}`
+              };
+            }
+            if (partial.postEditStatus === "failed") {
+              return {
+                block: true,
+                reason: composePartialApplyReason({
+                  appliedCount: partial.appliedCount,
+                  appliedIndices: partial.appliedIndices,
+                  postEditStatus: "failed",
+                  preflightDetails,
+                  alreadyAppliedEdits
+                })
+              };
+            }
+            if (partial.appliedCount > 0) {
+              logToolReadGuardEvent({
+                event: "edit_partial_apply",
+                sessionId: runtime.telemetrySessionId,
+                filePath,
+                metadata: {
+                  appliedCount: partial.appliedCount,
+                  appliedTotal: partial.appliedTotal,
+                  appliedIndices: partial.appliedIndices,
+                  editBatchSummary: partial.summary,
+                  routedThroughPostEditPipeline: true
+                }
+              });
+              return {
+                block: true,
+                reason: composePartialApplyReason({
+                  appliedCount: partial.appliedCount,
+                  appliedIndices: partial.appliedIndices,
+                  postEditStatus: "succeeded",
+                  postEditOutput: partial.postEditOutput,
+                  preflightDetails,
+                  alreadyAppliedEdits
+                })
+              };
+            }
+          } catch {}
+        }
+        if (!editBatchSummary)
+          logBlockedEditSummary("preflight");
+        return { block: true, reason: preflightError };
+      }
+      logToolReadGuardEvent({
+        event: "edit_check_started",
+        sessionId: runtime.telemetrySessionId,
+        filePath,
+        metadata: {
+          tool: mutation?.kind ?? "edit",
+          touchedLines: touchedLines ?? null,
+          isExistingFile
+        }
+      });
+      const fileTimeMoved = readGuard.fileTimeMoved?.(filePath) === true;
+      const verdict = typeof readGuard.checkEdit === "function" ? readGuard.checkEdit(filePath, touchedLines, editRanges, {
+        skipSnapshotCheck: !!contentMatchValidated,
+        oldTextResolved: !!contentMatchValidated
+      }) : { action: "allow" };
+      if (fileTimeMoved && toolCallId !== undefined)
+        runtime.markToolCallFileTimeStale(toolCallId);
+      if (verdict.relocation) {
+        const relocated = relocateEditRange(event.input, verdict.relocation.from, verdict.relocation.to);
+        if (relocated) {
+          const [toStart, toEnd] = verdict.relocation.to;
+          runtime.readGuard?.recordRead({
+            filePath,
+            requestedOffset: toStart,
+            requestedLimit: toEnd - toStart + 1,
+            effectiveOffset: toStart,
+            effectiveLimit: toEnd - toStart + 1,
+            expandedByLsp: false,
+            turnIndex: runtime.turnIndex,
+            writeIndex: 0,
+            timestamp: Date.now()
+          });
+          logToolReadGuardEvent({
+            event: "edit_range_relocated",
+            sessionId: runtime.telemetrySessionId,
+            filePath,
+            metadata: {
+              tool: "edit",
+              from: verdict.relocation.from,
+              to: verdict.relocation.to
+            }
+          });
+        } else if (verdict.action === "block") {
+          logBlockedEditSummary("range_relocated_blocked");
+          return { block: true, reason: verdict.reason };
+        }
+      } else if (verdict.action === "block") {
+        logBlockedEditSummary("read_guard_blocked");
+        return {
+          block: true,
+          reason: verdict.reason
+        };
+      } else if (toolCallId !== undefined) {
+        runtime.markToolCallEditInPlace(toolCallId);
+      }
+    }
+  }
+  if (isWriteOrEdit && runtime.cachedExports.size > 0) {
+    const newContent = getNewContentFromToolCall(event);
+    if (newContent) {
+      const dupeWarnings = [];
+      const exportRe = /export\s+(?:async\s+)?(?:function|class|const|let|type|interface)\s+(\w+)/g;
+      let currentFileExports;
+      if (filePath && nodeFs.existsSync(filePath)) {
+        try {
+          const currentContent = nodeFs.readFileSync(filePath, "utf-8");
+          currentFileExports = new Set;
+          for (const m of currentContent.matchAll(exportRe)) {
+            currentFileExports.add(m[1]);
+          }
+        } catch {}
+      }
+      for (const match of newContent.matchAll(exportRe)) {
+        const name = match[1];
+        const existingFile = runtime.cachedExports.get(name);
+        if (existingFile && path.resolve(existingFile) !== path.resolve(filePath) && !currentFileExports?.has(name)) {
+          dupeWarnings.push(`\`${name}\` already exists in ${path.relative(runtime.projectRoot, existingFile)}`);
+        }
+      }
+      if (dupeWarnings.length > 0) {
+        return {
+          block: true,
+          reason: `\uD83D\uDD34 STOP - Redefining existing export(s). Import instead:
+` + dupeWarnings.map((w) => "  • " + w).join(`
+`)
+        };
+      }
+    }
+  }
+}