@ipul-labs/forge 1.13.0

package/server/forge/core/ForgeAgent.js

@@ -0,0 +1,1144 @@
+/**
+ * server/forge/core/ForgeAgent.js
+ *
+ * Orchestrates the full Forge pipeline across one or more repositories.
+ *
+ *   analyzeIssue  → identify files across all repos → fetch contents → propose fix
+ *   applyFix      → group changes by repo → per repo: branch + commit + MR
+ *   refineIssue   → re-run pass 2 with feedback; reuses prior file paths per-repo
+ *   ciFixIssue    → target fix at CI failure logs
+ *
+ * Progress is reported via an optional onProgress callback so that
+ * the calling route can stream SSE events to the client.
+ *
+ * Multi-repo model
+ * ────────────────
+ * - `primaryProject` is the repo where the issue lives.
+ * - `secondaryProjects` are additional repos the fix can span (full-stack).
+ * - The AI sees every repo's file tree in pass 1 and tags files with repo id.
+ * - In pass 2 it proposes changes tagged with the repo they target.
+ * - `applyFix` groups by repo and creates one branch + MR per repo.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { checkResolution, identifyRelevantFiles, proposeFix, refineOrAsk } from "./agentClient.js";
+import { branchNameFor } from "./branchName.js";
+import * as configStore from "./configStore.js";
+import { ensureWorkingTree, overlayChanges } from "./localRepo.js";
+import { createProvider } from "./providers/index.js";
+import { reattributeChanges } from "./validator/attribute.js";
+
+/**
+ * Whether Refine should give the model real Read/Glob/Grep access to a local
+ * checkout of the primary repo. Primary control is the Settings UI flag
+ * (configStore.defaults.refineRepoAccess, default true). The
+ * FORGE_REFINE_REPO_ACCESS env var, when set, overrides the config — useful
+ * for forcing it on/off in CI or dev without touching the persisted config.
+ * Only honours GitLab primaries at runtime (matches validator/localRepo).
+ */
+function refineRepoAccessEnabled() {
+	const raw = process.env.FORGE_REFINE_REPO_ACCESS;
+	if (raw != null) {
+		const v = raw.trim().toLowerCase();
+		return !(v === "0" || v === "false" || v === "off" || v === "no");
+	}
+	return configStore.get().defaults?.refineRepoAccess ?? true;
+}
+
+function supportsLocalClone(repo) {
+	const colon = repo?.indexOf?.(":") ?? -1;
+	if (colon <= 0) return true;
+	return repo.slice(0, colon).toLowerCase() === "gitlab";
+}
+
+/**
+ * Heuristic: does this CLI error look like a missing/corrupt Claude session?
+ * We can't pattern-match on an exact string because the CLI wording drifts
+ * between versions — as of today it emits "No conversation found with session
+ * ID: <uuid>" for a missing resume, but older/newer builds have said "session
+ * not found" / "Unable to resume" / "expired". Match on session-specific
+ * vocabulary only so we don't fall back on unrelated failures like "Unknown
+ * model".
+ */
+function isLikelyResumeFailure(err) {
+	const msg = String(err?.message ?? err ?? "").toLowerCase();
+	return /session|resume|conversation|expired/.test(msg);
+}
+
+// ─── Types (JSDoc) ────────────────────────────────────────────────────────────
+/**
+ * @typedef {{ type: 'progress', step: string, message: string }} ProgressEvent
+ * @typedef {{ type: 'log', message: string }} LogEvent
+ * @typedef {{ type: 'result', data: AnalysisResult }} ResultEvent
+ * @typedef {{ type: 'error', message: string }} ErrorEvent
+ *
+ * @typedef {{
+ *   repo: string,
+ *   file: string,
+ *   action: 'create'|'modify'|'delete',
+ *   proposed: string,
+ *   original: string|null,
+ *   summary: string
+ * }} ForgeChange
+ *
+ * @typedef {{
+ *   issue: object,
+ *   mrTitle?: string,
+ *   explanation: string,
+ *   reasoning: string,
+ *   changes: ForgeChange[],
+ *   repos: string[]
+ * }} AnalysisResult
+ *
+ * @typedef {{
+ *   repo: string,
+ *   branchName: string,
+ *   mr: object|null,
+ *   pipelineUrl: string|null
+ * }} ApplicationResult
+ */
+
+const MAX_FILE_BYTES = 40_000;        // ~40 KB per file to keep the context window healthy
+const MAX_FILES_TOTAL = 12;           // hard cap across all repos
+const MAX_FILES_PER_REPO = 8;         // cap per repo so one repo can't starve another
+const CONV_PREFIX = /^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(?:\([^)]+\))?!?:\s*/i;
+
+/**
+ * Builds a conventional-commit subject line from the analysis. Prefers
+ * `analysis.mrTitle` (the model's own commit-style summary), falling back to
+ * the issue title with a `fix:` prefix when the model didn't supply one.
+ */
+function buildCommitSubject(analysis) {
+	const mrTitle = analysis.mrTitle?.trim();
+	if (mrTitle) return mrTitle;
+	return `fix: ${analysis.issue.title.replace(CONV_PREFIX, "")}`;
+}
+
+/**
+ * Assembles the full commit message: subject + per-file change list + trailers.
+ * Trailers let external tooling (and humans) identify Forge commits without
+ * parsing the subject line.
+ */
+function buildCommitMessage(subject, changes, analysis, mode) {
+	const body = changes.map((c) => `- ${c.file}: ${c.summary}`).join("\n");
+	const trailers = [
+		`Forge-Issue: #${analysis.issue.iid}`,
+		`Forge-Mode: ${mode}`,
+	].join("\n");
+	return `${subject}\n\n${body}\n\n${trailers}`;
+}
+
+/**
+ * Returns the progress-step copy for a given analysis kind.
+ *
+ *   "fresh"   — first analysis for an issue
+ *   "new"     — rerunning analysis after discarding a stored result
+ *   "update"  — re-analyzing because an MR already exists
+ *   "retry"   — retrying because a merged MR didn't actually resolve the issue
+ *
+ * Keeping the messaging here (not inlined) means each phase gets its own
+ * voice without the analyze function turning into a switch statement.
+ *
+ * @param {"fresh"|"new"|"update"|"retry"} kind
+ * @param {number} iid
+ * @param {string} agentLabel
+ * @param {string} [repoLine]  Extra " (repos: …)" suffix appended to the intro line.
+ */
+function buildStepMessages(kind, iid, agentLabel, repoLine = "") {
+	const files = (n) => `${n} file${n !== 1 ? "s" : ""}`;
+
+	switch (kind) {
+		case "new":
+			return {
+				intro: `Discarding stored analysis — starting fresh for issue #${iid}${repoLine}`,
+				fetch_issue: `Reloading issue #${iid} for a clean slate...`,
+				scan_repo: "Rescanning repository from scratch...",
+				identify_files: "Re-evaluating which files matter this time...",
+				fetch_files: (n) => `Re-pulling ${files(n)} at current main...`,
+				generate_fix: `Drafting a new fix with ${agentLabel}...`,
+			};
+		case "update":
+			return {
+				intro: `Updating existing MR for issue #${iid}${repoLine}`,
+				fetch_issue: `Loading issue #${iid} to update the open MR...`,
+				scan_repo: "Checking repository for drift since the last analysis...",
+				identify_files: "Selecting files that still need changes...",
+				fetch_files: (n) => `Loading ${files(n)} for the revised proposal...`,
+				generate_fix: `Revising the fix with ${agentLabel}...`,
+			};
+		case "retry":
+			return {
+				intro: `Retrying analysis for issue #${iid} — prior fix left it unresolved${repoLine}`,
+				fetch_issue: `Reloading issue #${iid} for a follow-up attempt...`,
+				scan_repo: "Rescanning repository with what we learned...",
+				identify_files: "Looking for files the first attempt missed...",
+				fetch_files: (n) => `Loading ${files(n)} for the retry...`,
+				generate_fix: `Attempting a different fix with ${agentLabel}...`,
+			};
+		case "fresh":
+		default:
+			return {
+				intro: `Analysis started for issue #${iid}${repoLine}`,
+				fetch_issue: `Fetching issue #${iid}...`,
+				scan_repo: "Scanning repository...",
+				identify_files: "Identifying relevant files...",
+				fetch_files: (n) => `Loading ${files(n)}...`,
+				generate_fix: `Generating fix with ${agentLabel}...`,
+			};
+	}
+}
+
+export class ForgeAgent {
+	/**
+	 * @param {{ project?: string, secondaryProjects?: string[], agent?: string }} [opts]
+	 */
+	constructor(opts = {}) {
+		const primary = opts.project ?? process.env.FORGE_GITLAB_PROJECT;
+		if (!primary) throw new Error("ForgeAgent requires a primary project.");
+
+		const secondaries = (opts.secondaryProjects ?? [])
+			.filter((p) => p && p !== primary);
+
+		this.primaryProject = primary;
+		this.secondaryProjects = [...new Set(secondaries)];
+		this.allRepos = [this.primaryProject, ...this.secondaryProjects];
+		this.agent = opts.agent ?? "claude";
+
+		/** @type {Map<string, import('./providers/base.js').ScmProvider>} */
+		this.providers = new Map();
+		for (const repo of this.allRepos) {
+			this.providers.set(repo, createProvider(repo));
+		}
+
+		// Back-compat: `this.provider` is the primary repo's provider.
+		this.provider = this.providers.get(this.primaryProject);
+	}
+
+	_provider(repo) {
+		const p = this.providers.get(repo);
+		if (!p) throw new Error(`ForgeAgent: no provider configured for repo "${repo}"`);
+		return p;
+	}
+
+	get _agentLabel() {
+		return this.agent === "openclaw" ? "OpenClaw" : "Claude";
+	}
+
+	get _isMultiRepo() {
+		return this.allRepos.length > 1;
+	}
+
+	// ─── Shared helpers ────────────────────────────────────────────────────────
+
+	async _fetchAllTrees(emit) {
+		const results = await Promise.all(
+			this.allRepos.map(async (repo) => {
+				try {
+					const files = await this._provider(repo).getFileTree("src", "main");
+					return { repo, files };
+				} catch (err) {
+					emit({ type: "log", message: `Could not scan ${repo}: ${err.message}` });
+					return { repo, files: [] };
+				}
+			}),
+		);
+		return results;
+	}
+
+	async _fetchFiles(entries, emit) {
+		const byRepo = new Map();
+		for (const entry of entries) {
+			const list = byRepo.get(entry.repo) ?? [];
+			list.push(entry.path);
+			byRepo.set(entry.repo, list);
+		}
+
+		const all = await Promise.all(
+			[...byRepo.entries()].map(async ([repo, paths]) => {
+				const provider = this._provider(repo);
+				return Promise.all(
+					paths.map(async (path) => {
+						try {
+							const content = await provider.getFileContent(path, "main");
+							const truncated = content.length > MAX_FILE_BYTES;
+							const body = truncated
+								? content.slice(0, MAX_FILE_BYTES) + "\n// [truncated — file exceeds size limit]"
+								: content;
+							const sizeKB = (content.length / 1024).toFixed(1);
+							emit({ type: "log", message: `Loaded ${repo}:${path} (${sizeKB} KB${truncated ? ", truncated" : ""})` });
+							return { repo, path, content: body };
+						} catch (err) {
+							emit({ type: "log", message: `Skipped ${repo}:${path}: ${err.message}` });
+							return null;
+						}
+					}),
+				);
+			}),
+		);
+		return all.flat().filter(Boolean);
+	}
+
+	/**
+	 * Normalises raw file entries coming back from the model.
+	 * The schema now asks for `{ repo, path }` objects, but older prompts /
+	 * smaller models occasionally return plain strings — default those to the
+	 * primary repo.
+	 */
+	_normalizeFileSelections(rawEntries) {
+		return (rawEntries ?? [])
+			.map((entry) => {
+				if (!entry) return null;
+				if (typeof entry === "string") return { repo: this.primaryProject, path: entry };
+				if (entry.path && entry.repo) return { repo: entry.repo, path: entry.path };
+				if (entry.path) return { repo: this.primaryProject, path: entry.path };
+				return null;
+			})
+			.filter(Boolean);
+	}
+
+	_validateSelections(entries, repoTrees) {
+		const treeSet = new Map(repoTrees.map((t) => [t.repo, new Set(t.files)]));
+		const valid = [];
+		const skipped = [];
+		const seen = new Set();
+		for (const { repo, path } of entries) {
+			const key = `${repo}::${path}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const set = treeSet.get(repo);
+			if (!set) { skipped.push(`${repo}:${path} (unknown repo)`); continue; }
+			if (!set.has(path)) { skipped.push(`${repo}:${path} (not in tree)`); continue; }
+			valid.push({ repo, path });
+		}
+		return { valid, skipped };
+	}
+
+	/** Enforces the per-repo and total caps, preserving model order. */
+	_capSelections(entries) {
+		const capped = [];
+		const perRepo = new Map();
+		for (const entry of entries) {
+			if (capped.length >= MAX_FILES_TOTAL) break;
+			const count = perRepo.get(entry.repo) ?? 0;
+			if (count >= MAX_FILES_PER_REPO) continue;
+			capped.push(entry);
+			perRepo.set(entry.repo, count + 1);
+		}
+		return capped;
+	}
+
+	_normalizeChanges(rawChanges, fileContents) {
+		return (rawChanges ?? []).map((change) => {
+			const repo = change.repo && this.allRepos.includes(change.repo)
+				? change.repo
+				: this.primaryProject;
+			const original = fileContents.find((f) => f.repo === repo && f.path === change.file)?.content ?? null;
+			return { ...change, repo, original };
+		});
+	}
+
+	// ─── Analyze ───────────────────────────────────────────────────────────────
+
+	/**
+	 * Runs the full analysis pipeline for an issue across all configured repos.
+	 *
+	 * @param {number} issueIid
+	 * @param {(event: ProgressEvent|LogEvent|ResultEvent|ErrorEvent) => void} [onProgress]
+	 * @param {string} [model]
+	 * @param {string} [ciContext]
+	 * @param {string} [userPrompt]
+	 * @returns {Promise<AnalysisResult>}
+	 */
+	async analyzeIssue(issueIid, onProgress, model, ciContext, userPrompt, kind = "fresh", opts = {}) {
+		const emit = onProgress ?? (() => {});
+		const { signal } = opts;
+
+		const repoLine = this._isMultiRepo
+			? ` (repos: ${this.allRepos.join(", ")})`
+			: "";
+		const msgs = buildStepMessages(kind, issueIid, this._agentLabel, repoLine);
+		emit({ type: "log", message: msgs.intro });
+
+		// Step 1 — fetch the issue from the primary repo
+		emit({ type: "progress", step: "fetch_issue", message: msgs.fetch_issue });
+		const issue = await this.provider.getIssue(issueIid);
+
+		// Step 2 — scan all repos in parallel
+		emit({
+			type: "progress",
+			step: "scan_repo",
+			message: this._isMultiRepo
+				? `Scanning ${this.allRepos.length} repositories...`
+				: msgs.scan_repo,
+		});
+		const repoTrees = await this._fetchAllTrees(emit);
+		for (const { repo, files } of repoTrees) {
+			emit({ type: "log", message: `${repo}: ${files.length} file${files.length !== 1 ? "s" : ""} in tree` });
+		}
+
+		// Step 3 — identify relevant files (Claude pass 1)
+		emit({ type: "progress", step: "identify_files", message: msgs.identify_files });
+		const ident = await identifyRelevantFiles(issue, repoTrees, model, this.agent, { signal });
+		const {
+			files: rawFiles,
+			reasoning = "",
+			cost: cost1 = 0,
+			serviceTier,
+			inputTokens: it1 = 0,
+			outputTokens: ot1 = 0,
+			cacheCreationTokens: cc1 = 0,
+			cacheReadTokens: cr1 = 0,
+		} = ident;
+
+		const normalized = this._normalizeFileSelections(rawFiles);
+		const { valid, skipped } = this._validateSelections(normalized, repoTrees);
+		const capped = this._capSelections(valid);
+
+		if (capped.length) {
+			emit({ type: "log", message: `Identified ${capped.length} file(s): ${capped.map((f) => `${f.repo}:${f.path}`).join(", ")}` });
+		} else {
+			emit({ type: "log", message: "No files identified — the model returned no valid selections." });
+		}
+		if (skipped.length) emit({ type: "log", message: `Skipped: ${skipped.join(", ")}` });
+		if (reasoning) emit({ type: "log", message: `Reasoning: ${reasoning}` });
+
+		// Step 4 — fetch file contents across repos
+		emit({
+			type: "progress",
+			step: "fetch_files",
+			message: msgs.fetch_files(capped.length),
+		});
+		const fileContents = await this._fetchFiles(capped, emit);
+
+		// Step 5 — propose fix (pass 2)
+		emit({ type: "progress", step: "generate_fix", message: msgs.generate_fix });
+		const propose = await proposeFix(
+			issue,
+			fileContents,
+			{ ciContext, userPrompt, repos: this.allRepos },
+			model,
+			this.agent,
+			{ signal },
+		);
+		const {
+			title: mrTitle,
+			explanation,
+			changes,
+			cost: cost2 = 0,
+			inputTokens: it2 = 0,
+			outputTokens: ot2 = 0,
+			cacheCreationTokens: cc2 = 0,
+			cacheReadTokens: cr2 = 0,
+			rateLimit: rl2 = null,
+		} = propose;
+
+		const enrichedChanges = this._normalizeChanges(changes, fileContents);
+		emit({
+			type: "log",
+			message: `Proposed ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+		});
+
+		const result = {
+			issue,
+			mrTitle,
+			explanation,
+			reasoning,
+			changes: enrichedChanges,
+			repos: this.allRepos,
+		};
+		emit({ type: "result", data: result });
+		emit({
+			type: "usage",
+			cost: cost1 + cost2,
+			serviceTier: serviceTier ?? "unknown",
+			inputTokens: it1 + it2,
+			outputTokens: ot1 + ot2,
+			cacheCreationTokens: cc1 + cc2,
+			cacheReadTokens: cr1 + cr2,
+			// Most recent rate-limit snapshot wins (pass 2 is last).
+			rateLimit: rl2 ?? ident.rateLimit ?? null,
+		});
+		return result;
+	}
+
+	// ─── Refine ────────────────────────────────────────────────────────────────
+
+	/**
+	 * Re-runs pass 2 with reviewer feedback and the prior proposed changes as
+	 * additional context. Reuses the previous files (per-repo) — no new file
+	 * discovery.
+	 */
+	async refineIssue(issueIid, previousChanges, feedback, onProgress, model, ciContext, validationState, claudeSessionId, opts = {}) {
+		const emit = onProgress ?? (() => {});
+		const { signal } = opts;
+
+		// Session continuity: only the user-feedback refine path on Claude carries
+		// a multi-turn session. CI-fix refines route through proposeFix (stateless)
+		// and OpenClaw has no session API. Generate a fresh UUID for turn 1 so we
+		// own the id from the start and can --resume it on turn 2+.
+		const useSession = this.agent === "claude" && !ciContext;
+		const resumeSession = Boolean(useSession && claudeSessionId);
+		const sessionId = useSession ? (claudeSessionId || randomUUID()) : null;
+
+		emit({ type: "progress", step: "fetch_issue", message: `Fetching issue #${issueIid}...` });
+		const issue = await this.provider.getIssue(issueIid);
+
+		// Pull the unique (repo, path) pairs from the previous changes.
+		const uniq = new Map();
+		for (const c of previousChanges ?? []) {
+			const repo = c.repo && this.allRepos.includes(c.repo) ? c.repo : this.primaryProject;
+			const key = `${repo}::${c.file}`;
+			if (!uniq.has(key)) uniq.set(key, { repo, path: c.file });
+		}
+		const selections = [...uniq.values()];
+
+		emit({
+			type: "progress",
+			step: "fetch_files",
+			message: `Loading ${selections.length} file${selections.length !== 1 ? "s" : ""}...`,
+		});
+		const fileContents = await this._fetchFiles(selections, emit);
+
+		// CI-context refines are always directive (the failure logs describe what
+		// broke), so skip classification and go straight through proposeFix. This
+		// keeps the CI-fix loop tight and avoids an "answer" being emitted when
+		// the caller expects fresh changes.
+		if (ciContext) {
+			emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+			const propose = await proposeFix(
+				issue,
+				fileContents,
+				{ feedback, previousChanges, ciContext, repos: this.allRepos },
+				model,
+				this.agent,
+				{ signal },
+			);
+			return this._emitRefineResult(propose, fileContents, issue, emit, "ci-fix");
+		}
+
+		// Give the refine model access to the full primary repo: prepare a local
+		// clone with previousChanges overlaid and hand Claude Read/Glob/Grep via
+		// cwd. Falls back to the lighter "file tree only" path when disabled,
+		// when using a non-Claude agent, or when the primary repo isn't GitLab
+		// (validator/localRepo are GitLab-only for now).
+		let repoCwd = null;
+		let repoTrees = null;
+		const canUseLocalClone =
+			refineRepoAccessEnabled()
+			&& this.agent !== "openclaw"
+			&& supportsLocalClone(this.primaryProject);
+
+		if (canUseLocalClone) {
+			try {
+				emit({ type: "progress", step: "prepare_repo", message: `Preparing local checkout of ${this.primaryProject}...` });
+				const branchName = branchNameFor(issue.iid, { issue });
+				const dir = await ensureWorkingTree(
+					this.primaryProject,
+					branchName,
+					(msg) => emit({ type: "log", message: msg }),
+				);
+				const primaryChanges = (previousChanges ?? []).filter(
+					(c) => (c.repo ?? this.primaryProject) === this.primaryProject,
+				);
+				if (primaryChanges.length) {
+					await overlayChanges(
+						dir,
+						primaryChanges,
+						(msg) => emit({ type: "log", message: msg }),
+					);
+				}
+				repoCwd = dir;
+				emit({ type: "log", message: `Refine session has Read/Glob/Grep access at ${dir}` });
+			} catch (err) {
+				emit({ type: "log", message: `Could not prepare local checkout (${err.message}); falling back to file-tree mode.` });
+				repoCwd = null;
+			}
+		}
+
+		if (!repoCwd) {
+			try {
+				repoTrees = await this._fetchAllTrees(emit);
+			} catch (err) {
+				emit({ type: "log", message: `Could not scan repo trees: ${err.message}` });
+			}
+		}
+
+		emit({ type: "progress", step: "generate_fix", message: `Refining fix with ${this._agentLabel}...` });
+		if (sessionId) emit({ type: "session", sessionId, resumed: resumeSession });
+
+		const callRefine = (sid, resume) =>
+			refineOrAsk(
+				issue,
+				fileContents,
+				{
+					feedback,
+					previousChanges,
+					validationState,
+					repos: this.allRepos,
+					repoCwd,
+					repoTrees,
+					repoAccessMode: repoCwd ? "tools" : "tree",
+					...(sid ? { sessionId: sid, resumeSession: resume } : {}),
+				},
+				model,
+				this.agent,
+				(evt) => emit(evt),
+				{ signal },
+			);
+
+		let activeSessionId = sessionId;
+		let response;
+		try {
+			response = await callRefine(activeSessionId, resumeSession);
+		} catch (err) {
+			// Resume failures (session pruned by the CLI, format drift after an
+			// upgrade, crashed half-turn leaving the session unreadable) should
+			// not kill the user's refine. Regenerate the session, tell the
+			// frontend to adopt the new id, and retry once with the full prompt.
+			if (resumeSession && isLikelyResumeFailure(err)) {
+				const fresh = randomUUID();
+				emit({ type: "log", message: `Could not resume Claude session ${activeSessionId} (${err.message}). Starting fresh session ${fresh}.` });
+				activeSessionId = fresh;
+				emit({ type: "session", sessionId: fresh, resumed: false });
+				response = await callRefine(fresh, false);
+			} else {
+				throw err;
+			}
+		}
+
+		// CLI sometimes forks on resume and returns a different session id than
+		// the one we passed. Re-emit so the frontend persists the authoritative
+		// id — otherwise next refine would --resume a stale handle.
+		if (response?.sessionId && response.sessionId !== activeSessionId) {
+			emit({ type: "log", message: `Claude session forked: ${activeSessionId} → ${response.sessionId}` });
+			activeSessionId = response.sessionId;
+			emit({ type: "session", sessionId: activeSessionId, resumed: false });
+		}
+
+		const {
+			kind,
+			answer,
+			cost = 0,
+			serviceTier,
+			inputTokens = 0,
+			outputTokens = 0,
+			cacheCreationTokens = 0,
+			cacheReadTokens = 0,
+			rateLimit = null,
+		} = response;
+
+		const usageEvent = {
+			type: "usage",
+			cost,
+			serviceTier: serviceTier ?? "unknown",
+			inputTokens,
+			outputTokens,
+			cacheCreationTokens,
+			cacheReadTokens,
+			rateLimit,
+		};
+
+		if (kind === "answer") {
+			const text = answer?.trim() || "(no answer produced)";
+			emit({ type: "log", message: "Refine classified as question — responding without changing code." });
+			emit({ type: "answer", text });
+			emit(usageEvent);
+			return { kind: "answer", answer: text };
+		}
+
+		// kind === "refine" (default to this if the model omitted kind but gave changes)
+		return this._emitRefineResult(
+			{ ...response, title: response.title, explanation: answer },
+			fileContents,
+			issue,
+			emit,
+			"refine",
+		);
+	}
+
+	/**
+	 * Shared tail for both ciFix-style proposeFix results and directive refine
+	 * results: normalises changes, emits the result + usage events, and returns
+	 * the AnalysisResult so callers can still await it.
+	 */
+	_emitRefineResult(propose, fileContents, issue, emit, label) {
+		const {
+			title: mrTitle,
+			explanation,
+			changes,
+			cost = 0,
+			serviceTier,
+			inputTokens = 0,
+			outputTokens = 0,
+			cacheCreationTokens = 0,
+			cacheReadTokens = 0,
+			rateLimit = null,
+		} = propose;
+
+		const enrichedChanges = this._normalizeChanges(changes, fileContents);
+		emit({
+			type: "log",
+			message: `${label === "ci-fix" ? "CI fix" : "Refined"} to ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+		});
+
+		const result = {
+			issue,
+			mrTitle,
+			explanation: explanation ?? "",
+			reasoning: "",
+			changes: enrichedChanges,
+			repos: this.allRepos,
+		};
+		emit({ type: "result", data: result });
+		emit({
+			type: "usage",
+			cost,
+			serviceTier: serviceTier ?? "unknown",
+			inputTokens,
+			outputTokens,
+			cacheCreationTokens,
+			cacheReadTokens,
+			rateLimit,
+		});
+		return result;
+	}
+
+	// ─── CI Fix ────────────────────────────────────────────────────────────────
+
+	/**
+	 * Targeted fix for a CI pipeline failure. Uses the CI logs as the primary
+	 * signal for file selection instead of the issue description.
+	 */
+	async ciFixIssue(issueIid, ciContext, onProgress, model, opts = {}) {
+		const emit = onProgress ?? (() => {});
+		const { signal } = opts;
+		emit({ type: "log", message: `CI fix started for issue #${issueIid}` });
+
+		emit({ type: "progress", step: "fetch_issue", message: `Fetching issue #${issueIid}...` });
+		const issue = await this.provider.getIssue(issueIid);
+
+		emit({ type: "progress", step: "scan_repo", message: "Scanning repositories..." });
+		const repoTrees = await this._fetchAllTrees(emit);
+
+		emit({ type: "progress", step: "identify_files", message: "Identifying files from CI failure..." });
+		const ciIssue = { ...issue, description: `CI pipeline failure:\n\n${ciContext}` };
+		const ident = await identifyRelevantFiles(ciIssue, repoTrees, model, this.agent, { signal });
+		const {
+			files: rawFiles,
+			cost: cost1 = 0,
+			serviceTier,
+			inputTokens: it1 = 0,
+			outputTokens: ot1 = 0,
+			cacheCreationTokens: cc1 = 0,
+			cacheReadTokens: cr1 = 0,
+		} = ident;
+
+		const { valid } = this._validateSelections(this._normalizeFileSelections(rawFiles), repoTrees);
+		const capped = this._capSelections(valid);
+
+		emit({
+			type: "progress",
+			step: "fetch_files",
+			message: `Loading ${capped.length} file${capped.length !== 1 ? "s" : ""}...`,
+		});
+		const fileContents = await this._fetchFiles(capped, emit);
+
+		emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+		const propose = await proposeFix(
+			issue,
+			fileContents,
+			{ ciContext, repos: this.allRepos },
+			model,
+			this.agent,
+			{ signal },
+		);
+		const {
+			title: mrTitle,
+			explanation,
+			changes,
+			cost: cost2 = 0,
+			inputTokens: it2 = 0,
+			outputTokens: ot2 = 0,
+			cacheCreationTokens: cc2 = 0,
+			cacheReadTokens: cr2 = 0,
+			rateLimit: rl2 = null,
+		} = propose;
+
+		const enrichedChanges = this._normalizeChanges(changes, fileContents);
+		emit({
+			type: "log",
+			message: `Proposed ${enrichedChanges.length} change(s): ${enrichedChanges.map((c) => `${c.repo}:${c.file} (${c.action})`).join(", ")}`,
+		});
+
+		const result = {
+			issue,
+			mrTitle,
+			explanation,
+			reasoning: "",
+			changes: enrichedChanges,
+			repos: this.allRepos,
+		};
+		emit({ type: "result", data: result });
+		emit({
+			type: "usage",
+			cost: cost1 + cost2,
+			serviceTier: serviceTier ?? "unknown",
+			inputTokens: it1 + it2,
+			outputTokens: ot1 + ot2,
+			cacheCreationTokens: cc1 + cc2,
+			cacheReadTokens: cr1 + cr2,
+			rateLimit: rl2 ?? ident.rateLimit ?? null,
+		});
+		return result;
+	}
+
+	// ─── Resolution check ──────────────────────────────────────────────────────
+
+	/**
+	 * Asks the model whether the diffs in a merged MR actually fix the issue.
+	 * The issue lives in the primary repo; the MR is fetched from whichever
+	 * provider created it.
+	 */
+	async checkResolution(issueIid, mrIid, repo = this.primaryProject) {
+		const provider = this._provider(repo);
+		const [issue, diffs] = await Promise.all([
+			this.provider.getIssue(issueIid),
+			provider.getMRDiffs(mrIid),
+		]);
+		return checkResolution(issue, diffs, undefined, this.agent);
+	}
+
+	// ─── Apply ─────────────────────────────────────────────────────────────────
+
+	/**
+	 * Applies an approved analysis: creates one branch + commit + MR per repo
+	 * that has changes. Primary repo is always processed first so its MR exists
+	 * before any secondary MRs that cross-reference it.
+	 *
+	 * @param {AnalysisResult} analysis
+	 * @returns {Promise<{ applications: ApplicationResult[] }>}
+	 */
+	async applyFix(analysis) {
+		// The model's `c.repo` is occasionally wrong (a `.go` file routed to a
+		// Node primary by the normalize fallback). Reattribute against the SCM
+		// API before grouping so we never try to commit a file to a repo that
+		// doesn't have it.
+		const corrected = await this._correctAttribution(analysis.changes);
+		const grouped = this._groupChangesByRepo(corrected);
+		if (grouped.size === 0) {
+			throw new Error("No changes to apply.");
+		}
+
+		const ordered = this._orderedRepos(grouped);
+		const applications = [];
+
+		for (const repo of ordered) {
+			const changes = grouped.get(repo);
+			const app = await this._applyToRepo(repo, changes, analysis, applications);
+			applications.push(app);
+		}
+
+		return { applications };
+	}
+
+	/**
+	 * Pushes a new commit to an existing branch in a specific repo (e.g. to fix
+	 * a failing pipeline without creating a new MR). Only affects the one repo.
+	 *
+	 * @param {string} branchName
+	 * @param {AnalysisResult} analysis
+	 * @param {string} [repo]  Defaults to primary.
+	 */
+	async commitToBranch(branchName, analysis, repo = this.primaryProject) {
+		const corrected = await this._correctAttribution(analysis.changes);
+		const grouped = this._groupChangesByRepo(corrected);
+		const changes = grouped.get(repo);
+		if (!changes?.length) {
+			throw new Error(`No changes for repo "${repo}" to commit.`);
+		}
+
+		const provider = this._provider(repo);
+		const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed }));
+		const subject = buildCommitSubject(analysis);
+		const commitMessage = buildCommitMessage(subject, changes, analysis, "ci-fix");
+
+		await provider.commitFiles(branchName, commitMessage, actions);
+		return { repo, branchName };
+	}
+
+	/**
+	 * Opens an MR for a branch that was previously pushed via deployBranch.
+	 * Used when a test-deploy pipeline goes green and the user wants to promote
+	 * the change to a real MR.
+	 *
+	 * @param {string} branchName
+	 * @param {string} repo
+	 * @param {number} issueIid
+	 * @returns {Promise<ApplicationResult>}
+	 */
+	async promoteBranchToMR(branchName, repo, issueIid) {
+		const targetRepo = repo && this.allRepos.includes(repo) ? repo : this.primaryProject;
+		const provider = this._provider(targetRepo);
+		const isPrimary = targetRepo === this.primaryProject;
+
+		// Refuse to open an MR that has nothing to merge. `compareRefs` returns
+		// `null` on providers that can't answer, which we treat as "allowed" so
+		// we don't block GitHub/Azure until they implement it.
+		const cmp = await provider.compareRefs("main", branchName);
+		if (cmp && cmp.aheadCount === 0) {
+			throw new Error(
+				`Branch \`${branchName}\` has no commits ahead of main — nothing to promote.`,
+			);
+		}
+
+		const issue = await this._provider(this.primaryProject).getIssue(issueIid);
+		const rawTitle = issue.title.replace(CONV_PREFIX, "");
+		const subject = `fix: ${rawTitle}`;
+		const mrTitle = this._isMultiRepo
+			? `${subject} [${this._repoShortLabel(targetRepo)}]`
+			: subject;
+
+		const linkedIssue = isPrimary
+			? `Closes #${issueIid}`
+			: `Relates to ${this.primaryProject}#${issueIid}`;
+		const description = `## 🎯 Summary
+
+Promoted to MR from test-deploy branch \`${branchName}\` after the branch pipeline went green.
+
+${linkedIssue}
+
+---
+
+_Opened by Forge._`;
+
+		const mr = await this._ensureMR(provider, {
+			sourceBranch: branchName,
+			targetBranch: "main",
+			title: mrTitle,
+			description,
+			labels: ["forge", `forge:issue-${issueIid}`],
+		});
+
+		let pipelineUrl = null;
+		try {
+			const pipelines = await provider.getMRPipelines(mr.iid);
+			pipelineUrl = pipelines[0]?.web_url ?? null;
+		} catch {
+			// Pipeline lookup is best-effort.
+		}
+
+		return { repo: targetRepo, branchName, mr, pipelineUrl };
+	}
+
+	/**
+	 * Pushes a fix as a new branch per repo without opening MRs. Used for the
+	 * "Deploy to Test" flow where a branch pipeline deploys to a test namespace.
+	 *
+	 * @param {AnalysisResult} analysis
+	 * @returns {Promise<{ applications: ApplicationResult[] }>}
+	 */
+	async deployBranch(analysis) {
+		const corrected = await this._correctAttribution(analysis.changes);
+		const grouped = this._groupChangesByRepo(corrected);
+		if (grouped.size === 0) throw new Error("No changes to deploy.");
+
+		const ordered = this._orderedRepos(grouped);
+		const applications = [];
+		const branchName = branchNameFor(analysis.issue.iid, analysis);
+
+		for (const repo of ordered) {
+			const changes = grouped.get(repo);
+			const provider = this._provider(repo);
+
+			await this._ensureBranch(provider, branchName, "main");
+
+			const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed }));
+			const subject = buildCommitSubject(analysis);
+			const commitMessage = buildCommitMessage(subject, changes, analysis, "deploy-to-test");
+			await provider.commitFiles(branchName, commitMessage, actions);
+
+			let pipelineUrl = null;
+			try {
+				const pipelines = await provider.getPipelinesByRef(branchName);
+				pipelineUrl = pipelines[0]?.web_url ?? null;
+			} catch {
+				// Pipeline may not have kicked off yet — non-fatal.
+			}
+
+			applications.push({ repo, branchName, mr: null, pipelineUrl });
+		}
+
+		return { applications };
+	}
+
+	// ─── Private apply helpers ─────────────────────────────────────────────────
+
+	/**
+	 * Resolves each change's `repo` against the SCM (does the file actually
+	 * exist there?) so we don't try to commit to the wrong repo when the
+	 * model omitted or guessed `c.repo` wrong. Mirror of the validator's
+	 * auto-attribution; returns a flat changes array with corrected repo.
+	 * Falls back to the input on attribution failure so we never block apply
+	 * on a flaky API call.
+	 */
+	async _correctAttribution(changes) {
+		try {
+			const { changes: corrected, unattributed } = await reattributeChanges(changes ?? [], this.allRepos);
+			if (unattributed.length) {
+				console.warn(
+					`[forge] Dropping ${unattributed.length} unattributable change(s):`,
+					unattributed.map((c) => c.file).join(", "),
+				);
+			}
+			return corrected;
+		} catch (err) {
+			console.warn("[forge] Attribution lookup failed, using model-supplied repo:", err?.message ?? err);
+			return changes ?? [];
+		}
+	}
+
+	_groupChangesByRepo(changes) {
+		const grouped = new Map();
+		for (const change of changes ?? []) {
+			const repo = change.repo && this.allRepos.includes(change.repo)
+				? change.repo
+				: this.primaryProject;
+			const list = grouped.get(repo) ?? [];
+			list.push(change);
+			grouped.set(repo, list);
+		}
+		return grouped;
+	}
+
+	/** Primary always first, secondaries after in allRepos order. */
+	_orderedRepos(grouped) {
+		const present = new Set(grouped.keys());
+		return this.allRepos.filter((r) => present.has(r));
+	}
+
+	async _applyToRepo(repo, changes, analysis, priorApplications) {
+		const provider = this._provider(repo);
+		const { issue, explanation } = analysis;
+		const branchName = branchNameFor(issue.iid, analysis);
+
+		await this._ensureBranch(provider, branchName, "main");
+
+		const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed }));
+		const subject = buildCommitSubject(analysis);
+		const commitMessage = buildCommitMessage(subject, changes, analysis, "mr");
+		await provider.commitFiles(branchName, commitMessage, actions);
+
+		const isPrimary = repo === this.primaryProject;
+		const mrTitle = this._isMultiRepo
+			? `${subject} [${this._repoShortLabel(repo)}]`
+			: subject;
+
+		const mrDescription = this._buildMRDescription(issue, explanation, changes, {
+			isPrimary,
+			repo,
+			priorApplications,
+		});
+
+		const mr = await this._ensureMR(provider, {
+			sourceBranch: branchName,
+			targetBranch: "main",
+			title: mrTitle,
+			description: mrDescription,
+			labels: ["forge", `forge:issue-${issue.iid}`],
+		});
+
+		let pipelineUrl = null;
+		try {
+			const pipelines = await provider.getMRPipelines(mr.iid);
+			pipelineUrl = pipelines[0]?.web_url ?? null;
+		} catch {
+			// Pipeline may not have kicked off yet — non-fatal.
+		}
+
+		return { repo, branchName, mr, pipelineUrl };
+	}
+
+	/**
+	 * Creates a branch, tolerating the case where it already exists — the whole
+	 * point of intent-based names is that multiple applies/refines reuse the
+	 * same branch. GitLab returns 400 "Branch already exists"; other providers
+	 * may use different strings, so we match loosely.
+	 */
+	async _ensureBranch(provider, branchName, ref) {
+		try {
+			return await provider.createBranch(branchName, ref);
+		} catch (err) {
+			if (/already exists/i.test(err?.message ?? "")) return null;
+			throw err;
+		}
+	}
+
+	/**
+	 * Opens an MR for the given branch, or returns the existing open one if
+	 * the user is re-applying to a branch that already has an MR attached.
+	 * Source-branch match is exact; label updates are intentionally skipped on
+	 * the reuse path to keep this idempotent.
+	 */
+	async _ensureMR(provider, mrSpec) {
+		try {
+			return await provider.createMR(mrSpec);
+		} catch (err) {
+			if (!/already|exist/i.test(err?.message ?? "")) throw err;
+			const open = await provider.listAllForgeMRs();
+			const match = open.find((mr) => mr.source_branch === mrSpec.sourceBranch);
+			if (match) return match;
+			throw err;
+		}
+	}
+
+	_repoShortLabel(repo) {
+		return repo.split("/").pop() || repo;
+	}
+
+	_buildMRDescription(issue, explanation, changes, opts = {}) {
+		const { isPrimary = true, repo = this.primaryProject, priorApplications = [] } = opts;
+
+		const changeList = changes
+			.map((c) => `- **${c.file}** (${c.action}): ${c.summary}`)
+			.join("\n");
+
+		const linkedIssue = isPrimary
+			? `Closes #${issue.iid}`
+			: `Relates to ${this.primaryProject}#${issue.iid}`;
+
+		let companionBlock = "";
+		if (this._isMultiRepo) {
+			const companions = priorApplications
+				.filter((a) => a.mr && a.repo !== repo)
+				.map((a) => `- [${a.repo}!${a.mr.iid}](${a.mr.web_url}) — ${this._repoShortLabel(a.repo)}`);
+			const heading = "## 🔗 Companion MRs";
+			if (companions.length) {
+				companionBlock = `\n\n${heading}\n\nThis is part of a full-stack change spanning multiple repositories.\n\n${companions.join("\n")}`;
+			} else {
+				companionBlock = `\n\n${heading}\n\nThis is part of a full-stack change — companion MRs will be posted in other repos.`;
+			}
+		}
+
+		return `## 🎯 Summary
+
+Automated fix for ${this.primaryProject}#${issue.iid} generated by Forge.
+
+${explanation}
+
+${linkedIssue}${companionBlock}
+
+## ✨ Changes (${this._repoShortLabel(repo)})
+
+${changeList}
+
+## 🧪 Testing
+
+- ⏳ Automated CI pipeline
+- ⏳ Manual review of diff before merge
+
+---
+
+_Generated by [Forge](https://iplayulisten.com/admin/forge)_`;
+	}
+}