@ipul-labs/forge 1.16.8 → 1.17.0

package/server/forge/core/ForgeAgent.js

@@ -1,1179 +0,0 @@
-/**
- * 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 { classifyIssue } from "./prompts.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 CONV_PREFIX = /^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(?:\([^)]+\))?!?:\s*/i;
-
-const FILE_CAPS = {
-	feature:  { total: 18, perRepo: 15 },
-	refactor: { total: 18, perRepo: 15 },
-	fix:      { total: 12, perRepo: 8 },
-	chore:    { total: 12, perRepo: 8 },
-};
-
-/**
- * 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 prefix derived from the issue kind.
- */
-function buildCommitSubject(analysis) {
-	const mrTitle = analysis.mrTitle?.trim();
-	if (mrTitle) return mrTitle;
-	const kind = classifyIssue(analysis.issue);
-	const prefix = kind === "feature" ? "feat" : kind === "refactor" ? "refactor" : "fix";
-	return `${prefix}: ${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 ?? configStore.getPrimaryProject();
-		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("", "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, issueKind) {
-		const caps = FILE_CAPS[issueKind] ?? FILE_CAPS.fix;
-		const capped = [];
-		const perRepo = new Map();
-		for (const entry of entries) {
-			if (capped.length >= caps.total) break;
-			const count = perRepo.get(entry.repo) ?? 0;
-			if (count >= caps.perRepo) 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 = {}, previousChanges = null) {
-		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 issueKind = classifyIssue(issue);
-		emit({ type: "log", message: `Issue classified as: ${issueKind}` });
-
-		const normalized = this._normalizeFileSelections(rawFiles);
-		const { valid, skipped } = this._validateSelections(normalized, repoTrees);
-		const capped = this._capSelections(valid, issueKind);
-
-		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 promptRules = configStore.get().defaults?.promptRules || "";
-		const propose = await proposeFix(
-			issue,
-			fileContents,
-			{ ciContext, userPrompt, previousChanges, repos: this.allRepos, promptRules },
-			model,
-			this.agent,
-			{ signal },
-		);
-		const {
-			title: mrTitle,
-			explanation,
-			changes,
-			removals = [],
-			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(", ")}`,
-		});
-		if (removals.length > 0) {
-			emit({
-				type: "log",
-				message: `⚠ ${removals.length} removal(s) declared: ${removals.map((r) => `${r.file}: ${r.what}`).join("; ")}`,
-			});
-		}
-
-		const result = {
-			issue,
-			mrTitle,
-			explanation,
-			reasoning,
-			changes: enrichedChanges,
-			removals,
-			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 ciRefineRules = configStore.get().defaults?.promptRules || "";
-			const propose = await proposeFix(
-				issue,
-				fileContents,
-				{ feedback, previousChanges, ciContext, repos: this.allRepos, promptRules: ciRefineRules },
-				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 refinePromptRules = configStore.get().defaults?.promptRules || "";
-		const callRefine = (sid, resume) =>
-			refineOrAsk(
-				issue,
-				fileContents,
-				{
-					feedback,
-					previousChanges,
-					validationState,
-					repos: this.allRepos,
-					repoCwd,
-					repoTrees,
-					repoAccessMode: repoCwd ? "tools" : "tree",
-					promptRules: refinePromptRules,
-					...(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, "fix");
-
-		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 ciPromptRules = configStore.get().defaults?.promptRules || "";
-		const propose = await proposeFix(
-			issue,
-			fileContents,
-			{ ciContext, repos: this.allRepos, promptRules: ciPromptRules },
-			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);
-
-		// Rebase onto latest main before pushing so CI runs against current code.
-		try {
-			const mrs = await provider.listAllForgeMRs();
-			const mr = mrs.find((m) => m.source_branch === branchName);
-			if (mr && provider.supportsRebase) {
-				await provider.rebaseMR(mr.iid);
-			}
-		} catch { /* rebase failure is non-fatal — push will still work */ }
-
-		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)_`;
-	}
-}