@gitkraken/conflict-tools 0.2.4-beta.17 → 0.2.4-beta.18

package/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- `ResolverConfig.maxModelCalls` — an optional global model-call budget for the whole operation. When set and the budget is spent, the opt-in fix phase stops attempting further fixes and leaves the remainder in the findings (so the verdict still reflects the true post-fix state), emitting a new `fix:budget-exhausted` progress event (`{ spent, limit }`). When unset, the fix phase is not budget-limited.
+- `fix:failed` progress event (`{ filePath?, reason }`) — emitted when the opt-in fix phase throws a non-abort error, so a consumer can observe the graceful degradation rather than only seeing the checks flip to `errored`.
 - Cross-file fixes in the fix phase (opt-in `ResolverConfig.fix`). After per-file convergence, a project-tier broken reference (an import/cross-file use whose target stopped resolving) is routed to the refine of its **use-site** file: the finding becomes a fix instruction, and the whole set is re-detected, up to `crossFileMaxIterations` rounds (default 2). Each cross-file fix is a single refine pass plus a mandatory per-file re-validation; the final whole-set detection also re-checks per-file for files a cross-file fix touched. **Limitation:** only use-site files that have an AI resolution are routed — a cross-file break landing on an auto-merged file (no resolution to carry the edit) is reported but not auto-fixed yet (needs a patches channel). The definition side, if broken, arrives as its own finding on its own file. Report-only (fix off) is unchanged.
 - Per-file fix loop (opt-in via `ResolverConfig.fix`, default `false`). When enabled, an AI-resolved (`strategy: 'ai'`) text file that carries error-severity per-file findings is routed back through refine: the findings become fix instructions, the file is re-analyzed after each edit, and the loop repeats until the file is clean, a round makes no progress, or `fixLoopMaxIterations` (default 3) is reached. Whatever it cannot fix stays in the findings, so the verdict reflects the post-fix state. The no-markers invariant holds (a fix that reintroduces markers is discarded). New progress events `fix:started` / `fix:completed`. Report-only (fix off) is unchanged. Deferred for the opt-in fix path: rebase per-step-ref/transient discipline, parser/validator call caching, cross-file fixes, and a full finding-lifecycle model (double-counting is handled here by fingerprint dedup when folding findings into the report).
 - `collectFileFindings` — a per-file detection unit (structural + intra-file broken references + consumer validator issues, all `tier: 'file'`) over already-loaded parent snapshots; the fix loop re-runs it after each edit. `detect()` remains the authoritative whole-set report.
@@ -30,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- The opt-in fix phase is now fault-isolated. A parser, validator, or model throw inside the fix phase no longer rejects the whole operation: the pre-fix resolutions are kept, both detection checks are reported as `errored` (so the verdict is `needs-review`, never a false `clean`), and the throw is surfaced via `fix:failed`. A user abort still propagates and cancels the operation.
 - `OperationDigest.verdict` can now reach `clean` on a real repository. `detectionComplete` treated `partial-unsupported-language` as "did not run", so any operation whose scope contained a non-code file (package.json, README, lockfiles — always present in a real merge) forced `verdict: 'needs-review'` even with zero findings and full confidence. Since `--fix` gates auto-apply on `verdict === 'clean'`, this made auto-apply effectively unreachable. A check now counts as complete when it ran, including when some scope files were an unsupported language (they carry no references to break); only a check that could not run at all — no parser, no refs, an unreadable parent snapshot, or a thrown parser — leaves detection incomplete.
 - A non-abort error in the refine pass no longer destroys the pre-refine resolution. Previously the refine `catch` rethrew, bubbling to `resolveOne` and degrading a good resolve-stage result into a take-side fallback (confidence 0) — the same class of failure as a throwing validator, one stage later. The pre-refine resolution is now kept, its confidence capped (the enhancement did not complete), and the error reported via `refine:failed`. A user abort still cancels (rethrown past the fallback).
 - A throwing consumer validator no longer destroys a good resolution. The post-refine `validator.validate()` call is now guarded: a validator error is reported via a new `validation:failed` progress event and the resolution is kept intact, instead of bubbling to `resolveOne` and degrading a successful AI resolve into a whole-file take-side fallback (confidence 0) — the exact dropped-side loss the tool guards against. The validator stays advisory.

package/README.md

@@ -1,6 +1,6 @@
 # @gitkraken/conflict-tools
 
-AI-powered git conflict resolution. Parses conflict markers (including delete-modify conflicts), resolves them with an agentic AI loop that has access to git context (blame, grep, diff, log, show, file content), and writes results back to the working tree.
+AI-powered git conflict resolution. Parses conflict markers (including delete-modify conflicts), resolves them with an agentic AI loop that has access to git context (blame, grep, diff, log, show, file content), refines the result with targeted intra-file edits, then runs deterministic reference-integrity detection over the whole touched set and produces an honest verdict. Results are written back to the working tree by the consumer.
 
 ## What it does
 
@@ -8,9 +8,9 @@ Three entry points, each serving a different consumer need:
 
 - `extractConflict()` — parses conflict markers from a single file and returns a structured representation. Handles both text conflicts (with markers) and delete-modify conflicts (one side deleted, the other modified). No AI, no resolution.
 
-- `resolveConflict()` — takes one `Conflict` and an optional `ResolutionContext`, runs the AI tool-use loop, returns a `Resolution` with resolved content, confidence, and metrics. The single-file workhorse.
+- `resolveConflict()` — takes one `Conflict` and an optional `ResolutionContext`, runs the AI tool-use loop and per-file refine, returns a `Resolution` with resolved content, confidence, and metrics. The single-file workhorse.
 
-- `resolveConflicts() + applyResolutions()` — batch-resolve every currently unmerged file in the working tree, then write and stage results. Supports pattern-based routing: skip files, apply take-ours/take-theirs, or route to AI per glob pattern. The library does NOT orchestrate `git rebase`/`merge`/`cherry-pick` — the consumer drives the operation lifecycle.
+- `resolveConflicts() + applyResolutions()` — batch-resolve every currently unmerged file in the working tree, run set-level detection, then write and stage results. Supports pattern-based routing: skip files, apply take-ours/take-theirs, or route to AI per glob pattern. The library does NOT orchestrate `git rebase`/`merge`/`cherry-pick` — the consumer drives the operation lifecycle.
 
 The library never calls `git` or an AI provider directly. Consumers supply adapters via ports.
 
@@ -20,6 +20,16 @@ The library never calls `git` or an AI provider directly. Consumers supply adapt
 pnpm add @gitkraken/conflict-tools
 ```
 
+## Pipeline
+
+An operation runs in three stages. **Report-only is the default**, and the stage shape is identical whether or not the opt-in fix phase is enabled — the fix phase only adds edit attempts, it does not change the flow.
+
+1. **Resolve** — the agentic AI tool-use loop replaces conflict markers, self-assessing a confidence per marker. The *only* blocking gate is residual conflict markers (checked built-in, language-agnostic): a candidate that still contains markers is rejected and retried. No other check gates this stage — parser, validator, and detection are all downstream and advisory.
+2. **Refine** (per file) — when the resolver returns `followUpInstructions` (targeted edits it could not express as a whole-chunk decision), a second agentic loop applies them via the `edit_file_lines` tool. A refine that reintroduces markers is discarded; a refined file's confidence is capped at 0.9.
+3. **Detection** (set level) — after every file is resolved, deterministic reference-integrity detection runs over the whole touched set: per-file structural checks (syntax errors, duplicate definitions, intra-file broken references) on the resolved *and* the auto-merged/incoming files, plus cross-file broken-reference checks. Report-only — it never mutates state or fails the operation. It produces the `DetectionReport` attached to `StepResult.detection`, which drives the verdict.
+
+The opt-in **fix phase** (`config.fix: true`) sits between refine and the final detection report: it re-detects, routes the error-severity findings back through refine (per-file convergence, then cross-file routing), and only then emits the final report. What it cannot fix stays in the findings, so the verdict always reflects the post-fix state. See [Fix phase](#fix-phase-opt-in).
+
 ## Ports
 
 ### `ConflictGitPort`
@@ -42,6 +52,7 @@ High-level ops the library dispatches through:
 | `showFile(ref, path, opts?)` | Read file content at a specific ref. Supports `startLine`/`endLine` |
 | `unmergedEntries()` | List files git considers unresolved |
 | `mergeBase(a, b)` | Common ancestor between two refs |
+| `changedFiles(from, to)` | Paths changed between two refs (name-only). Used to discover the merge's incoming/auto-merged set for detection |
 | `blame(path, opts?)` | Line-level authorship. Supports `startLine`/`endLine` (maps to `git blame -L`) |
 | `grep(pattern, opts?)` | Content search across the tree. Supports `maxResults` |
 | `diff(from, to, opts?)` | Unified diff between refs, optionally scoped to a path |
@@ -73,29 +84,64 @@ const model: ConflictModelPort = {
 
 The shape of `tools`, `toolCalls`, and `toolResults` follows abstract types (`ToolDefinition`, `ToolCall`, `ToolResult`) so consumers can adapt any SDK. The library does not require streaming or any provider-specific feature.
 
-### `ResolutionVerifier` (optional)
+### `ParserPort` (optional — enables detection)
+
+A **facts-in** port. Given a content overlay, it returns per-file parse facts — definitions, references (each with a `resolved` flag), optional bindings, and syntax errors. The *package* derives findings from those facts; the port itself never classifies anything as a conflict or a break.
+
+```typescript
+import type { ParserPort, SourceOverlay, ParsedFile } from '@gitkraken/conflict-tools';
+
+const parser: ParserPort = {
+    async analyze(sources: SourceOverlay): Promise<ReadonlyMap<string, ParsedFile>> {
+        // tree-sitter (merge-mate) or a language server (GitLens/GKD), overlaying `sources`.
+        // Return one ParsedFile per input path.
+    },
+};
+```
+
+Three properties define the contract:
+
+- **Content-in overlay, no FS access.** `analyze(sources)` sees exactly the `SourceOverlay` contents (a `ReadonlyMap<path, content>`) and never reads the filesystem itself. This is what lets the package hand it pre-merge parent snapshots *and* the post-merge result and diff the two. A tree-sitter backend sees only these files; a language server may resolve against its workspace with these contents overlaid on top.
+- **Language-agnostic.** A file the backend cannot parse comes back with `language: 'unsupported'` and empty facts; the detector skips it (and reports `partial-unsupported-language`) rather than emitting false findings.
+- **Precision-abstracting.** A tree-sitter backend and a language-server backend differ in how completely they resolve references — the port hides that difference behind the same shape.
+
+`ParsedFile`:
+
+| Field | Meaning |
+|---|---|
+| `language` | Backend's language id; `'unsupported'` means "skip this file" |
+| `definitions` | `SymbolDefinition[]` — top-level defs (`name`, `kind?`, 1-indexed `line`) |
+| `references` | `SymbolReference[]` — `name`, `line`, `column?`, `resolved` (did it resolve within the overlay), `target?` |
+| `bindings?` | Optional names bound at *any* scope (module-level and nested). Populating it lets detection catch a reference broken by removing a nested binding. A backend that only surfaces top-level `definitions` may omit it |
+| `syntaxErrors` | `SyntaxIssue[]` — `line`, `message` |
+
+Pass via `deps.parser`. When absent, detection is skipped and the report says so (`skipped-no-parser`) — never a silent clean.
 
-A pluggable post-resolution check. The library ships a `defaultVerifier` that scans the assembled content for residual conflict markers. During the AI loop, a failed verification triggers a retry with feedback — the model gets a chance to self-correct.
+### `Validator` (optional)
+
+The consumer's validation port. Plug in any checks — syntax, real import resolution, types, lint, project rules. It runs **post-refine over an overlay** (one file for per-file validation, or the whole touched set for cross-file) and returns `ValidatorFinding[]`.
 
 ```typescript
-import { defaultVerifier } from '@gitkraken/conflict-tools';
-import type { ResolutionVerifier } from '@gitkraken/conflict-tools';
-
-// Use the built-in (checks for residual <<<<<<< / ======= / >>>>>>>)
-const verifier = defaultVerifier;
-
-// Or provide your own (e.g. run a linter, compile check)
-const custom: ResolutionVerifier = {
-    verify: async (filePath, content) => {
-        const errors = await lint(content);
-        return errors.length === 0
-            ? { valid: true }
-            : { valid: false, feedback: errors.join('\n') };
+import type { Validator, ValidatorFinding } from '@gitkraken/conflict-tools';
+
+const validator: Validator = {
+    async validate(sources) {
+        const findings: ValidatorFinding[] = [];
+        for (const [file, content] of sources) {
+            for (const err of await typecheck(file, content)) {
+                findings.push({ category: 'type-error', severity: 'error', file, line: err.line, message: err.message });
+            }
+        }
+        return findings;
     },
 };
 ```
 
-Pass the verifier via `deps.verifier` to `resolveConflict` or `resolveConflicts`.
+**Advisory, never blocking.** Its findings fold into the operation's detection findings and the verdict; a validator finding never triggers a re-resolve, and a *throwing* validator is caught (reported via `validation:failed`) and the resolution is kept intact. `ValidatorFinding.category` is an open string (e.g. `'type-error'`, `'lint:no-console'`) so consumer categories flow through alongside the package's own `FindingCategory` values.
+
+The one blocking gate — **residual conflict markers** — is *not* this port's job. It is checked built-in and language-agnostic inside the resolve loop. (This was the old `defaultVerifier`; it is now internal. `defaultVerifier`, `ResolutionVerifier`, and `VerificationResult` are no longer exported.)
+
+Pass via `deps.validator` to `resolveConflict` or `resolveConflicts`.
 
 ## Entry points
 
@@ -130,19 +176,25 @@ import { resolveConflict } from '@gitkraken/conflict-tools';
 const resolution = await resolveConflict(conflict, context, {
     model,
     git,
+    validator, // optional — advisory per-file checks
     config: { maxSteps: 15, temperature: 0 },
     onProgress: (event) => console.log(event),
 });
 
 // resolution.content       — resolved file content (markers replaced)
 // resolution.strategy      — 'ai' | 'take-ours' | 'take-theirs' | 'deleted' | 'skipped'
-// resolution.confidence    — 0..1, from the AI's own self-assessment
+// resolution.confidence    — 0..1, from the AI's own self-assessment (capped at 0.9 if refined)
 // resolution.description   — one-or-two sentence rationale, from the AI
+// resolution.findings?     — advisory per-file findings from the validator port (post-refine)
 // resolution.chunks?       — per-marker decisions (for observability and validation)
+// resolution.edits?        — IntraFileEditOp[] applied during refine (absent if refine did not run)
 // resolution.metrics?      — { inputTokens, outputTokens, stepCount, toolCallCount, ... }
+// resolution.rawSignals?   — policy-free measurements for the consumer's own assessment
 ```
 
-`ResolutionContext` carries optional hints the AI can use:
+`resolveConflict` runs stages 1–2 (resolve + refine) for a single file. Set-level detection (stage 3) is only run by the batch entry point, since it needs the whole touched set; use `detect()` directly if you want detection for a single-file flow.
+
+`ResolutionContext` carries optional hints the AI can use, plus the refs detection compares against:
 
 ```typescript
 interface ResolutionContext {
@@ -150,21 +202,25 @@ interface ResolutionContext {
     prDescription?: string;
     previousResolutions?: Resolution[];
     fileNeighbors?: string[];
+    /** Auto-merged files beyond the conflict set. Usually unset — detection discovers this from refs. */
+    touchedFiles?: string[];
     refs?: { ours: string; theirs: string; base?: string };
+    /** Parent tips for detection's before/after comparison, when they differ from `refs`. */
+    detectionRefs?: { ours: string; theirs: string; base?: string };
     threeWayDiff?: { oursDiff: string; theirsDiff: string };
+    /** Whole-file free-text guidance, rendered as a top-level <user-guidance> block. */
+    userGuidance?: string;
     metadata?: Record<string, unknown>;
 }
 ```
 
 When `refs` is provided, the library computes `git diff base..ours -- file` and `git diff base..theirs -- file` automatically and includes both in the prompt. This typically lets the AI resolve without any tool calls. Consumers that already have these diffs cached can pass `threeWayDiff` directly to skip the computation.
 
-### Phase 2 refine pass
-
-After Phase 1 resolves conflict markers, the AI may return `followUpInstructions: string[]` on the resolution — a list of targeted edits it could not express as a whole-chunk decision (for example, re-applying a partial change from the incoming branch). When `followUpInstructions` is non-empty, `resolveConflict` automatically runs a second agentic loop (Phase 2) that applies those edits via the `edit_file_lines` tool.
+`refs` drives the resolver's three-way diff; `detectionRefs` (falling back to `refs`) drives detection's before/after comparison. They differ in a rebase — where `refs` is the in-flight per-step state while detection needs the two stable pre-merge branch tips — and coincide in a plain merge, so `detectionRefs` is usually left unset.
 
-`ResolverConfig.refineMaxSteps?: number` controls how many model turns Phase 2 is allowed. Defaults to 5.
+#### Refine edits
 
-`Resolution.edits?: IntraFileEditOp[]` carries the list of edit operations that were successfully applied during Phase 2. Absent when Phase 2 did not run or all edits were discarded.
+The refine pass (stage 2) applies edits the resolver could not express as whole-chunk decisions — for example, re-applying a partial change from the incoming branch. `ResolverConfig.refineMaxSteps` (default 5) bounds its model turns. `Resolution.edits?: IntraFileEditOp[]` lists the operations that survived (absent when refine did not run or all edits were discarded).
 
 `IntraFileEditOp` is a discriminated union on `kind`:
 
@@ -176,12 +232,14 @@ After Phase 1 resolves conflict markers, the AI may return `followUpInstructions
 ### `resolveConflicts(deps, context?) + applyResolutions(resolutions, deps)` — batch
 
 ```typescript
-import { resolveConflicts, applyResolutions } from '@gitkraken/conflict-tools';
+import { resolveConflicts, applyResolutions, summarizeOperation } from '@gitkraken/conflict-tools';
 
 const step = await resolveConflicts(
     {
         model,
         git,
+        parser,     // optional — supply to enable set-level detection (stage 3)
+        validator,  // optional — advisory per-file checks
         config: {
             rules: [
                 { match: ['*.lock', 'pnpm-lock.yaml'], strategy: 'take-theirs' },
@@ -200,8 +258,13 @@ const step = await resolveConflicts(
 // step.resolutions[]       — successful resolutions
 // step.errors[]            — { filePath, error } for files that failed (no fallback or AI exhausted)
 // step.skipped?[]          — { filePath, reason } for files that were excluded or had no markers
+// step.detection?          — DetectionReport over the whole touched set (present when a parser was supplied)
 
-await applyResolutions(step.resolutions, { git });
+// Gate on the verdict, not on raw confidence — see below.
+const { digest } = await summarizeOperation(step);
+if (digest.verdict === 'clean') {
+    await applyResolutions(step.resolutions, { git });
+}
 // Resolutions are written via writeFile, checkoutFile, or removeFile and staged.
 ```
 
@@ -221,7 +284,117 @@ Available strategies for rules and `defaultStrategy`:
 | `'deleted'` | Remove the file entirely |
 | `'skip'` | Skip the file (no resolution produced) |
 
-The function inspects the working tree once (via `unmergedEntries`), processes each conflict sequentially, and returns. It does not call `git rebase --continue` or any other operation command — that is the consumer's job.
+The function inspects the working tree once (via `unmergedEntries`), processes each conflict sequentially, runs detection over the touched set, and returns. It does not call `git rebase --continue` or any other operation command — that is the consumer's job.
+
+## Detection & verdict
+
+### `detect(resolutions, context, deps)`
+
+Deterministic, report-only post-resolution detection. It never mutates state or fails the operation. `resolveConflicts` calls it for you and attaches the result to `StepResult.detection`; call it directly for a single-file or custom flow.
+
+```typescript
+import { detect } from '@gitkraken/conflict-tools';
+
+const report = await detect(step.resolutions, { refs }, { git, parser });
+```
+
+`DetectDeps` is `{ git; parser?; signal? }`. It flags:
+
+- references that resolved in a pre-merge parent (ours/theirs) but no longer resolve in the merged result (`broken-reference`, with `provenance`),
+- duplicate definitions and syntax errors in the resolved files (`duplicate-definition`, `syntax-error`),
+- a whole-side take that discarded a substantial diff from the other side (`dropped-side`).
+
+The scope includes the resolved files *and* the merge's auto-merged/incoming set (discovered from `refs` via `changedFiles`/`mergeBase`, or overridden by `context.touchedFiles`), so a dangling reference in a cleanly-merged file is still caught.
+
+`DetectionReport`:
+
+```typescript
+interface DetectionReport {
+    findings: Finding[];
+    checks: { referenceIntegrity: CheckStatus; structural: CheckStatus };
+    /** Honest coverage — present only when the reference check ran. */
+    scope?: { analyzed: number; readable: number; truncated: boolean };
+}
+```
+
+`Finding`:
+
+| Field | Meaning |
+|---|---|
+| `category` | Open string. The package emits `FindingCategory`; a consumer validator may add its own |
+| `severity` | `'error'` \| `'warning'` |
+| `tier` | `'file'` (intra-file) or `'project'` (cross-file) — the fix phase routes each tier differently |
+| `location` | `{ file; line; symbol? }` |
+| `provenance?` | For `broken-reference`: the pre-merge side (`'ours'`/`'theirs'`) that still resolved it, and where |
+| `message` | Human-readable description |
+
+`FindingCategory` (the well-known values the package itself emits):
+
+| Category | Meaning |
+|---|---|
+| `broken-reference` | A symbol resolved in a pre-merge parent but no longer resolves in the merged result |
+| `duplicate-definition` | The same symbol is defined twice in a resolved file |
+| `syntax-error` | The parser reported a syntax error in a resolved file |
+| `dropped-side` | A whole-side take discarded a substantial diff from the discarded side |
+
+`CheckStatus` tells "ran, clean" apart from "did not run" — so an empty `findings` array is never mistaken for a clean result:
+
+| Status | Meaning |
+|---|---|
+| `ran` | The check ran to completion |
+| `skipped-no-parser` | No `ParserPort` supplied |
+| `skipped-no-refs` | No refs, so the before/after comparison was impossible (structural checks still ran) |
+| `skipped-unreadable-source` | Refs were present but the parent snapshots came back empty (unreadable source) |
+| `partial-unsupported-language` | The check ran, but some files in scope were an unsupported language |
+| `errored` | The parser was present but threw |
+
+### `summarizeOperation` / `buildOperationDigest`
+
+`buildOperationDigest(result, reviewThreshold?)` is a pure, model-free rollup of a `StepResult` that folds in `detection`. `summarizeOperation(result, opts?)` returns `{ digest, prose?, usage? }` — always the digest, plus a prose narrative when `opts.model` is supplied.
+
+```typescript
+import { buildOperationDigest } from '@gitkraken/conflict-tools';
+
+const digest = buildOperationDigest(step);
+// digest.verdict            — 'clean' | 'needs-review' | 'blocked'
+// digest.detectionComplete  — did every detection check run to completion
+// digest.findingCount       — total detection findings
+// digest.needsReview        — ReviewItem[] (findings first, then lowest confidence first)
+// digest.minConfidence      — lowest file confidence, or null
+// digest.byStrategy         — resolution count per strategy
+```
+
+`OperationVerdict`:
+
+- `blocked` — at least one error-severity finding exists (the build is known-broken).
+- `needs-review` — confidence is low, detection did not fully run, a resolution errored, or a warning finding exists.
+- `clean` — none of the above.
+
+**Gate auto-apply on the verdict, not on confidence.** A refined or fixed file has its confidence capped at 0.9 — so a "confidence must be 1.0" gate would reject exactly the files the tool improved. `verdict === 'clean'` is the honest signal. And an *absent* verdict must NOT be read as clean: if you never ran detection (no parser) or never summarized, `detectionComplete` is `false` and empty findings mean "we didn't look," not "nothing's wrong." Only `verdict === 'clean'` is clean.
+
+A `ReviewItem` distinguishes a low-confidence flag from a finding: `reason: 'low-confidence' | 'finding'`, with `confidence?` (absent for a file flagged purely by a finding, e.g. an auto-merged file with no resolution of its own) and `findingCategories?` (present when `reason` is `'finding'`).
+
+## Fix phase (opt-in)
+
+By default the pipeline is **report-only**: detection findings land in `StepResult.detection` and the verdict, and the consumer decides what to do. Set `config.fix: true` to have the library attempt to fix error-severity findings before emitting the final report. The pipeline shape is identical in both modes — the fix phase only inserts edit attempts between refine and the final detection.
+
+When enabled:
+
+- **Per-file convergence** — an AI-resolved (`strategy: 'ai'`) text file carrying error-severity per-file findings is routed back through refine; the file is re-analyzed after each edit and the loop repeats until it is clean, a round makes no progress, or `fixLoopMaxIterations` (default 3) is reached.
+- **Cross-file routing** — a `tier: 'project'` broken reference (an import/cross-file use whose target stopped resolving) is routed to the refine of its *use-site* file, and the whole set is re-detected, up to `crossFileMaxIterations` (default 2) rounds. Only use-site files that have an AI resolution are routed; a break landing on an auto-merged file (no resolution to carry the edit) is reported but not auto-fixed.
+
+Whatever the fix phase cannot fix stays in the findings, so the verdict always reflects the post-fix state. The no-markers invariant holds throughout: a fix that reintroduces conflict markers is discarded rather than written.
+
+`ResolverConfig` fix-phase fields:
+
+| Field | Default | Effect |
+|---|---|---|
+| `fix` | `false` | Opt in to the fix phase. Off → report-only |
+| `fixLoopMaxIterations` | `3` | Max per-file fix iterations (refine → re-detect the file) |
+| `crossFileMaxIterations` | `2` | Max cross-file fix rounds (route project-level breaks → re-detect the set) |
+| `maxModelCalls` | unset | Global model-call budget for the whole operation. When set and the budget is spent, the fix phase stops attempting further fixes and leaves the remainder in the findings, emitting `fix:budget-exhausted`. When unset, the fix phase is not budget-limited |
+
+The fix phase is **fault-isolated**: a parser, validator, or model throw inside it does not reject the whole operation. The resolutions computed so far (possibly partially fixed, since the fix phase mutates them as it goes) are kept, both detection checks are reported as `errored`, and a `fix:failed` event is emitted (a user abort still propagates and cancels the operation).
 
 ## Consumer examples
 
@@ -241,8 +414,9 @@ if (conflict) {
 ### GitLens / GKD — batch "resolve all" (user-driven)
 
 ```typescript
-const step = await resolveConflicts({ git, model, onProgress: webview.post });
-const approved = await reviewDialog(step.resolutions);
+const step = await resolveConflicts({ git, model, parser, onProgress: webview.post }, { refs });
+const { digest } = await summarizeOperation(step);
+const approved = await reviewDialog(step.resolutions, step.detection, digest.verdict);
 await applyResolutions(approved, { git });
 // User clicks "continue rebase" themselves.
 ```
@@ -256,13 +430,18 @@ for (const commit of commits) {
     if (result.exitCode === 0) continue;
 
     const step = await resolveConflicts({
-        git, model,
+        git, model, parser,
         config: {
             rules: [{ match: '*.lock', strategy: 'take-theirs' }],
             fallbackStrategy: 'take-ours',
+            fix: true, // attempt to fix detected breaks before reporting
         },
         onProgress: emit,
-    });
+    }, { refs });
+
+    const { digest } = await summarizeOperation(step);
+    if (digest.verdict === 'blocked') { await escalateToHuman(step); break; }
+
     await applyResolutions(step.resolutions, { git });
     await git.exec(['rebase', '--continue']);
 }
@@ -282,27 +461,35 @@ score(resolution, goldenFile);
 
 | Event | When |
 |---|---|
-| `conflict:found` | A conflict file has been parsed |
+| `conflict:found` | A conflict file has been parsed (`conflictType`, `markerCount`) |
 | `conflict:excluded` | A file was skipped by a rule with `strategy: 'skip'` |
-| `conflict:skipped` | A file had no conflict markers and no delete-modify reason |
-| `resolution:applied` | A resolution was produced for a file |
-| `resolution:fallback` | AI failed; fallback strategy applied |
-| `resolution:failed` | AI failed and no fallback configured |
-| `resolver:tool-call` | The AI invoked a tool. Includes `reason` (why the AI called it) |
-| `resolver:step-usage` | Token usage for one model call |
-| `resolver:completed` | The resolver finished a single file |
-| `resolver:response` | Phase 1 produced its final response |
-| `resolver:tool-result` | A Phase 1 tool returned content |
-| `refine:started` | Phase 2 has begun |
-| `refine:skipped` | Phase 2 was not run (no follow-ups) |
-| `refine:tool-call` | Phase 2 model invoked `edit_file_lines` |
-| `refine:tool-result` | Phase 2 tool returned feedback |
-| `refine:final-text` | Phase 2 model emitted final description |
-| `refine:completed` | Phase 2 finished successfully (includes `appliedCount`) |
-| `refine:failed` | Phase 2 threw before completing |
-| `edit:discarded` | An edit batch was rejected (introduced markers) |
-
-Note: `refine:tool-result.appliedCount` reports edits applied to an in-progress buffer per turn. The final disposition is signaled by `refine:completed` / `edit:discarded` / `refine:failed` — only edits that survive residual-marker validation appear in `Resolution.edits`.
+| `conflict:skipped` | A file had no conflict markers and no delete-modify reason (`reason`, `entryReason?`) |
+| `resolution:applied` | A resolution was produced for a file (`strategy`, `confidence?`, `description?`) |
+| `resolution:fallback` | AI failed; fallback strategy applied (`error`, `cause?`) |
+| `resolution:failed` | AI failed and no fallback configured (`error`) |
+| `resolver:tool-call` | The AI invoked a tool during resolve (`tool`, `args`, `stepNumber`, `reason?`) |
+| `resolver:step-usage` | Token usage for one resolve model call (`stepNumber`, `usage`) |
+| `resolver:completed` | The resolver finished a single file (`stepCount`) |
+| `resolver:response` | The resolve stage produced its final structured response (`chunks`, `confidence`, `description`, `strategy?`, `followUpInstructions?`) |
+| `resolver:tool-result` | A resolve-stage tool returned content (`tool`, `stepNumber`, `content`) |
+| `refine:started` | The refine pass has begun |
+| `refine:skipped` | Refine was not run (`reason`, e.g. no follow-ups) |
+| `refine:tool-call` | Refine model invoked `edit_file_lines` (`stepNumber`, `ops`) |
+| `refine:tool-result` | A refine tool returned feedback (`stepNumber`, `appliedCount`, `isError`, `feedback`) |
+| `refine:final-text` | Refine model emitted its final description (`text`) |
+| `refine:completed` | Refine finished successfully (`appliedCount`) |
+| `refine:failed` | Refine threw before completing (`reason`) |
+| `refine:bailed` | Refine bailed early after consecutive apply errors, keeping edits that landed (`reason`) |
+| `refine:discarded` | A refine/fix edit batch was rejected because it reintroduced conflict markers (`reason`) |
+| `refine:touched-user-region` | Refine modified a user-resolved marker region (`markerIndexes`) |
+| `fix:started` | The fix loop began fixing a file (`findingCount`) |
+| `fix:completed` | The fix loop finished evaluating a file (`iterations`, `remaining`) — emitted even for a clean file (iterations 0, remaining 0) |
+| `fix:failed` | The opt-in fix phase threw a non-abort error (`filePath?`, `reason`); the operation degrades gracefully — pre-fix resolutions are kept and both checks are reported as `errored` |
+| `fix:budget-exhausted` | The global `maxModelCalls` budget was spent (`spent`, `limit`); the fix phase stopped and left the remainder in findings |
+| `validation:failed` | The consumer validator threw; reported and swallowed, resolution kept (`reason`) |
+| `verification:issues` | Advisory verification issues attached to a resolution (`issues`) |
+
+Note: `refine:tool-result.appliedCount` reports edits applied to an in-progress buffer per turn. The final disposition is signaled by `refine:completed` / `refine:discarded` / `refine:failed` — only edits that survive residual-marker validation appear in `Resolution.edits`.
 
 Operation-level events (rebase started, step completed, etc.) are the consumer's responsibility — the library has no opinion about the surrounding workflow.
 
@@ -328,7 +515,7 @@ try {
 }
 ```
 
-In the batch entry point, errors that have a configured fallback do not throw — they are downgraded to `resolution:fallback` events, and the resulting resolutions appear in `step.resolutions`. Errors without a fallback land in `step.errors` and the loop continues with the next file.
+In the batch entry point, errors that have a configured fallback do not throw — they are downgraded to `resolution:fallback` events, and the resulting resolutions appear in `step.resolutions`. Errors without a fallback land in `step.errors` and the loop continues with the next file. The advisory stages (refine, validator, detection, fix phase) are fault-isolated — a non-abort throw there is reported and swallowed rather than destroying a good resolution. A user abort (`signal.aborted`) always propagates and cancels the operation.
 
 ## Semver policy
 

package/dist/ports/model.d.ts

@@ -44,6 +44,13 @@ interface ResolverConfig {
   /** Max cross-file fix rounds (route project-level breaks to their use-site file → re-detect the whole
    *  set) when `fix` is on. Default 2. */
   crossFileMaxIterations?: number;
+  /** Global cap on `model.generate` calls for the whole operation (resolve + refine + fix). Default
+   *  `undefined` = unlimited. Primarily a backstop for the fix phase's multiplicative worst case
+   *  (files × fixLoopMaxIterations + crossFileMaxIterations × routable calls). When spent, the fix
+   *  phase stops attempting further fixes and leaves the remainder in findings — it never aborts the
+   *  operation. The resolve loop is not gated by this (it is already bounded by `maxSteps`); its calls
+   *  still count toward the cap. */
+  maxModelCalls?: number;
 }
 //#endregion
 export { ConflictModelMessage, ConflictModelParams, ConflictModelPort, ConflictModelResult, ResolverConfig };

package/dist/resolver/fix-loop.d.ts

@@ -5,6 +5,7 @@ import { ConflictModelPort, ResolverConfig } from "../ports/model.js";
 import { ParserPort } from "../ports/parser.js";
 import { Validator } from "../ports/verify.js";
 import { ConflictProgressEvent } from "../types/events.js";
+import { ModelBudget } from "./model-budget.js";
 
 //#region src/resolver/fix-loop.d.ts
 interface FixLoopDeps {
@@ -14,6 +15,12 @@ interface FixLoopDeps {
   config?: ResolverConfig;
   onProgress?: (event: ConflictProgressEvent) => void;
   signal?: AbortSignal;
+  /** Global model-call budget for the operation. When exhausted, the loop stops before any further
+   *  model call and leaves the remaining findings unfixed. Absent = unlimited. */
+  budget?: ModelBudget;
+  /** Invoked the first time the budget stops work. The caller dedupes so the operation emits a single
+   *  `fix:budget-exhausted`, whether the stop happens here or in the cross-file stage. */
+  onBudgetExhausted?: () => void;
 }
 /**
  * Per-file convergence loop (opt-in `config.fix`). Re-detects the file's per-file findings, feeds the
@@ -34,6 +41,9 @@ interface FixPhaseDeps {
   config?: ResolverConfig;
   onProgress?: (event: ConflictProgressEvent) => void;
   signal?: AbortSignal;
+  /** Global model-call budget for the operation. When exhausted, both fix stages stop before any
+   *  further model call, leaving the remainder in the report. Absent = unlimited. */
+  budget?: ModelBudget;
 }
 /**
  * The fix phase (opt-in). Stage 2: per-file convergence over each AI resolution ({@link runFixLoop}).

package/dist/resolver/model-budget.d.ts

@@ -0,0 +1,20 @@
+import { ConflictModelPort } from "../ports/model.js";
+
+//#region src/resolver/model-budget.d.ts
+/** A shared, per-operation counter of `model.generate` calls. Created once per {@link resolveConflicts}
+ *  run; the wrapped model increments the counter but never blocks — enforcement is the caller's job via
+ *  {@link ModelBudget.exhausted}, checked before fix-phase model calls only. Counting instead of throwing
+ *  is deliberate: a throw inside the resolve loop would be caught by the fallback path and degrade a good
+ *  resolution into a whole-side take — the exact data loss this package guards against. */
+interface ModelBudget {
+  /** Wrap a model so every `generate` call increments this budget's shared counter, then delegates to
+   *  the real model unchanged. Multiple wraps share one counter. */
+  wrap(model: ConflictModelPort): ConflictModelPort;
+  spent(): number;
+  /** Calls left before the cap. `Infinity` when the budget is unlimited (`max` undefined). */
+  remaining(): number;
+  exhausted(): boolean;
+}
+declare function createModelBudget(max?: number): ModelBudget;
+//#endregion
+export { ModelBudget, createModelBudget };

package/dist/resolver/model-budget.js

@@ -0,0 +1 @@
+function e(e){let t=0,n=()=>e===void 0?1/0:e-t;return{wrap(e){return{generate:n=>(t++,e.generate(n))}},spent:()=>t,remaining:n,exhausted:()=>n()<=0}}export{e as createModelBudget};

package/dist/types/events.d.ts

@@ -108,6 +108,14 @@ type ConflictProgressEvent = {
   filePath: string;
   iterations: number;
   remaining: number;
+} | {
+  type: 'fix:failed';
+  filePath?: string;
+  reason: string;
+} | {
+  type: 'fix:budget-exhausted';
+  spent: number;
+  limit: number;
 } | {
   type: 'verification:issues';
   filePath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitkraken/conflict-tools",
-  "version": "0.2.4-beta.17",
+  "version": "0.2.4-beta.18",
   "description": "AI-powered git conflict resolution.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Axosoft, LLC dba GitKraken",