agenr 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.13.3] - 2026-03-23
+
+### Surgeon
+
+- **`complete_pass` gating rejects premature completion.** The tool now validates budget utilization and candidate coverage before accepting completion. Final completion rejected if <25% budget used. Dedup phase rejected if <50% of clusters processed with budget remaining. Retirement phase rejected if <40 candidates evaluated with budget remaining. Safety valve accepts after 3 rejections per phase. Rejection messages tell the surgeon exactly what to do next.
+- **System prompt tightened.** Budget Awareness section now explicitly states that `complete_pass` will reject premature attempts, and that efficiency means spending budget on the right candidates, not spending less budget overall.
+
+## [0.13.2] - 2026-03-23
+
+### Surgeon
+
+- **Continuation loop prevents early exit.** If the surgeon model stops without calling `complete_pass` and has >10% budget remaining, a continuation prompt is injected to push it back to work. Up to 3 nudges before allowing exit. Eliminates the "surgeon quits at 1% budget" problem.
+- **Lowered default dedup similarity threshold from 0.82 to 0.60.** The threshold controls candidate surfacing, not merge execution — the surgeon agent still makes every merge decision. Lower threshold surfaces more candidates for review on large corpora.
+- **`reset` parameter for `query_dedup_clusters` and `query_contradiction_candidates`.** Query parameters are no longer permanently frozen after the first call. Pass `reset: true` to clear cached clusters and rebuild at a new threshold. Lets the surgeon start wide and narrow if noisy.
+- **Strengthened auto sweep prompts.** Contradictions phase always runs proactive scan (no more skipping when pending conflicts = 0). Budget discipline section added — surgeon must keep working while budget remains. Retirement throughput expectations: 500+ candidates on a 3K corpus, not 100.
+- **Dedup threshold guidance in prompts.** Surgeon is told the default is deliberately low, and can raise it via reset if too noisy.
+
 ## [0.13.1] - 2026-03-23
 
 ### MCP Server

package/dist/cli-main.js

@@ -20772,7 +20772,7 @@ function validateClusterWithSupport(group, maxSize, diameterFloor, supportGraph)
 }
 
 // src/modules/surgeon/application/clustering/cluster.ts
-var DEFAULT_SIMILARITY_THRESHOLD2 = 0.82;
+var DEFAULT_SIMILARITY_THRESHOLD2 = 0.6;
 var CROSS_TYPE_SUBJECT_THRESHOLD = 0.89;
 var DEFAULT_MIN_CLUSTER = 2;
 var DEFAULT_MAX_CLUSTER_SIZE2 = 12;
@@ -22929,6 +22929,53 @@ async function updateEntryFieldsById(db, entryId, fields) {
   };
 }
 
+// src/modules/surgeon/application/completion-guard.ts
+function createEmptyProgress() {
+  return {
+    queryCalls: 0,
+    maxWindowEnd: 0,
+    totalCount: null,
+    sawExhaustedPage: false
+  };
+}
+function createPaginatedQueryTracker() {
+  let progress = createEmptyProgress();
+  return {
+    reset() {
+      progress = createEmptyProgress();
+    },
+    recordPage(input) {
+      const offset = Number.isFinite(input.offset) ? Math.max(0, Math.floor(input.offset)) : 0;
+      const returnedCount = Number.isFinite(input.returnedCount) ? Math.max(0, Math.floor(input.returnedCount)) : 0;
+      const totalCount = Number.isFinite(input.totalCount) ? Math.max(0, Math.floor(input.totalCount)) : null;
+      progress = {
+        queryCalls: progress.queryCalls + 1,
+        maxWindowEnd: Math.max(progress.maxWindowEnd, offset + returnedCount),
+        totalCount: totalCount ?? progress.totalCount,
+        sawExhaustedPage: progress.sawExhaustedPage || input.exhausted
+      };
+    },
+    snapshot() {
+      return { ...progress };
+    }
+  };
+}
+function createSurgeonCompletionGuardState(input) {
+  return {
+    rejectionCounts: /* @__PURE__ */ new Map(),
+    initialHealth: {
+      totalEntries: Math.max(0, Math.floor(input.totalEntries)),
+      retirementCandidates: Math.max(0, Math.floor(input.retirementCandidates)),
+      dedupClusters: Number.isFinite(input.dedupClusters) ? Math.max(0, Math.floor(input.dedupClusters)) : void 0,
+      pendingConflicts: Number.isFinite(input.pendingConflicts) ? Math.max(0, Math.floor(input.pendingConflicts)) : void 0
+    },
+    retirement: createPaginatedQueryTracker(),
+    dedup: createPaginatedQueryTracker(),
+    pendingConflicts: createPaginatedQueryTracker(),
+    contradictionScan: createPaginatedQueryTracker()
+  };
+}
+
 // src/modules/surgeon/adapters/prompts/index.ts
 import fs21 from "fs/promises";
 import path24 from "path";
@@ -23149,6 +23196,72 @@ var COMPLETE_PASS_SCHEMA = Type2.Object({
   observations: Type2.Array(Type2.String()),
   recommendations: Type2.Array(Type2.String())
 });
+var FINAL_COMPLETION_MIN_BUDGET_USED_FRACTION = 0.25;
+var PHASE_COMPLETION_MIN_BUDGET_USED_FRACTION = 0.5;
+var SAFETY_VALVE_REJECTION_LIMIT = 3;
+var LARGE_CORPUS_PROACTIVE_SCAN_THRESHOLD = 200;
+function isCompletionPhase(value) {
+  return value === "contradictions" || value === "dedup" || value === "retirement";
+}
+function normalizeCompletionKey(passType, currentPass) {
+  const normalizedPassType = passType?.trim();
+  if (normalizedPassType) {
+    return normalizedPassType;
+  }
+  return currentPass;
+}
+function isAutoPhaseTransition(currentPass, passType) {
+  return currentPass === "auto" && isCompletionPhase(passType);
+}
+function calculateBudgetUsedPct(deps) {
+  if (!deps.budgetTracker) {
+    return null;
+  }
+  const remaining = deps.budgetTracker.remaining();
+  const tokenBudget = Number.isFinite(deps.tokenBudget) ? Math.max(0, deps.tokenBudget ?? 0) : 0;
+  const costCap = Number.isFinite(deps.costCap) ? Math.max(0, deps.costCap ?? 0) : 0;
+  const tokenUsedPct = tokenBudget > 0 ? 1 - remaining.tokens / tokenBudget : 1;
+  const costUsedPct = costCap > 0 ? 1 - remaining.costUsd / costCap : 1;
+  return {
+    budgetUsedPct: Math.max(0, Math.min(1, Math.max(tokenUsedPct, costUsedPct))),
+    remainingTokens: remaining.tokens,
+    remainingCostUsd: remaining.costUsd
+  };
+}
+function formatBudgetUsedPct(value) {
+  return Math.round(value * 100);
+}
+function rejectCompletionAttempt(deps, rejectionKey, priorRejections, summary, details, message) {
+  deps.completionGuards?.rejectionCounts.set(rejectionKey, priorRejections + 1);
+  return toolResult(
+    {
+      completed: false,
+      rejected: true,
+      rejectionCount: priorRejections + 1,
+      summary,
+      ...details
+    },
+    message
+  );
+}
+function describeRetirementProgress(progress, knownCandidates) {
+  if (progress.queryCalls === 0) {
+    return knownCandidates > 0 ? `about ${knownCandidates} retirement candidates were available before the pass started, but query_candidates has not been called yet` : "query_candidates has not been called yet";
+  }
+  if (knownCandidates > 0) {
+    return `only ${progress.maxWindowEnd} of about ${knownCandidates} retirement candidates have been paged so far`;
+  }
+  return `only ${progress.maxWindowEnd} retirement candidates have been paged so far and query_candidates has not been exhausted`;
+}
+function describeDedupProgress(progress, totalClusters) {
+  if (progress.queryCalls === 0) {
+    return totalClusters > 0 ? `${totalClusters} dedup clusters were cached for this run, but query_dedup_clusters has not been called yet` : "query_dedup_clusters has not been called yet";
+  }
+  if (totalClusters > 0) {
+    return `only ${progress.maxWindowEnd} of ${totalClusters} dedup clusters have been paged so far`;
+  }
+  return `only ${progress.maxWindowEnd} dedup clusters have been paged so far and query_dedup_clusters has not been exhausted`;
+}
 function createCompletePassTool(deps) {
   return {
     name: "complete_pass",
@@ -23178,12 +23291,111 @@ function createCompletePassTool(deps) {
         recommendations: params.recommendations
       };
       const passType = params.pass_type?.trim();
+      const rejectionKey = normalizeCompletionKey(passType, deps.pass);
+      const priorRejections = deps.completionGuards?.rejectionCounts.get(rejectionKey) ?? 0;
+      const budgetUsage = calculateBudgetUsedPct(deps);
+      const budgetUsedPct = budgetUsage?.budgetUsedPct ?? 1;
+      const budgetUsedLabel = formatBudgetUsedPct(budgetUsedPct);
+      const handledCount = Math.max(0, params.actions_taken + params.entries_skipped.length);
+      if (priorRejections < SAFETY_VALVE_REJECTION_LIMIT && budgetUsage && deps.completionGuards) {
+        const isPhaseTransition = isAutoPhaseTransition(deps.pass, passType);
+        const guardedPhase = isPhaseTransition ? passType : isCompletionPhase(deps.pass) ? deps.pass : null;
+        if (guardedPhase === "retirement" && budgetUsedPct < PHASE_COMPLETION_MIN_BUDGET_USED_FRACTION) {
+          const progress = deps.completionGuards.retirement.snapshot();
+          const knownCandidates = deps.completionGuards.initialHealth.retirementCandidates;
+          const hasKnownRetirementWork = knownCandidates > 0 || progress.queryCalls > 0;
+          const shouldReject = hasKnownRetirementWork && !progress.sawExhaustedPage && (progress.queryCalls === 0 && knownCandidates > handledCount || progress.queryCalls > 0 && (knownCandidates === 0 || progress.maxWindowEnd < knownCandidates));
+          if (shouldReject) {
+            return rejectCompletionAttempt(
+              deps,
+              rejectionKey,
+              priorRejections,
+              summary,
+              {
+                phase: "retirement",
+                budgetUsedPct: budgetUsedLabel,
+                pagedCandidates: progress.maxWindowEnd,
+                knownCandidates: knownCandidates || null,
+                remainingTokens: budgetUsage.remainingTokens,
+                remainingCostUsd: budgetUsage.remainingCostUsd
+              },
+              `Retirement completion rejected: ${describeRetirementProgress(progress, knownCandidates)} with ${budgetUsedLabel}% of budget used. Continue calling query_candidates with a higher offset until it returns no more candidates or your budget is genuinely low.`
+            );
+          }
+        }
+        if (guardedPhase === "dedup" && budgetUsedPct < PHASE_COMPLETION_MIN_BUDGET_USED_FRACTION) {
+          const progress = deps.completionGuards.dedup.snapshot();
+          const totalClusters = progress.totalCount ?? deps.completionGuards.initialHealth.dedupClusters ?? 0;
+          const halfClusters = totalClusters > 0 ? Math.ceil(totalClusters * 0.5) : 0;
+          const hasKnownDedupWork = totalClusters > 0 || progress.queryCalls > 0;
+          const shouldReject = hasKnownDedupWork && !progress.sawExhaustedPage && (progress.queryCalls === 0 && totalClusters > handledCount || progress.queryCalls > 0 && (totalClusters === 0 || progress.maxWindowEnd < halfClusters));
+          if (shouldReject) {
+            return rejectCompletionAttempt(
+              deps,
+              rejectionKey,
+              priorRejections,
+              summary,
+              {
+                phase: "dedup",
+                budgetUsedPct: budgetUsedLabel,
+                pagedClusters: progress.maxWindowEnd,
+                totalClusters: totalClusters || null,
+                remainingTokens: budgetUsage.remainingTokens,
+                remainingCostUsd: budgetUsage.remainingCostUsd
+              },
+              `Dedup completion rejected: ${describeDedupProgress(progress, totalClusters)} with ${budgetUsedLabel}% of budget used. Continue paging query_dedup_clusters before completing the dedup phase.`
+            );
+          }
+        }
+        const isFinalAutoCompletion = deps.pass === "auto" && (!passType || passType === "auto");
+        if (isFinalAutoCompletion && budgetUsedPct < FINAL_COMPLETION_MIN_BUDGET_USED_FRACTION) {
+          const reasons = [];
+          const pendingConflicts = deps.completionGuards.pendingConflicts.snapshot();
+          const dedup = deps.completionGuards.dedup.snapshot();
+          const retirement = deps.completionGuards.retirement.snapshot();
+          const contradictionScan = deps.completionGuards.contradictionScan.snapshot();
+          const initialPendingConflicts = deps.completionGuards.initialHealth.pendingConflicts ?? 0;
+          const initialDedupClusters = deps.completionGuards.initialHealth.dedupClusters ?? 0;
+          const initialRetirementCandidates = deps.completionGuards.initialHealth.retirementCandidates;
+          if (initialPendingConflicts > 0 && !pendingConflicts.sawExhaustedPage && (pendingConflicts.queryCalls === 0 || pendingConflicts.maxWindowEnd < initialPendingConflicts)) {
+            reasons.push(
+              pendingConflicts.queryCalls === 0 ? `${initialPendingConflicts} pending conflicts were available and query_conflicts has not been paged` : `only ${pendingConflicts.maxWindowEnd} of ${initialPendingConflicts} pending conflicts have been paged`
+            );
+          }
+          if (initialDedupClusters > 0 && !dedup.sawExhaustedPage && (dedup.queryCalls === 0 || dedup.maxWindowEnd < initialDedupClusters)) {
+            reasons.push(describeDedupProgress(dedup, initialDedupClusters));
+          }
+          if (initialRetirementCandidates > 0 && !retirement.sawExhaustedPage && (retirement.queryCalls === 0 || retirement.maxWindowEnd < initialRetirementCandidates)) {
+            reasons.push(describeRetirementProgress(retirement, initialRetirementCandidates));
+          }
+          if (deps.completionGuards.initialHealth.totalEntries >= LARGE_CORPUS_PROACTIVE_SCAN_THRESHOLD && contradictionScan.queryCalls === 0) {
+            reasons.push("the proactive contradiction scan has not run yet");
+          }
+          if (reasons.length > 0) {
+            return rejectCompletionAttempt(
+              deps,
+              rejectionKey,
+              priorRejections,
+              summary,
+              {
+                phase: "auto",
+                budgetUsedPct: budgetUsedLabel,
+                remainingTokens: budgetUsage.remainingTokens,
+                remainingCostUsd: budgetUsage.remainingCostUsd,
+                reasons
+              },
+              `Completion rejected: only ${budgetUsedLabel}% of budget used and the sweep still looks incomplete because ${reasons.join("; ")}. Continue paging candidates and only call complete_pass with pass_type="auto" when the remaining phases are genuinely exhausted or budget is low.`
+            );
+          }
+        }
+      }
       if (passType && passType !== "auto" && deps.pass === "auto") {
         deps.completionState.completePhase(passType, summary);
         return toolResult(
           {
             completed: false,
             phaseComplete: passType,
+            safetyValveUsed: priorRejections >= SAFETY_VALVE_REJECTION_LIMIT,
             summary
           },
           `${passType} phase complete. Continue with the next pass. Call complete_pass with pass_type="auto" when all passes are done.`
@@ -23193,6 +23405,7 @@ function createCompletePassTool(deps) {
       return toolResult(
         {
           completed: true,
+          safetyValveUsed: priorRejections >= SAFETY_VALVE_REJECTION_LIMIT,
           summary
         },
         "Pass marked complete. Do not call more tools. Respond with a brief final acknowledgment."
@@ -23402,6 +23615,10 @@ var QUERY_CONTRADICTION_CANDIDATES_SCHEMA = Type4.Object({
     default: false,
     description: "If true, only return pairs sharing a subject_key. If false, also find semantically similar cross-subject pairs."
   })),
+  reset: Type4.Optional(Type4.Boolean({
+    default: false,
+    description: "If true, clear the cached contradiction scan for this run and rebuild it with the current scan settings."
+  })),
   limit: Type4.Optional(Type4.Integer({ minimum: 1, maximum: 50, default: 20 })),
   offset: Type4.Optional(Type4.Integer({ minimum: 0 }))
 });
@@ -23441,9 +23658,13 @@ function createQueryContradictionCandidatesTool(deps) {
   return {
     name: "query_contradiction_candidates",
     label: "Query contradiction candidates",
-    description: "Scan the active corpus for potential undiscovered contradictions. Finds pairs of entries that are semantically similar or share structured claim predicates but assert different things. Pairs already in conflict_log are marked but still returned. Use inspect_entry to evaluate promising pairs, then resolve_conflict to fix confirmed contradictions or flag_for_review for ambiguous cases.",
+    description: "Scan the active corpus for potential undiscovered contradictions. Finds pairs of entries that are semantically similar or share structured claim predicates but assert different things. Pairs already in conflict_log are marked but still returned. Use inspect_entry to evaluate promising pairs, then resolve_conflict to fix confirmed contradictions or flag_for_review for ambiguous cases. If you need to rebuild the scan with different thresholds, call with reset=true.",
     parameters: QUERY_CONTRADICTION_CANDIDATES_SCHEMA,
     async execute(_toolCallId, params) {
+      if (params.reset === true) {
+        cached = null;
+        deps.completionGuards?.contradictionScan.reset();
+      }
       const query = buildQuery(params, deps);
       const offset = normalizeOffset2(params.offset);
       const limit = normalizeLimit2(params.limit);
@@ -23470,6 +23691,12 @@ function createQueryContradictionCandidatesTool(deps) {
       }
       const totalCount = cached?.pairs.length ?? 0;
       if (offset >= totalCount) {
+        deps.completionGuards?.contradictionScan.recordPage({
+          offset,
+          returnedCount: 0,
+          totalCount,
+          exhausted: true
+        });
         return toolResult({
           pairs: [],
           count: 0,
@@ -23481,6 +23708,12 @@ function createQueryContradictionCandidatesTool(deps) {
         });
       }
       const pairs = (cached?.pairs ?? []).slice(offset, offset + limit);
+      deps.completionGuards?.contradictionScan.recordPage({
+        offset,
+        returnedCount: pairs.length,
+        totalCount,
+        exhausted: offset + pairs.length >= totalCount
+      });
       return toolResult({
         pairs,
         count: pairs.length,
@@ -23620,6 +23853,12 @@ function createQueryConflictsTool(deps) {
         now: deps.now()
       });
       if (offset >= conflicts.length) {
+        deps.completionGuards?.pendingConflicts.recordPage({
+          offset,
+          returnedCount: 0,
+          totalCount: conflicts.length,
+          exhausted: true
+        });
         return toolResult({
           conflicts: [],
           count: 0,
@@ -23630,6 +23869,12 @@ function createQueryConflictsTool(deps) {
         });
       }
       const page = conflicts.slice(offset, offset + limit).filter((conflict) => !deps.conflictCache?.consumedConflictIds.has(conflict.id)).map((conflict) => summarizeConflict(conflict));
+      deps.completionGuards?.pendingConflicts.recordPage({
+        offset,
+        returnedCount: page.length,
+        totalCount: conflicts.length,
+        exhausted: offset + page.length >= conflicts.length
+      });
       return toolResult({
         conflicts: page,
         count: page.length,
@@ -23750,7 +23995,7 @@ function createResolveConflictTool(deps) {
 import { Type as Type7 } from "@sinclair/typebox";
 
 // src/modules/surgeon/application/dedup-clusters.ts
-var DEFAULT_SIM_THRESHOLD = 0.82;
+var DEFAULT_SIM_THRESHOLD = 0.6;
 var CLUSTER_PREVIEW_MAX_CHARS = 200;
 var UNSCOPED_PROJECT_LABEL = "(unscoped)";
 var DAY_MS3 = 24 * 60 * 60 * 1e3;
@@ -23868,6 +24113,11 @@ function getCachedEligibleDedupClusters(cache) {
     clusters: cache.eligibleClusters
   };
 }
+function resetDedupClusterCache(cache) {
+  cache.rawClusters = null;
+  cache.eligibleClusters = null;
+  cache.frozenQuery = null;
+}
 async function loadEligibleDedupClusters(db, input) {
   const cached = getCachedEligibleDedupClusters(input.cache);
   if (cached) {
@@ -24031,6 +24281,10 @@ var QUERY_DEDUP_CLUSTERS_SCHEMA = Type8.Object({
   project: Type8.Optional(Type8.String()),
   type: Type8.Optional(Type8.String()),
   sim_threshold: Type8.Optional(Type8.Number({ minimum: 0.5, maximum: 1 })),
+  reset: Type8.Optional(Type8.Boolean({
+    default: false,
+    description: "If true, clear the cached cluster scan for this run and rebuild it with the current filters so you can adjust thresholds mid-run."
+  })),
   limit: Type8.Optional(Type8.Integer({ minimum: 1, maximum: 20 })),
   offset: Type8.Optional(Type8.Integer({ minimum: 0 }))
 });
@@ -24050,12 +24304,16 @@ function createQueryDedupClustersTool(deps) {
   return {
     name: "query_dedup_clusters",
     label: "Query dedup clusters",
-    description: "Retrieve clusters of potentially duplicate entries. Each cluster groups entries with high embedding similarity or identical structured claims. Returns cluster summaries with entry previews. Use offset for pagination.",
+    description: "Retrieve clusters of potentially duplicate entries. Each cluster groups entries with high embedding similarity or identical structured claims. Returns cluster summaries with entry previews. Use offset for pagination. If you need to rebuild the candidate set with a different threshold or scope, call with reset=true.",
     parameters: QUERY_DEDUP_CLUSTERS_SCHEMA,
     async execute(_toolCallId, params) {
       if (!deps.clusterCache) {
         throw new Error("Dedup cluster cache is unavailable for this run.");
       }
+      if (params.reset === true) {
+        resetDedupClusterCache(deps.clusterCache);
+        deps.completionGuards?.dedup.reset();
+      }
       const query = normalizeDedupClusterQuery(
         {
           project: params.project,
@@ -24074,6 +24332,12 @@ function createQueryDedupClustersTool(deps) {
         now: deps.now()
       });
       if (offset >= clusters.length) {
+        deps.completionGuards?.dedup.recordPage({
+          offset,
+          returnedCount: 0,
+          totalCount: clusters.length,
+          exhausted: true
+        });
         return toolResult({
           clusters: [],
           count: 0,
@@ -24085,6 +24349,12 @@ function createQueryDedupClustersTool(deps) {
         });
       }
       const page = clusters.slice(offset, offset + limit).map((cluster, index) => summarizeDedupCluster(cluster, offset + index, query.project));
+      deps.completionGuards?.dedup.recordPage({
+        offset,
+        returnedCount: page.length,
+        totalCount: clusters.length,
+        exhausted: offset + page.length >= clusters.length
+      });
       return toolResult({
         clusters: page,
         count: page.length,
@@ -24250,6 +24520,18 @@ var QUERY_CANDIDATES_SCHEMA = Type12.Object({
   limit: Type12.Optional(Type12.Integer({ minimum: 1, maximum: 100 })),
   offset: Type12.Optional(Type12.Integer({ minimum: 0 }))
 });
+function normalizeLimit5(value) {
+  if (!Number.isFinite(value) || (value ?? 0) <= 0) {
+    return 20;
+  }
+  return Math.floor(value);
+}
+function normalizeOffset5(value) {
+  if (!Number.isFinite(value) || (value ?? 0) < 0) {
+    return 0;
+  }
+  return Math.floor(value);
+}
 function createQueryCandidatesTool(deps) {
   return {
     name: "query_candidates",
@@ -24257,6 +24539,8 @@ function createQueryCandidatesTool(deps) {
     description: "List active entries that look stale enough to inspect for retirement.",
     parameters: QUERY_CANDIDATES_SCHEMA,
     async execute(_toolCallId, params) {
+      const limit = normalizeLimit5(params.limit);
+      const offset = normalizeOffset5(params.offset);
       const candidates = await listRetirementCandidates(deps.db, {
         project: params.project?.trim() || deps.project,
         type: params.type?.trim() || void 0,
@@ -24270,6 +24554,11 @@ function createQueryCandidatesTool(deps) {
         runId: deps.runId,
         now: deps.now()
       });
+      deps.completionGuards?.retirement.recordPage({
+        offset,
+        returnedCount: candidates.length,
+        exhausted: candidates.length < limit
+      });
       if (candidates.length === 0) {
         return toolResult({
           candidates: [],
@@ -24473,13 +24762,13 @@ var QUERY_SUPERSESSION_SCHEMA = Type15.Object({
   limit: Type15.Optional(Type15.Integer({ minimum: 1, maximum: 50, default: 20 })),
   offset: Type15.Optional(Type15.Integer({ minimum: 0 }))
 });
-function normalizeOffset5(value) {
+function normalizeOffset6(value) {
   if (!Number.isFinite(value) || (value ?? 0) < 0) {
     return 0;
   }
   return Math.floor(value);
 }
-function normalizeLimit5(value) {
+function normalizeLimit6(value) {
   if (!Number.isFinite(value) || (value ?? 0) <= 0) {
     return 20;
   }
@@ -24503,8 +24792,8 @@ function createQuerySupersessionCandidatesTool(deps) {
         },
         deps.project
       );
-      const offset = normalizeOffset5(params.offset);
-      const limit = normalizeLimit5(params.limit);
+      const offset = normalizeOffset6(params.offset);
+      const limit = normalizeLimit6(params.limit);
       const { groups } = await loadEligibleSupersessionGroups(deps.db, {
         cache: deps.supersessionCache,
         query,
@@ -24927,6 +25216,9 @@ async function captureBrainHealthSnapshot(db) {
 // src/modules/surgeon/application/workflow.ts
 var USER_ABORT_ERROR = "Run aborted by user (SIGINT).";
 var USER_ABORT_SUMMARY = "Run aborted by user.";
+var MAX_CONTINUATION_ATTEMPTS = 3;
+var LOW_BUDGET_FRACTION = 0.1;
+var SHALLOW_RUN_WARNING_BUDGET_USED_FRACTION = 0.5;
 function resolveRunBudget(options, config) {
   if (Number.isFinite(options.budget) && options.budget > 0) {
     return Math.floor(options.budget);
@@ -25112,6 +25404,7 @@ function buildInitialUserPrompt(options, stats, tokenBudget, dedupClusterCount,
       `Last surgeon run: ${stats.lastRun ? `${stats.lastRun.passType} ${stats.lastRun.status} at ${stats.lastRun.startedAt}` : "none"}.`,
       `Your budget is ${tokenBudget} tokens for the entire sweep.`,
       "Work through passes in priority order: contradictions -> dedup -> retirement.",
+      "Always run the proactive contradiction scan before dedup, even when pending conflicts start at 0.",
       "Call complete_pass with the pass_type for each phase transition, and complete_pass with pass_type='auto' when the full sweep is done."
     ].join(" ");
   }
@@ -25128,6 +25421,31 @@ function buildInitialUserPrompt(options, stats, tokenBudget, dedupClusterCount,
     "Work conservatively and use complete_pass when you are done."
   ].join(" ");
 }
+function buildContinuationPrompt(options, input) {
+  const lines = [
+    `You stopped without calling complete_pass and still have ${input.remainingTokens} tokens and about $${input.remainingCostUsd.toFixed(2)} of run budget remaining.`
+  ];
+  if (options.pass === "auto") {
+    lines.push(
+      "Continue the auto sweep. If contradictions are not fully scanned, resume there first. Otherwise continue with the next unfinished phase in order: contradictions, dedup, retirement."
+    );
+    lines.push(
+      "Do not call complete_pass with pass_type='auto' until the full sweep is genuinely done."
+    );
+  } else {
+    lines.push(`Continue the ${options.pass} pass.`);
+    lines.push(
+      "Do not call complete_pass until candidates are genuinely exhausted or budget is low."
+    );
+  }
+  lines.push("Keep paginating and evaluating candidates.");
+  lines.push("A healthy-looking batch or a few blocked candidates are not reasons to stop.");
+  lines.push(
+    "If contradiction or dedup scans feel too narrow or too noisy, call the query tool again with reset=true and adjusted thresholds."
+  );
+  lines.push(`This is continuation attempt ${input.attempt} of ${MAX_CONTINUATION_ATTEMPTS}.`);
+  return lines.join(" ");
+}
 function buildStoredSummary(passType, summary, phaseCompletions, snapshots) {
   if (!summary) {
     return null;
@@ -25299,6 +25617,7 @@ async function runSurgeon(options, deps) {
   };
   let terminalStatus = null;
   let terminalError = null;
+  let continuationAttempts = 0;
   async function finalizeRun(status, error, summaryOverride) {
     if (beforeSnapshot && !afterSnapshot) {
       afterSnapshot = await captureBrainHealthSnapshot(deps.db);
@@ -25414,6 +25733,12 @@ async function runSurgeon(options, deps) {
       skipRecentlyEvaluatedDays: protection.contradictionSkipRecentlyEvaluatedDays,
       now
     })).length : void 0;
+    const completionGuards = createSurgeonCompletionGuardState({
+      totalEntries: initialStatus.health.total,
+      retirementCandidates: initialStatus.health.forgetting.candidates,
+      dedupClusters: initialDedupClusterCount ?? initialAutoDedupClusterCount,
+      pendingConflicts: initialPendingConflictCount
+    });
     const tools = createToolRegistryFn({
       db: deps.db,
       config: deps.config,
@@ -25444,6 +25769,10 @@ async function runSurgeon(options, deps) {
         await logSurgeonAction(deps.db, action);
         traceLogger.logAction(action);
       },
+      budgetTracker,
+      tokenBudget,
+      costCap: runCostCap,
+      completionGuards,
       getHealthStats: (statusDeps) => loadStatusFn(
         {
           db: deps.db,
@@ -25479,6 +25808,30 @@ async function runSurgeon(options, deps) {
         convertToLlm,
         toolExecution: "sequential",
         getApiKey: deps.getApiKey,
+        getFollowUpMessages: async () => {
+          if (completionState.isComplete || signal?.aborted || budgetTracker.isExhausted() || budgetTracker.isCostCapExceeded() || continuationAttempts >= MAX_CONTINUATION_ATTEMPTS) {
+            return [];
+          }
+          const remaining = budgetTracker.remaining();
+          const tokenRemainingFraction = tokenBudget > 0 ? remaining.tokens / tokenBudget : 0;
+          const costRemainingFraction = runCostCap > 0 ? remaining.costUsd / runCostCap : 0;
+          if (tokenRemainingFraction < LOW_BUDGET_FRACTION || costRemainingFraction < LOW_BUDGET_FRACTION) {
+            return [];
+          }
+          continuationAttempts += 1;
+          log21.warn(
+            `Surgeon stopped without completing. Injecting continuation prompt (${continuationAttempts}/${MAX_CONTINUATION_ATTEMPTS}) with ${remaining.tokens} tokens and $${remaining.costUsd.toFixed(2)} remaining.`
+          );
+          return [{
+            role: "user",
+            content: buildContinuationPrompt(options, {
+              remainingTokens: remaining.tokens,
+              remainingCostUsd: remaining.costUsd,
+              attempt: continuationAttempts
+            }),
+            timestamp: Date.now()
+          }];
+        },
         beforeToolCall: async (context) => {
           registerUsage(context.assistantMessage);
           if (signal?.aborted) {
@@ -25580,6 +25933,19 @@ async function runSurgeon(options, deps) {
         summarizeCompletion(completionState.summary, completionState.passCompletions) ?? USER_ABORT_SUMMARY
       );
     }
+    const totals = budgetTracker.totals();
+    const budgetUsedPct = Math.min(
+      1,
+      Math.max(
+        runCostCap > 0 ? totals.costUsd / runCostCap : 1,
+        tokenBudget > 0 ? (totals.inputTokens + totals.outputTokens) / tokenBudget : 1
+      )
+    );
+    if (!completionState.isComplete && !budgetTracker.isExhausted() && !budgetTracker.isCostCapExceeded() && budgetUsedPct < SHALLOW_RUN_WARNING_BUDGET_USED_FRACTION) {
+      log21.warn(
+        `Surgeon ended without calling complete_pass and left ${((1 - budgetUsedPct) * 100).toFixed(0)}% of the run budget unused. The run may have quit early. Re-run with --verbose to inspect the trace.`
+      );
+    }
     const finalStatus = completionState.summary ? terminalStatus && terminalStatus !== "failed" ? terminalStatus : "completed" : terminalStatus ?? "completed";
     return finalizeRun(finalStatus, terminalError);
   } catch (error) {

package/dist/modules/surgeon/adapters/prompts/passes/auto.md

@@ -6,15 +6,15 @@ You have access to ALL surgeon tools across ALL pass types. Your job is to work
 
 Work through passes in this priority order:
 
-1. **Contradictions** - Resolve pending conflicts first. Active inconsistencies degrade corpus trust. Use `query_conflicts` and `resolve_conflict`.
-   Then scan for undiscovered contradictions with `query_contradiction_candidates`, log confirmed pairs with `log_conflict`, and resolve them.
+1. **Contradictions** - Always start here. Resolve pending conflicts first. Active inconsistencies degrade corpus trust. Use `query_conflicts` and `resolve_conflict`.
+   Then run a proactive scan with `query_contradiction_candidates`, even if `query_conflicts` returned zero pending conflicts. Log confirmed pairs with `log_conflict` and resolve them.
 2. **Dedup** - Merge duplicate entries next. Duplicates waste recall bandwidth and confuse retrieval. Use `query_dedup_clusters` and `merge_cluster`.
 3. **Retirement** - Clean up stale entries last. Use `query_candidates` and `retire_entry`. After standard candidates, scan for supersession chains with `query_supersession_candidates`.
 
 ## Workflow
 
 1. Call `get_health_stats` to orient.
-2. Start with the highest-priority pass that has work to do. If there are pending conflicts, start with contradictions. If none, check for dedup clusters. If none, start retirement.
+2. **Always start with contradictions.** First resolve pending conflicts via `query_conflicts`. Then, regardless of whether there were pending conflicts, run a proactive scan using `query_contradiction_candidates` to find undiscovered contradictions. Only move to dedup after both pending conflicts are resolved and the proactive scan is complete, or the contradictions budget allocation is genuinely spent.
 3. Work through that pass's candidates using the same methodology described in its individual pass instructions.
 4. When a pass is complete (candidates exhausted or no more productive work), call `complete_pass` with `pass_type` set to the pass you just finished (for example, `"contradictions"`).
 5. After completing a pass, move to the next priority pass. You do not need to call `get_health_stats` again - check for work by calling the next pass's query tool directly.
@@ -40,6 +40,18 @@ Rough budget allocation guideline (not rigid):
 
 If a pass has no work, its budget share rolls into the next pass.
 
+## Budget Discipline
+
+**Do not stop early.** Your budget exists to be used. If you have remaining budget and there are still candidates to evaluate, keep working. Finishing a sweep at 1% of budget on a corpus of thousands of entries means you barely looked.
+
+Concrete rules:
+
+- After each `complete_pass` for a phase transition, check your remaining budget. If significant budget remains, the next phase should use it.
+- For retirement: page through all candidates until `query_candidates` returns empty or budget is genuinely low, meaning less than 10% remains. Seeing a batch of healthy entries is not a reason to stop. The next batch may contain stale entries.
+- For contradictions: the proactive scan is mandatory in auto mode. Zero pending conflicts from `query_conflicts` is not enough to move on.
+- For dedup: if the phase produces very few clusters, note that observation. A corpus of thousands of entries typically has many more than a handful of near-duplicate candidates.
+- If you reach `complete_pass` with `pass_type = "auto"` after using less than 50% of your budget, reconsider. Go back and do deeper evaluation: inspect more dedup clusters, reset the contradiction or dedup query with wider thresholds if needed, or run a broader retirement sweep.
+
 ## Complete Pass Calls
 
 Call `complete_pass` once per phase transition:
@@ -49,6 +61,6 @@ Call `complete_pass` once per phase transition:
 - After finishing retirement work: `complete_pass` with `pass_type = "retirement"`
 - After all passes are done: `complete_pass` with `pass_type = "auto"` (this is the final one)
 
-If a pass has zero work (for example, no pending conflicts), skip calling `complete_pass` for it - just move to the next pass.
+If a pass has zero actionable work after running its required discovery steps, you may move to the next pass without calling `complete_pass` for that phase.
 
 The final `complete_pass` with `pass_type = "auto"` should include observations and recommendations spanning all passes you worked through.

package/dist/modules/surgeon/adapters/prompts/passes/contradictions.md

@@ -42,6 +42,8 @@ Keep working until conflicts are exhausted or budget is low. Call `complete_pass
 
 After resolving pending conflicts from `query_conflicts`, scan for undiscovered contradictions using `query_contradiction_candidates`. This finds pairs of active entries that the ingestion pipeline never compared - entries from different sessions, with different subject normalization, or from different project scopes.
 
+**Do not skip proactive scanning.** Even if `query_conflicts` returned zero pending conflicts, the proactive scan via `query_contradiction_candidates` is mandatory. Undiscovered contradictions are the most dangerous kind because they silently degrade corpus quality without appearing in the pending conflict queue.
+
 For each candidate pair:
 
 1. **Check if already known** - If `existingConflictLogId` is present, the conflict is already logged. Skip it or inspect the entries if you need more context.
@@ -57,7 +59,7 @@ For each candidate pair:
 
 **Prioritize claim divergence pairs** (strategy `"claim_divergence"`) over embedding similarity pairs. Claim divergence means two entries share the same subject and predicate but assert different objects - these are usually real conflicts. Embedding similarity pairs need more careful evaluation.
 
-Budget note: Proactive scanning is secondary to resolving known pending conflicts. If budget is tight after `query_conflicts`, skip the scan and note it in your `complete_pass` recommendations.
+Budget note: Known pending conflicts still take priority, but proactive scanning is part of completing this pass. Only stop before the scan is exhausted when budget is genuinely low. If that happens, note the incomplete scan in your `complete_pass` recommendations.
 
 ## Resolution Quality Rules
 

package/dist/modules/surgeon/adapters/prompts/passes/dedup.md

@@ -31,6 +31,14 @@ For each cluster from `query_dedup_clusters`:
 - Preserve the strongest form. Prefer the most specific, complete, and well-supported version of the knowledge.
 - Treat recently consolidated entries with extra caution. If `merged_from > 0` and `consolidated_at` is recent, inspect before merging again.
 
+## Threshold Guidance
+
+The similarity threshold controls which entry pairs are surfaced as candidates for your review. It does not control whether entries actually get merged. Merging always requires your decision after reading the entries.
+
+The default threshold is deliberately low (`0.60`) so the candidate net is wide. That will surface some clear duplicates, some borderline cases, and some related-but-distinct entries. That is expected. Your job is to evaluate each cluster and decide: merge, flag, or skip.
+
+If the current threshold is too noisy or too narrow, call `query_dedup_clusters` with `reset = true` and a different `sim_threshold`. Reset clears the cached cluster set for this run and rebuilds it with your new parameters. Start wide, then tighten only if the candidate stream is mostly noise.
+
 ## Working Through Clusters
 
 You will receive clusters in batches.

package/dist/modules/surgeon/adapters/prompts/passes/retirement.md

@@ -37,6 +37,10 @@ An empty `query_candidates` result means there are no more candidates matching t
 
 A productive pass works through hundreds of candidates, not dozens.
 
+**Budget awareness:** If your budget allows examining more candidates, you must keep paginating. Do not call `complete_pass` while `query_candidates` is still returning candidates and budget is available. A batch where most entries are healthy is normal in a healthy corpus. That does not mean the pass is done. Keep going. The stale entries are mixed throughout the candidate pool.
+
+Expected throughput: On a corpus of around 3000 entries, a retirement pass with adequate budget should evaluate at least 500 candidates and often more. If you stop at 100, you probably have not done enough.
+
 ## Type-Specific Heuristics
 
 Different entry types have different retirement profiles:

package/dist/modules/surgeon/adapters/prompts/system.md

@@ -43,7 +43,7 @@ You are working through the full candidate pool, not just one batch. After proce
 - Your budget is running low - check the budget warnings from blocked tool calls
 - You have exhausted the actionable candidates
 
-Only call `complete_pass` when you have genuinely finished working through available candidates or your budget is exhausted. Processing a single batch and stopping is not completing the pass.
+Only call `complete_pass` when you have genuinely finished working through available candidates or your budget is exhausted. Processing a single batch and stopping is not completing the pass. `complete_pass` will reject your request if significant budget remains and candidates have not been exhausted. If your completion is rejected, continue paging through candidates.
 
 When `query_candidates` returns zero candidates, that is your signal that no more candidates match the current filters and it is appropriate to call `complete_pass`.
 
@@ -97,13 +97,15 @@ This is your core competency - the judgment that mechanical rules cannot make.
 
 ## Budget Awareness
 
-You have a token budget. Prioritize high-value actions:
+You have a token budget for this run. Use it wisely:
 
 - Don't waste budget inspecting entries that are obviously protected or clearly fine from their summary.
 - Don't inspect every candidate - scan summaries, pick the most promising ones.
-- When you have enough evidence, act or finish. Don't over-investigate.
+- When you have enough evidence, act or skip. Don't over-investigate a single entry.
 - Flag borderline cases for review rather than spending budget trying to reach certainty.
 
+**But do not stop early.** Efficiency means spending budget on the right candidates, not spending less budget overall. If candidates remain and budget is available, keep working. The `complete_pass` tool will reject premature completion if you have not used enough of your budget.
+
 ## Scope
 
 - When a project scope is provided, focus on entries in that project plus universal (unscoped) entries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "openclaw": {
     "extensions": [
       "dist/edge/openclaw/index.js"