@sctg/backport-agent 0.1.0-20260529153002

package/dist/main.mjs

@@ -0,0 +1,2741 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { Agent, createBuiltinTools, createUserInstructionConfigService } from "@sctg/cline-sdk";
+import { z } from "zod";
+import yaml from "js-yaml";
+import { minimatch } from "minimatch";
+import { createTool } from "@sctg/cline-agents";
+import { execFileSync } from "node:child_process";
+import { Octokit } from "@octokit/rest";
+//#region src/config/schema.ts
+/**
+* @file config/schema.ts
+*
+* Zod schema for the agent's main configuration file (config.json).
+* All fields are validated and typed at load time via `SyncConfigSchema.parse()`.
+*
+* The top-level object is divided into five sections:
+*  - `upstream`   – coordinates of the original repository being tracked
+*  - `fork`       – coordinates of the customised fork maintained by this agent
+*  - `workingDir` – filesystem location of the local checkout
+*  - `auth`       – git authentication (SSH key or HTTP bearer token)
+*  - `sync`       – behavioural knobs (commit limits, dry-run mode, branch names…)
+*  - `customizations` – inline or external customizations manifest (optional)
+*  - `models`     – LLM model identifiers used for cheap vs. powerful inference
+*  - `validation` – shell commands executed after cherry-picking, grouped by risk level
+*/
+/**
+* Full Zod validation schema for the backport-agent configuration.
+*
+* All nested objects have sensible defaults so that a minimal config.json only
+* needs to specify `upstream`, `fork`, and `workingDir`.
+*
+* **Important — Zod v4 `.default()` behaviour:**
+* When an entire sub-object is optional, we use `.default(() => ({} as any))`.
+* The factory form `() => value` is required by Zod v4 (unlike v3's plain value form).
+* The `as any` cast is intentional: each individual field already carries its own
+* `.default(…)`, so Zod will fill in all missing keys automatically; the outer
+* `{}` is just an empty trigger that lets the field-level defaults take effect.
+*/
+var SyncConfigSchema = z.object({
+	/**
+	* Coordinates of the upstream (canonical) repository.
+	* The agent fetches from this remote and picks commits out of it.
+	*/
+	upstream: z.object({
+		/** GitHub repository in `owner/repo` format, e.g. `"cline/cline"`. */
+		repo: z.string().describe("owner/repo of the upstream repository"),
+		/**
+		* Full git URL for the upstream remote, e.g. `"git@github.com:org/repo.git"` (SSH)
+		* or `"https://github.com/org/repo.git"` (HTTPS).
+		* Required when the working directory does not yet exist (for auto-clone setup).
+		* Supports any git hosting provider, not just GitHub.
+		*/
+		url: z.string().optional().describe("Full git URL (SSH or HTTPS) for the upstream remote"),
+		/** Branch on the upstream repo that the agent tracks, e.g. `"main"`. */
+		branch: z.string().describe("Upstream branch to sync from"),
+		/** Local git remote name pointing to the upstream repo. Defaults to `"upstream"`. */
+		remote: z.string().default("upstream").describe("Git remote name for upstream")
+	}),
+	/**
+	* Coordinates of the fork (customised) repository.
+	* This is where new sync branches are pushed and PRs are opened.
+	*/
+	fork: z.object({
+		/** GitHub repository in `owner/repo` format, e.g. `"TEA-ching/cline"`. */
+		repo: z.string().describe("owner/repo of the fork"),
+		/**
+		* Full git URL for cloning the fork, e.g. `"git@github.com:myuser/repo.git"` (SSH)
+		* or `"https://github.com/myuser/repo.git"` (HTTPS).
+		* If the working directory does not exist the agent will clone this URL automatically.
+		* Supports any git hosting provider, not just GitHub.
+		*/
+		url: z.string().optional().describe("Full git URL (SSH or HTTPS) used to clone the fork"),
+		/** Target branch in the fork that sync commits are based on, e.g. `"main"`. */
+		branch: z.string().describe("Fork branch to sync into"),
+		/** Local git remote name pointing to the fork. Defaults to `"origin"`. */
+		remote: z.string().default("origin").describe("Git remote name for the fork")
+	}),
+	/**
+	* Absolute filesystem path to the local git clone of the fork.
+	* All git operations are executed with this path as the working directory.
+	* Example: `"/home/ci/repos/my-fork"`.
+	* If the directory does not exist and `fork.url` is set, the agent will
+	* clone the fork automatically on startup.
+	*/
+	workingDir: z.string().describe("Absolute path to the local clone of the fork"),
+	/**
+	* Git authentication credentials.
+	*
+	* Exactly one of `sshKeyPath` or `githubToken` should be set:
+	*  - `sshKeyPath`   — path to an SSH private key; sets `GIT_SSH_COMMAND` for all git calls.
+	*    Supports `~` expansion.  Example: `"~/.ssh/id_ed25519"`.
+	*  - `githubToken`  — bearer token for HTTPS remotes (GitHub PAT, GitLab token, etc.);
+	*    injected via `http.extraHeader`.  Works with any git hosting provider.
+	*    For security, prefer referencing an environment variable with the `$VAR` syntax
+	*    (e.g. `"$GITHUB_TOKEN"`) instead of embedding the raw token.  If omitted, the
+	*    agent falls back to the `GITHUB_TOKEN` environment variable automatically.
+	*
+	* Both fields are optional — omit this section if git is already authenticated
+	* through the system SSH agent or a credential helper.
+	*/
+	auth: z.object({
+		/**
+		* Absolute (or `~`-prefixed) path to the SSH private key.
+		* Example: `"~/.ssh/id_ed25519"` or `"/home/ci/.ssh/deploy_key"`.
+		*/
+		sshKeyPath: z.string().optional().describe("Path to the SSH private key (supports ~ expansion)"),
+		/**
+		* Bearer token for HTTPS authentication.
+		* Prefix with `$` to read from an environment variable at runtime
+		* (e.g. `"$GITHUB_TOKEN"`), which avoids storing the secret in config.json.
+		*/
+		githubToken: z.string().optional().describe("HTTP bearer token; use \"$ENV_VAR\" syntax to read from an environment variable")
+	}).default(() => ({})),
+	/**
+	* Runtime behaviour settings for the sync loop.
+	* All fields have defaults, so this entire section is optional in config.json.
+	*/
+	sync: z.object({
+		/**
+		* Maximum number of agent loop iterations per run.
+		* Each iteration is one model turn (potentially invoking several tools in parallel).
+		* Increase this value for large repos or runs with many conflict resolutions.
+		* Defaults to 200.
+		*/
+		maxIterations: z.number().int().positive().default(200),
+		/** Maximum number of upstream commits to process in a single agent run. Defaults to 20. */
+		maxCommitsPerRun: z.number().int().positive().default(20),
+		/**
+		* Depth used when first fetching remote refs.
+		* Shallow enough to be fast; `ensureMergeBase` will deepen if necessary. Defaults to 200.
+		*/
+		initialFetchDepth: z.number().int().positive().default(200),
+		/**
+		* Absolute upper bound for history depth when searching for a merge-base.
+		* If the merge-base is not found within this depth, a full `--unshallow` fetch is attempted.
+		* Defaults to 4000.
+		*/
+		maxFetchDepth: z.number().int().positive().default(4e3),
+		/**
+		* Number of commits to cherry-pick before pausing for human review.
+		* Smaller batches reduce blast radius if something goes wrong. Defaults to 5.
+		*/
+		batchSize: z.number().int().positive().default(5),
+		/**
+		* When true, the agent runs all analysis steps but skips all write operations
+		* (no cherry-picks, no branch pushes, no PR creation). Defaults to false.
+		* Can also be enabled at runtime via the `DRY_RUN=true` environment variable.
+		*/
+		dryRun: z.boolean().default(false),
+		/** When true, the agent opens a draft PR after pushing the sync branch. Defaults to true. */
+		createPullRequest: z.boolean().default(true),
+		/**
+		* Prefix used when naming the auto-generated sync branch.
+		* The final branch name is `<branchPrefix><upstreamBranch>-<YYYY-MM-DD>`.
+		* Defaults to `"sync/upstream-"`.
+		*/
+		branchPrefix: z.string().default("sync/upstream-")
+	}).default(() => ({})),
+	/**
+	* LLM model identifiers for the keypoollive provider.
+	* Use a cheap/fast model for high-volume triage and a more powerful one for
+	* conflict resolution where reasoning quality matters most.
+	*/
+	models: z.object({
+		/**
+		* Model used for fast, inexpensive tasks such as summarising diffs and
+		* classifying risk alongside the deterministic rule engine.
+		* Defaults to `"mistral/devstral-latest"`.
+		*/
+		fast: z.string().default("mistral/devstral-latest").describe("Low-cost model for summaries and risk triage"),
+		/**
+		* Model used as first attempt for conflict resolution — optimised for code tasks.
+		* Falls back to `models.powerful` if this call fails.
+		* Defaults to `"mistral/devstral-latest"`.
+		*/
+		specialist: z.string().default("mistral/devstral-latest").describe("Code-specialist model for conflict resolution (first attempt)"),
+		/**
+		* Model used for complex conflict resolution that demands deeper reasoning.
+		* Invoked as a fallback when `models.specialist` fails.
+		* Defaults to `"mistral/magistral-medium-latest"`.
+		*/
+		powerful: z.string().default("mistral/magistral-medium-latest").describe("High-capability model for conflict resolution (fallback)")
+	}).default(() => ({})),
+	/**
+	* Deterministic merge-strategy overrides by file path.
+	*
+	* Each entry is either a glob pattern (matched via `minimatch`) or a regex
+	* literal in the form `/pattern/flags` (e.g. `"/^sdk\\/.*\.lock$/i"`).
+	* Patterns are tested against the repo-relative file path.
+	*
+	* When a conflicted file matches:
+	*  - `ours`   → the fork version (HEAD) is used as-is; AI resolution is skipped.
+	*  - `theirs` → the upstream version (CHERRY_PICK_HEAD) is used as-is; AI resolution is skipped.
+	*
+	* `theirs` is checked first; if a file matches both, `theirs` wins.
+	*/
+	resolve: z.object({
+		/**
+		* Patterns for files where the fork version must always be kept.
+		* Useful for lock files, generated assets, or files maintained exclusively in the fork.
+		*/
+		ours: z.array(z.string()).default([]).describe("Glob/regex patterns — always keep fork version on conflict"),
+		/**
+		* Patterns for files where the upstream version must always be taken.
+		* Useful for changelogs, upstream-owned config files, or generated files
+		* that must not carry fork modifications.
+		*/
+		theirs: z.array(z.string()).default([]).describe("Glob/regex patterns — always take upstream version on conflict")
+	}).default(() => ({})),
+	/**
+	* Customizations manifest source.
+	*
+	* Accepts three forms:
+	*  - `string` starting with `http://` or `https://` → fetched at runtime.
+	*  - `string` (any other value) → treated as a local filesystem path.
+	*  - `object` → the manifest is embedded directly in config.json (JSON equivalent
+	*    of the YAML structure expected by `CustomizationsSchema`).
+	*
+	* When omitted the loader falls back to the `BACKPORT_CUSTOMIZATIONS` env var,
+	* then to `./customizations.yaml` in the current working directory.
+	*/
+	customizations: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("Path, URL, or inline object for the customizations manifest"),
+	/**
+	* Report output settings.
+	*/
+	report: z.object({ 
+	/**
+	* Filesystem directory where the detailed Markdown run report is written.
+	* The file name is `report.<timestamp>.md`.
+	* Defaults to the current working directory (`.`).
+	*/
+destination: z.string().default(".").describe("Directory where detailed run reports are written") }).default(() => ({})),
+	/**
+	* Shell command suites executed after cherry-picking, indexed by risk level.
+	* Commands must match the allowlist in `validation/commands.ts` or they will
+	* be blocked at execution time.
+	*/
+	validation: z.object({
+		/**
+		* Commands run for low-risk commits (no customisation or build-critical files touched).
+		* Defaults to `["npm run typecheck"]`.
+		*/
+		low: z.array(z.string()).default(["npm run typecheck"]),
+		/**
+		* Commands run for medium-risk commits (shared/services code changed).
+		* Defaults to typecheck + unit tests.
+		*/
+		medium: z.array(z.string()).default(["npm run typecheck", "npm run test:unit"]),
+		/**
+		* Commands run for high-risk commits (customisation zones, build files, lock files…).
+		* Defaults to typecheck + unit tests + full build.
+		*/
+		high: z.array(z.string()).default([
+			"npm run typecheck",
+			"npm run test:unit",
+			"npm run build"
+		])
+	}).default(() => ({}))
+});
+//#endregion
+//#region src/config/loader.ts
+/**
+* @file config/loader.ts
+*
+* Loads and validates the agent's main configuration from a JSON file.
+*
+* Resolution order for the config path (first match wins):
+*  1. Explicit `configPath` argument passed by the caller.
+*  2. The `BACKPORT_CONFIG` environment variable.
+*  3. `config.json` in the current working directory.
+*
+* Environment variable overrides applied after parsing:
+*  - `DRY_RUN=true` → forces `sync.dryRun = true` regardless of the JSON value.
+*/
+/**
+* Read, parse, and validate the agent configuration file.
+*
+* The raw JSON is parsed first, then any environment-variable overrides are
+* merged in before the result is validated through `SyncConfigSchema.parse()`.
+* Zod will throw a descriptive `ZodError` if required fields are missing or
+* have the wrong type.
+*
+* @param configPath - Optional explicit path to a `config.json` file.
+*                     Falls back to `BACKPORT_CONFIG` env var, then `./config.json`.
+* @returns A fully validated `SyncConfig` object with all defaults applied.
+* @throws {Error} If the file cannot be read or cannot be parsed as JSON.
+* @throws {ZodError} If the JSON structure does not satisfy `SyncConfigSchema`.
+*/
+function loadConfig(configPath) {
+	const path = configPath ?? process.env.BACKPORT_CONFIG ?? resolve(process.cwd(), "config.json");
+	const raw = JSON.parse(readFileSync(path, "utf-8"));
+	raw.sync ??= {};
+	raw.models ??= {};
+	raw.validation ??= {};
+	if (process.env.KEYPOOL_VAULT_URL) {}
+	if (process.env.DRY_RUN === "true") raw.sync = {
+		...raw.sync ?? {},
+		dryRun: true
+	};
+	return SyncConfigSchema.parse(raw);
+}
+//#endregion
+//#region src/customizations/schema.ts
+/**
+* @file customizations/schema.ts
+*
+* Zod schema for the agent's customizations manifest (customizations.yaml).
+*
+* Each "customization entry" describes a deliberate deviation from upstream:
+* which file paths it covers, what invariants must remain intact after a sync,
+* and optional shell commands that can verify the customization is still working.
+*
+* The agent uses this manifest to:
+*  1. Detect when an upstream commit touches a customization zone (risk classification).
+*  2. Guide conflict resolution — the LLM knows which files carry fork-specific logic.
+*  3. Produce human-readable PR comments that explain why certain files need review.
+*/
+/**
+* Schema for a single customization entry in the manifest.
+*
+* Example YAML entry:
+* ```yaml
+* - id: keypoollive-provider-vscode
+*   description: "Registers the keypoollive LLM provider inside the VS Code extension"
+*   paths:
+*     - src/api/providers/keypoollive.ts
+*     - src/shared/providers/providers.json
+*   invariants:
+*     - "keypoollive must remain listed in providers.json"
+*   testCommands:
+*     - "npm run typecheck"
+* ```
+*/
+var CustomizationEntrySchema = z.object({
+	/**
+	* Short machine-readable identifier for this customization, e.g. `"keypoollive-provider-vscode"`.
+	* Used in risk reports and decision logs to unambiguously reference the entry.
+	*/
+	id: z.string(),
+	/**
+	* Human-readable description of what this customization does and why it exists.
+	* Surfaced in PR comments and agent decision logs.
+	*/
+	description: z.string(),
+	/**
+	* Glob patterns (relative to the repository root) that cover the files owned
+	* by this customization.  Any upstream commit touching one of these paths will
+	* be classified as high risk.
+	*
+	* Standard minimatch syntax is supported, e.g. `"src/api/providers/keypoollive/**"`.
+	*/
+	paths: z.array(z.string()).describe("Glob patterns relative to repo root"),
+	/**
+	* Ordered list of invariants that must remain true after every sync.
+	* The agent checks these conceptually during conflict resolution and includes
+	* them in the PR body so human reviewers know what to verify.
+	*
+	* Example: `"The SCTG_KEY_VAULT_URL constant must not be removed."`
+	*/
+	invariants: z.array(z.string()).describe("Human-readable invariants that must remain true after sync"),
+	/**
+	* Optional shell commands to run in order to verify this specific customization
+	* is still intact after a sync.  These are appended to the validation suite when
+	* the commit risk level is "high" and this customization is affected.
+	*
+	* Commands must still match the global allowlist in `validation/commands.ts`.
+	*/
+	testCommands: z.array(z.string()).optional().describe("Commands to verify this customization still works")
+});
+/**
+* Schema for the entire customizations manifest file.
+* The top-level key `customizations` holds the array of entries.
+*/
+var CustomizationsSchema = z.object({ 
+/** Array of all known fork customizations. May be empty if the fork has no deviations. */
+customizations: z.array(CustomizationEntrySchema) });
+//#endregion
+//#region src/customizations/loader.ts
+/**
+* @file customizations/loader.ts
+*
+* Loads and validates the customizations manifest from multiple sources.
+*
+* Resolution order for the manifest (first match wins):
+*  1. Explicit `source` argument passed by the caller.
+*     - `string` starting with `http://` or `https://` → fetched via HTTP GET.
+*     - `string` (other) → read from the local filesystem.
+*     - `object` → used directly as the parsed manifest (JSON/inline form).
+*  2. The `BACKPORT_CUSTOMIZATIONS` environment variable (file path).
+*  3. `customizations.yaml` in the current working directory.
+*
+* The resolved value is parsed with `js-yaml` when it comes from a string/URL,
+* then validated against `CustomizationsSchema` via Zod.
+*/
+/**
+* Read, parse, and validate the customizations manifest.
+*
+* @param source - Optional source: a file path, an HTTP(S) URL, or an inline object.
+*                 Falls back to `BACKPORT_CUSTOMIZATIONS` env var, then `./customizations.yaml`.
+* @returns A fully validated `Customizations` object.
+* @throws {Error} If the file/URL cannot be read.
+* @throws {ZodError} If the structure does not satisfy `CustomizationsSchema`.
+*/
+async function loadCustomizations(source) {
+	if (source !== void 0 && typeof source === "object") return CustomizationsSchema.parse(source);
+	const strSource = source ?? process.env.BACKPORT_CUSTOMIZATIONS ?? resolve(process.cwd(), "customizations.yaml");
+	let raw;
+	if (typeof strSource === "string" && (strSource.startsWith("http://") || strSource.startsWith("https://"))) {
+		const response = await fetch(strSource);
+		if (!response.ok) throw new Error(`Failed to fetch customizations from ${strSource}: HTTP ${response.status} ${response.statusText}`);
+		const text = await response.text();
+		raw = yaml.load(text);
+	} else raw = yaml.load(readFileSync(strSource, "utf-8"));
+	return CustomizationsSchema.parse(raw);
+}
+//#endregion
+//#region src/tool-helper.ts
+/**
+* @file tool-helper.ts
+*
+* Typed wrapper around `createTool` from `@sctg/cline-sdk`.
+*
+* **Problem — overload resolution ambiguity:**
+* `@sctg/cline-shared/dist/tools/create.d.ts` declares two overloads of
+* `createTool`:
+*  1. `createTool(config: { inputSchema: Record<string, unknown>, ... })`
+*  2. `createTool<TSchema extends ZodTypeAny, TOutput>(config: { inputSchema: TSchema, ... })`
+*
+* TypeScript evaluates overloads in declaration order.  Because `ZodObject`
+* is structurally assignable to `Record<string, unknown>`, overload 1 always
+* wins, and the inferred input type in `execute` becomes `unknown` instead of
+* the typed schema inference from overload 2.
+*
+* **Solution:**
+* `defineTool` has the correct generic signature (overload 2's types) and casts
+* the config to `any` before forwarding to `createTool`.  TypeScript then
+* infers the Zod-typed `execute` parameter correctly at every call site.
+*
+* This is the only place where `as any` is used in the codebase.
+*/
+/**
+* Creates a fully-typed agent tool from the provided configuration.
+*
+* This is a thin wrapper around `createTool` that exists solely to fix TypeScript
+* overload resolution.  All arguments are forwarded unchanged; the only difference
+* from calling `createTool` directly is that `TSchema` is correctly inferred from
+* `inputSchema`.
+*
+* @typeParam TSchema - Zod schema type for the tool's input object.
+* @typeParam TOutput - Return type of the `execute` function.
+*
+* @param config - Tool configuration object.
+* @param config.name        - Machine-readable tool name (snake_case by convention).
+* @param config.description - Natural-language description shown to the LLM.
+* @param config.inputSchema - Zod schema that validates and types the tool's input.
+* @param config.execute     - Async function called by the agent runtime.  Receives
+*                             a fully typed `input` (inferred from `TSchema`) and
+*                             an `AgentToolContext` for runtime metadata.
+* @param config.lifecycle   - Optional lifecycle hooks (e.g. `completesRun: true`).
+* @param config.timeoutMs   - Optional per-invocation timeout in milliseconds.
+* @param config.retryable   - Whether the runtime should retry on transient failure.
+* @param config.maxRetries  - Maximum retry attempts (used when `retryable` is `true`).
+* @returns A fully constructed `AgentTool` ready to be passed to the `Agent` constructor.
+*/
+function defineTool(config) {
+	return createTool(config);
+}
+//#endregion
+//#region src/git/git-client.ts
+/**
+* @file git/git-client.ts
+*
+* Low-level git operations used by the backport agent.
+*
+* Design principles:
+*  - **No shell interpolation** — all git invocations use `execFileSync` with an
+*    explicit argument array.  User-supplied strings (SHAs, branch names, file
+*    paths) are always passed as separate array items, never concatenated into a
+*    shell command string.  This prevents command-injection vulnerabilities.
+*  - **Synchronous I/O** — the agent runs a single-threaded, sequential workflow;
+*    async/await overhead would add complexity without benefit.
+*  - **Minimal surface** — each function does exactly one git operation.  Higher-
+*    level orchestration lives in `git-tools.ts` (agent tool wrappers).
+*/
+/**
+* Executes a git command in the given working directory using `execFileSync`.
+*
+* All standard streams are piped so that stdout and stderr are captured rather
+* than printed to the terminal.  The return value is the trimmed stdout string.
+*
+* **Security note:** arguments must always be provided as an array — never as a
+* pre-joined string — to prevent shell injection.
+*
+* @param args - Git sub-command and its arguments, e.g. `["cherry", "-v", "HEAD"]`.
+* @param cwd  - Absolute path to the repository working directory.
+* @returns Trimmed stdout output of the git command.
+* @throws If the git process exits with a non-zero status (e.g. merge conflict).
+*/
+function git(args, cwd) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf-8",
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+/**
+* Ensures the local git history is deep enough to compute the merge-base between
+* the upstream branch and the fork branch.
+*
+* Many CI environments start with a shallow clone (`--depth=1`).  This function
+* progressively deepens the clone in steps rather than fetching the entire
+* history at once, which keeps network usage low for the common case.
+*
+* Algorithm:
+*  1. Try `git merge-base` at the current depth.
+*  2. If it fails, deepen by the next step value and retry.
+*  3. If even `maxDepth` is insufficient, fall back to `--unshallow`.
+*
+* @param cwd         - Absolute path to the repository working directory.
+* @param upstreamRef - Full ref for the upstream branch, e.g. `"upstream/main"`.
+* @param forkRef     - Full ref for the fork branch, e.g. `"origin/main"`.
+* @param maxDepth    - Depth ceiling before attempting a full unshallow fetch.
+*                      Defaults to 4000 (matches `sync.maxFetchDepth` default).
+* @returns The SHA of the common ancestor commit (the merge-base).
+* @throws If the merge-base cannot be determined even after a full fetch.
+*/
+function ensureMergeBase(cwd, upstreamRef, forkRef, maxDepth = 4e3) {
+	const depths = [
+		200,
+		500,
+		1e3,
+		2e3,
+		maxDepth
+	];
+	for (const depth of depths) try {
+		return git([
+			"merge-base",
+			upstreamRef,
+			forkRef
+		], cwd);
+	} catch {
+		if (depth === maxDepth) {
+			git(["fetch", "--unshallow"], cwd);
+			return git([
+				"merge-base",
+				upstreamRef,
+				forkRef
+			], cwd);
+		}
+		git(["fetch", `--deepen=${depth}`], cwd);
+	}
+	throw new Error("Could not find merge-base even after full fetch");
+}
+/**
+* Lists all upstream commits that are not yet present in the fork branch.
+*
+* Uses `git cherry` which compares patch content (not just SHA) so that commits
+* that were already cherry-picked (and may have a different SHA in the fork) are
+* correctly identified as already applied.
+*
+* Output format of `git cherry -v <upstream> <fork>`:
+*  - Lines prefixed with `+` are **not** in the fork → candidates for cherry-pick.
+*  - Lines prefixed with `-` **are** equivalent in the fork → already applied.
+*
+* @param cwd         - Absolute path to the repository working directory.
+* @param upstreamRef - Full ref for the upstream branch, e.g. `"upstream/main"`.
+* @param forkRef     - Full ref for the fork branch, e.g. `"origin/main"`.
+* @returns Array of `CandidateCommit` objects, oldest-first.
+*/
+function listCandidateCommits(cwd, upstreamRef, forkRef) {
+	const cherryOutput = git([
+		"cherry",
+		"-v",
+		forkRef,
+		upstreamRef
+	], cwd);
+	if (!cherryOutput) return [];
+	return cherryOutput.split("\n").map((line) => {
+		const marker = line[0];
+		const rest = line.slice(2);
+		const spaceIdx = rest.indexOf(" ");
+		return {
+			sha: rest.slice(0, spaceIdx),
+			subject: rest.slice(spaceIdx + 1),
+			alreadyApplied: marker === "-"
+		};
+	});
+}
+/**
+* Returns the list of file paths changed by a single commit.
+*
+* Internally calls `git diff-tree --no-commit-id -r --name-only <sha>` which
+* lists only changed paths without any diff content, keeping the output small.
+*
+* @param cwd - Absolute path to the repository working directory.
+* @param sha - Full or abbreviated commit SHA.
+* @returns Array of repository-relative file paths changed by the commit.
+*          Empty array if the commit has no file changes (e.g. an empty commit).
+*/
+function getCommitChangedFiles(cwd, sha) {
+	const output = git([
+		"diff-tree",
+		"--no-commit-id",
+		"-r",
+		"--name-only",
+		sha
+	], cwd);
+	return output ? output.split("\n").filter(Boolean) : [];
+}
+/**
+* Returns the full diff of a single commit, capped to `maxBytes` characters.
+*
+* The diff includes the commit stat summary (`--stat`) followed by the patch
+* (`--patch`).  Large diffs are truncated with a notice so that the LLM context
+* window is not exhausted by a single commit.
+*
+* @param cwd      - Absolute path to the repository working directory.
+* @param sha      - Full or abbreviated commit SHA.
+* @param maxBytes - Maximum number of characters to return.  Defaults to 32 000.
+* @returns Diff string, possibly truncated.
+*/
+function getCommitDiff(cwd, sha, maxBytes = 32e3) {
+	const full = git([
+		"show",
+		"--stat",
+		"--patch",
+		sha
+	], cwd);
+	return full.length > maxBytes ? full.slice(0, maxBytes) + "\n... [truncated]" : full;
+}
+/**
+* Creates a new sync branch from the tip of the fork branch.
+*
+* The branch is created locally; `pushBranch` must be called separately to
+* publish it to the remote.
+*
+* @param cwd        - Absolute path to the repository working directory.
+* @param branchName - Name for the new sync branch.
+* @param forkRef    - Full ref of the fork branch to branch off, e.g. `"origin/main"`.
+*/
+function createSyncBranch(cwd, branchName, forkRef) {
+	git(["checkout", forkRef], cwd);
+	git([
+		"checkout",
+		"-b",
+		branchName
+	], cwd);
+}
+/**
+* Attempts to cherry-pick a single upstream commit onto the current branch.
+*
+* The `-x` flag appends `(cherry picked from commit …)` to the commit message,
+* providing an audit trail in the fork's history.
+*
+* On conflict, the cherry-pick is intentionally left **in progress** rather than
+* aborted.  This allows the agent to inspect each conflicted file via
+* `getConflictContext`, resolve them, then call `continueCherryPick`.  If the
+* agent cannot resolve the conflicts, it should call `abortCherryPick` instead.
+*
+* @param cwd - Absolute path to the repository working directory.
+* @param sha - Full or abbreviated SHA of the commit to cherry-pick.
+* @returns An object with `success: true` if the cherry-pick applied cleanly,
+*          or `success: false` plus the list of conflicted file paths.
+*/
+function cherryPick(cwd, sha) {
+	try {
+		git([
+			"cherry-pick",
+			"-x",
+			sha
+		], cwd);
+		return {
+			success: true,
+			conflictedFiles: []
+		};
+	} catch {
+		const status = git([
+			"diff",
+			"--name-only",
+			"--diff-filter=U"
+		], cwd);
+		return {
+			success: false,
+			conflictedFiles: status ? status.split("\n").filter(Boolean) : []
+		};
+	}
+}
+/**
+* Aborts a cherry-pick that is currently in progress.
+*
+* This resets the index and working tree to the state before `git cherry-pick`
+* was called.  It is safe to call even if no cherry-pick is in progress (the
+* error is swallowed silently).
+*
+* @param cwd - Absolute path to the repository working directory.
+*/
+function abortCherryPick(cwd) {
+	try {
+		git(["cherry-pick", "--abort"], cwd);
+	} catch {}
+}
+/**
+* Returns the content of a file at a specific git ref.
+*
+* Common use cases:
+*  - `ref = "HEAD"`              → the fork's current version of the file.
+*  - `ref = "CHERRY_PICK_HEAD"` → the upstream version being cherry-picked.
+*  - `ref = "<sha>"`             → the version at any specific commit.
+*
+* @param cwd      - Absolute path to the repository working directory.
+* @param ref      - Git ref, symbolic name, or SHA.
+* @param filePath - Repository-relative path of the file, e.g. `"src/foo.ts"`.
+* @returns The file content as a UTF-8 string, or `null` if the file does not
+*          exist at the given ref (e.g. the file was added by the cherry-picked commit).
+*/
+function getFileAtRef(cwd, ref, filePath) {
+	try {
+		return git(["show", `${ref}:${filePath}`], cwd);
+	} catch {
+		return null;
+	}
+}
+/**
+* Writes resolved content to a file on disk and stages it with `git add`.
+*
+* Called by the agent after resolving each conflicted file.  The file must
+* contain no conflict markers before calling this function.
+*
+* @param cwd      - Absolute path to the repository working directory.
+* @param filePath - Repository-relative path of the file, e.g. `"src/foo.ts"`.
+* @param content  - Fully resolved file content, free of conflict markers.
+*/
+function writeAndStageFile(cwd, filePath, content) {
+	writeFileSync(`${cwd}/${filePath}`, content, "utf-8");
+	git(["add", filePath], cwd);
+}
+/**
+* Completes an in-progress cherry-pick after all conflicts have been resolved and staged.
+*
+* Uses `GIT_EDITOR=true` to suppress the interactive editor that git would
+* otherwise open for the commit message, making this safe to call in a
+* non-interactive CI environment.
+*
+* @param cwd - Absolute path to the repository working directory.
+* @throws If there are still unstaged conflicted files when this is called.
+*/
+function continueCherryPick(cwd) {
+	execFileSync("git", [
+		"cherry-pick",
+		"--continue",
+		"--no-edit"
+	], {
+		cwd,
+		encoding: "utf-8",
+		env: {
+			...process.env,
+			GIT_EDITOR: "true"
+		}
+	});
+}
+/**
+* Pushes the sync branch to the fork remote.
+*
+* A simple non-force push.  If the branch already exists on the remote with
+* different history the push will fail — the agent should never force-push to
+* avoid overwriting human commits.
+*
+* @param cwd        - Absolute path to the repository working directory.
+* @param remote     - Name of the git remote to push to, e.g. `"origin"`.
+* @param branchName - Name of the local branch to push.
+*/
+function pushBranch(cwd, remote, branchName) {
+	git([
+		"push",
+		remote,
+		branchName
+	], cwd);
+}
+/**
+* Fetches both the upstream and fork remotes to bring local refs up to date.
+*
+* Uses a shallow fetch (`--depth=N`) to keep network usage proportional.  The
+* depth here corresponds to `sync.initialFetchDepth`; `ensureMergeBase` will
+* deepen further if needed.
+*
+* @param cwd             - Absolute path to the repository working directory.
+* @param upstreamRemote  - Name of the upstream git remote, e.g. `"upstream"`.
+* @param forkRemote      - Name of the fork git remote, e.g. `"origin"`.
+* @param depth           - Shallow fetch depth.
+*/
+function fetchRemotes(cwd, upstreamRemote, forkRemote, depth) {
+	git([
+		"fetch",
+		`--depth=${depth}`,
+		upstreamRemote
+	], cwd);
+	git([
+		"fetch",
+		`--depth=${depth}`,
+		forkRemote
+	], cwd);
+}
+//#endregion
+//#region src/git/git-tools.ts
+/**
+* @file git/git-tools.ts
+*
+* Factory that creates the agent tools wrapping all low-level git operations.
+*
+* Each tool returned by `makeGitTools` corresponds to a single capability that
+* the LLM can invoke during the sync workflow:
+*
+*  1. `fetch_remotes`          — update local refs from upstream and fork.
+*  2. `list_candidate_commits` — discover which upstream commits to sync.
+*  3. `get_commit_details`     — inspect changed files and full diff.
+*  4. `create_sync_branch`     — branch off the fork tip for this sync run.
+*  5. `cherry_pick_commit`     — apply a single commit; reports conflicts.
+*  6. `abort_cherry_pick`      — abandon a conflicting cherry-pick.
+*  7. `get_conflict_context`   — fetch fork, upstream, and marker-annotated versions.
+*  8. `apply_resolved_file`    — write the LLM's resolution and stage it.
+*  9. `continue_cherry_pick`   — complete the cherry-pick after all files resolved.
+* 10. `push_sync_branch`       — publish the sync branch to the fork remote.
+*
+* All tools respect the `sync.dryRun` flag by returning early with a `dryRun:true`
+* marker instead of performing any mutating operation.
+*/
+/**
+* Tests whether a repo-relative file path matches any of the given patterns.
+*
+* Patterns are either:
+* - A glob string (matched via `minimatch` with `matchBase: true`).
+* - A regex literal in the form `/source/flags` (e.g. `"/^sdk\\/.*\.ts$/i"`).
+*
+* @param filePath - Repo-relative path of the file to test.
+* @param patterns - Array of glob or regex patterns from the config.
+* @returns `true` if the path matches at least one pattern.
+*/
+function matchesResolvePattern(filePath, patterns) {
+	for (const pattern of patterns) if (pattern.startsWith("/") && pattern.lastIndexOf("/") > 0) {
+		const lastSlash = pattern.lastIndexOf("/");
+		const source = pattern.slice(1, lastSlash);
+		const flags = pattern.slice(lastSlash + 1);
+		try {
+			if (new RegExp(source, flags).test(filePath)) return true;
+		} catch {}
+	} else if (minimatch(filePath, pattern, { matchBase: true })) return true;
+	return false;
+}
+/**
+* Builds and returns all git-related agent tools pre-bound to the provided config.
+*
+* The returned array is spread directly into the `Agent` constructor's `tools`
+* array.  Each tool captures `workingDir`, `upstream`, `fork`, and `sync` from
+* the config via closure, so callers never need to pass them per-invocation.
+*
+* @param config - Validated `SyncConfig` loaded from `config.json`.
+* @returns Array of ten agent tools covering the full git workflow.
+*/
+function makeGitTools(config) {
+	const { workingDir, upstream, fork, sync } = config;
+	return [
+		defineTool({
+			name: "fetch_remotes",
+			description: "Fetch both upstream and fork remotes to ensure local refs are up to date.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				fetchRemotes(workingDir, upstream.remote, fork.remote, sync.initialFetchDepth);
+				ensureMergeBase(workingDir, `${upstream.remote}/${upstream.branch}`, `${fork.remote}/${fork.branch}`, sync.maxFetchDepth);
+				return { success: true };
+			}
+		}),
+		defineTool({
+			name: "list_candidate_commits",
+			description: "List upstream commits that are not yet applied to the fork branch. Uses git cherry to detect already-applied patches by content, not just SHA. Returns an array of candidate commits with their SHA, subject, and alreadyApplied flag.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				const pending = listCandidateCommits(workingDir, `${upstream.remote}/${upstream.branch}`, `${fork.remote}/${fork.branch}`).filter((c) => !c.alreadyApplied).slice(0, sync.maxCommitsPerRun);
+				return {
+					candidates: pending,
+					total: pending.length
+				};
+			}
+		}),
+		defineTool({
+			name: "get_commit_details",
+			description: "Get the changed files and diff for a specific upstream commit. Use this before classifying risk or attempting a cherry-pick.",
+			inputSchema: z.object({
+				sha: z.string().describe("The commit SHA to inspect"),
+				/** Set to false to skip the diff and only retrieve the file list. */
+				includeDiff: z.boolean().default(true)
+			}),
+			execute: async ({ sha, includeDiff }) => {
+				return {
+					sha,
+					changedFiles: getCommitChangedFiles(workingDir, sha),
+					diff: includeDiff ? getCommitDiff(workingDir, sha) : null
+				};
+			}
+		}),
+		defineTool({
+			name: "create_sync_branch",
+			description: "Create a new sync branch from the fork branch tip. The branch name is auto-generated with today's date. Returns the branch name.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				if (sync.dryRun) return {
+					branchName: null,
+					dryRun: true
+				};
+				const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+				const branchName = `${sync.branchPrefix}${upstream.branch}-${date}`;
+				createSyncBranch(workingDir, branchName, `${fork.remote}/${fork.branch}`);
+				return { branchName };
+			}
+		}),
+		defineTool({
+			name: "cherry_pick_commit",
+			description: "Attempt to cherry-pick a single upstream commit onto the current sync branch. Returns success:true if clean, or success:false with conflictedFiles if conflicts arose. On conflict, the cherry-pick is left in progress for the resolve_conflict tool.",
+			inputSchema: z.object({ sha: z.string().describe("Upstream commit SHA to cherry-pick") }),
+			execute: async ({ sha }) => {
+				if (sync.dryRun) return {
+					success: true,
+					dryRun: true,
+					conflictedFiles: []
+				};
+				return cherryPick(workingDir, sha);
+			}
+		}),
+		defineTool({
+			name: "abort_cherry_pick",
+			description: "Abort the current cherry-pick in progress. Call this when a conflict cannot be resolved automatically.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				abortCherryPick(workingDir);
+				return { aborted: true };
+			}
+		}),
+		defineTool({
+			name: "get_conflict_context",
+			description: "For a conflicted file, return the fork version (HEAD), the upstream version (CHERRY_PICK_HEAD), and the current file content with conflict markers. Use this to gather context before resolving.",
+			inputSchema: z.object({ filePath: z.string().describe("Repo-relative path of the conflicted file") }),
+			execute: async ({ filePath }) => {
+				const forkVersion = getFileAtRef(workingDir, "HEAD", filePath);
+				const upstreamVersion = getFileAtRef(workingDir, "CHERRY_PICK_HEAD", filePath);
+				let withMarkers = null;
+				try {
+					withMarkers = readFileSync(`${workingDir}/${filePath}`, "utf-8");
+				} catch {
+					withMarkers = null;
+				}
+				let forcedStrategy = null;
+				const resolveConfig = config.resolve;
+				if (resolveConfig) {
+					if (matchesResolvePattern(filePath, resolveConfig.theirs ?? [])) forcedStrategy = "theirs";
+					else if (matchesResolvePattern(filePath, resolveConfig.ours ?? [])) forcedStrategy = "ours";
+				}
+				return {
+					filePath,
+					forkVersion,
+					upstreamVersion,
+					withMarkers,
+					forcedStrategy
+				};
+			}
+		}),
+		defineTool({
+			name: "apply_resolved_file",
+			description: "Write the resolved content for a conflicted file and stage it. Call this for each conflicted file before calling continue_cherry_pick.",
+			inputSchema: z.object({
+				filePath: z.string().describe("Repo-relative path of the file"),
+				resolvedContent: z.string().describe("The fully resolved file content, with no conflict markers")
+			}),
+			execute: async ({ filePath, resolvedContent }) => {
+				if (sync.dryRun) return {
+					staged: false,
+					dryRun: true
+				};
+				writeAndStageFile(workingDir, filePath, resolvedContent);
+				return {
+					staged: true,
+					filePath
+				};
+			}
+		}),
+		defineTool({
+			name: "continue_cherry_pick",
+			description: "Complete the cherry-pick after all conflicted files have been resolved and staged via apply_resolved_file.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				if (sync.dryRun) return {
+					committed: false,
+					dryRun: true
+				};
+				continueCherryPick(workingDir);
+				return { committed: true };
+			}
+		}),
+		defineTool({
+			name: "push_sync_branch",
+			description: "Push the current sync branch to the fork remote.",
+			inputSchema: z.object({ 
+			/** Name of the local sync branch to push, as returned by `create_sync_branch`. */
+branchName: z.string() }),
+			execute: async ({ branchName }) => {
+				if (sync.dryRun) return {
+					pushed: false,
+					dryRun: true
+				};
+				pushBranch(workingDir, fork.remote, branchName);
+				return {
+					pushed: true,
+					branchName
+				};
+			}
+		})
+	];
+}
+//#endregion
+//#region src/git/git-init.ts
+/**
+* @file git/git-init.ts
+*
+* Repository initialisation and authentication helpers.
+*
+* Two exported functions:
+*
+*  - `applyGitAuth(config)`    — configures the process environment so that all
+*    subsequent git calls (via `git-client.ts`) use the right credentials.
+*    Supports SSH private keys (via `GIT_SSH_COMMAND`) and HTTP bearer tokens
+*    (via git's `http.extraHeader` environment config).
+*
+*  - `ensureWorkingDir(config)` — makes the `workingDir` ready for the agent:
+*    · If the directory does not exist (or is not a git repo): clones `fork.url`.
+*    · If it already exists: fetches all remotes to bring it up to date.
+*    · Ensures the upstream remote is properly configured when its URL is provided
+*      and it differs from the fork remote.
+*
+* Design notes:
+*  - All git I/O is synchronous (matches the rest of git-client.ts).
+*  - No secrets are stored in child-process arguments — tokens are injected via
+*    environment variables only.
+*  - `fork.url` supports any git hosting provider (GitHub, GitLab, Gitea, …).
+*/
+/**
+* Resolves a config value that may reference an environment variable.
+*
+* If `value` starts with `$` the remainder is treated as an environment variable
+* name.  This lets operators write `"$GITHUB_TOKEN"` in config.json instead of
+* embedding the raw secret, keeping credentials out of version control.
+*
+* @param value - Raw config string, e.g. `"ghp_abc123"` or `"$MY_TOKEN"`.
+* @returns The resolved string, or `undefined` if the env var is not set.
+*/
+function resolveConfigValue(value) {
+	if (value.startsWith("$")) return process.env[value.slice(1)];
+	return value;
+}
+/**
+* Configures process-level environment variables so that all subsequent git
+* operations (in this process and its child processes) use the right credentials.
+*
+* Priority order:
+*  1. SSH key  (`config.auth.sshKeyPath`)     → sets `GIT_SSH_COMMAND`
+*  2. Token    (`config.auth.githubToken`)    → sets `GIT_CONFIG_*` http.extraHeader
+*  3. Fallback to `GITHUB_TOKEN` env var      → same as (2)
+*
+* If none of the above are set the function is a no-op; git will use whatever
+* credentials are already available in the environment (SSH agent, credential helper…).
+*
+* @param config - Validated `SyncConfig` loaded from `config.json`.
+*/
+function applyGitAuth(config) {
+	const { sshKeyPath, githubToken } = config.auth;
+	if (sshKeyPath) {
+		const keyPath = sshKeyPath.replace(/^~(?=\/|$)/, process.env.HOME ?? "");
+		process.env.GIT_SSH_COMMAND = `ssh -i "${keyPath}" -o StrictHostKeyChecking=no -o BatchMode=yes`;
+		process.stderr.write(`[GitAuth] SSH key configured: ${keyPath}\n`);
+		return;
+	}
+	const token = resolveConfigValue(githubToken ?? "$GITHUB_TOKEN");
+	if (token) {
+		const count = parseInt(process.env.GIT_CONFIG_COUNT ?? "0", 10);
+		process.env.GIT_CONFIG_COUNT = String(count + 1);
+		process.env[`GIT_CONFIG_KEY_${count}`] = "http.extraHeader";
+		process.env[`GIT_CONFIG_VALUE_${count}`] = `Authorization: Bearer ${token}`;
+		process.stderr.write("[GitAuth] HTTP bearer token auth configured.\n");
+	}
+}
+/**
+* Ensures that `config.workingDir` contains a ready-to-use git repository.
+*
+* **Clone** (directory absent or not a git repo):
+*  Clones `config.fork.url` into `config.workingDir`.  The parent directory is
+*  created if necessary.  Throws if `fork.url` is not set.
+*
+* **Sync** (directory is already a git repo):
+*  Runs `git fetch --all --prune` to bring all tracked remotes up to date.
+*
+* **Upstream remote**:
+*  When `config.upstream.url` is set and `upstream.remote` differs from
+*  `fork.remote`, the upstream remote is added (or its URL updated) automatically.
+*
+* @param config - Validated `SyncConfig` loaded from `config.json`.
+* @throws If cloning is required but `fork.url` is not configured.
+*/
+function ensureWorkingDir(config) {
+	const { workingDir, upstream, fork } = config;
+	if (!existsSync(`${workingDir}/.git`)) {
+		if (!fork.url) throw new Error(`[GitInit] '${workingDir}' is not a git repository and fork.url is not configured. Set fork.url to a valid git URL (SSH or HTTPS) to enable automatic cloning.`);
+		mkdirSync(dirname(workingDir), { recursive: true });
+		process.stderr.write(`[GitInit] Cloning ${fork.url} → ${workingDir} ...\n`);
+		execFileSync("git", [
+			"clone",
+			fork.url,
+			workingDir
+		], { stdio: [
+			"pipe",
+			"inherit",
+			"inherit"
+		] });
+		process.stderr.write("[GitInit] Clone complete.\n");
+	} else {
+		process.stderr.write(`[GitInit] ${workingDir} found — fetching all remotes...\n`);
+		try {
+			git([
+				"fetch",
+				"--all",
+				"--prune"
+			], workingDir);
+			process.stderr.write("[GitInit] Fetch complete.\n");
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[GitInit] Warning: fetch failed: ${msg}\n`);
+		}
+	}
+	if (upstream.url && upstream.remote !== fork.remote) try {
+		if (!git(["remote"], workingDir).split("\n").filter(Boolean).includes(upstream.remote)) {
+			git([
+				"remote",
+				"add",
+				upstream.remote,
+				upstream.url
+			], workingDir);
+			process.stderr.write(`[GitInit] Added remote '${upstream.remote}' → ${upstream.url}\n`);
+		} else if (git([
+			"remote",
+			"get-url",
+			upstream.remote
+		], workingDir) !== upstream.url) {
+			git([
+				"remote",
+				"set-url",
+				upstream.remote,
+				upstream.url
+			], workingDir);
+			process.stderr.write(`[GitInit] Updated remote '${upstream.remote}' → ${upstream.url}\n`);
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[GitInit] Warning: could not configure upstream remote: ${msg}\n`);
+	}
+}
+//#endregion
+//#region src/risk/classify-risk.ts
+/**
+* @file risk/classify-risk.ts
+*
+* Purely deterministic commit risk classifier — no LLM is involved.
+*
+* The classifier assigns one of three risk levels to an upstream commit:
+*  - **low**    — Only touches files that are safe to auto-apply.
+*  - **medium** — Touches shared infrastructure (API layer, shared types, services)
+*                  that may interact with fork customizations.
+*  - **high**   — Touches build configuration, CI pipelines, lockfiles, protobuf
+*                  definitions, or a file explicitly listed in the fork's
+*                  `customizations.yaml`.
+*
+* The LLM agent uses this output as high-level context before deciding whether
+* to attempt a cherry-pick, skip, or request human review.
+*
+* Pattern matching uses `minimatch` (the same glob library used by `.gitignore`
+* and the VS Code extension tree).  All patterns are relative to the repository
+* root, as returned by `git diff-tree --name-only`.
+*/
+/**
+* Glob patterns whose matches unconditionally elevate risk to `"high"`.
+*
+* These files are considered build-critical or structurally sensitive:
+*  - Dependency manifests and lockfiles (`package.json`, `*-lock.*`, `*.lock`)
+*  - CI / GitHub Actions workflows (`.github/workflows/**`)
+*  - Build scripts directory (`scripts/**`)
+*  - ESBuild config files (`esbuild.*`)
+*  - TypeScript project references (`tsconfig*.json`)
+*  - Protobuf definitions (`proto/**`) — changes here require proto regeneration
+*    and affect the entire RPC layer
+*/
+var HIGH_RISK_PATTERNS = [
+	"package.json",
+	"package-lock.json",
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	".github/workflows/**",
+	"scripts/**",
+	"esbuild.*",
+	"tsconfig*.json",
+	"proto/**"
+];
+/**
+* Glob patterns whose matches elevate risk to `"medium"` when no high-risk
+* pattern has already been matched.
+*
+* These paths contain shared infrastructure that is more likely to conflict
+* with fork customizations than generic feature code:
+*  - `src/core/api/**`           — API provider implementations
+*  - `src/shared/**`             — Shared types and utilities used everywhere
+*  - `src/services/**`           — Backend services (MCP hub, etc.)
+*  - `webview-ui/src/services/**`— Webview service layer
+*/
+var MEDIUM_RISK_PATTERNS = [
+	"src/core/api/**",
+	"src/shared/**",
+	"src/services/**",
+	"webview-ui/src/services/**"
+];
+/**
+* Classifies the risk level of an upstream commit based on which files it changes.
+*
+* Evaluation order (highest-priority first):
+*  1. Fork customization zones (`customizations.yaml`) → always `high`.
+*  2. `HIGH_RISK_PATTERNS` glob matches                → always `high`.
+*  3. `MEDIUM_RISK_PATTERNS` glob matches              → `medium` (if not already high).
+*  4. Detected file deletions or renames               → elevate to at least `medium`.
+*  5. No matches                                        → remains `low`.
+*
+* This function is **pure and deterministic** — given the same inputs it always
+* returns the same output.  It has no side effects and performs no I/O.
+*
+* @param sha             - Full or abbreviated commit SHA (used to label the result).
+* @param changedFiles    - Repository-relative file paths changed by the commit,
+*                          as returned by `getCommitChangedFiles`.
+* @param customizations  - Validated customizations manifest from `loadCustomizations`.
+* @returns A `CommitRisk` record with the computed level, reasons, and customization matches.
+*/
+function classifyRisk(sha, changedFiles, customizations) {
+	const reasons = [];
+	const matchedCustomizationIds = [];
+	let level = "low";
+	for (const entry of customizations.customizations) {
+		const hits = changedFiles.filter((f) => entry.paths.some((p) => minimatch(f, p)));
+		if (hits.length > 0) {
+			matchedCustomizationIds.push(entry.id);
+			reasons.push(`Touches customization "${entry.id}": ${hits.join(", ")}`);
+			level = "high";
+		}
+	}
+	for (const pattern of HIGH_RISK_PATTERNS) {
+		const hits = changedFiles.filter((f) => minimatch(f, pattern));
+		if (hits.length > 0) {
+			if (level !== "high") level = "high";
+			reasons.push(`High-risk file pattern "${pattern}": ${hits.join(", ")}`);
+		}
+	}
+	if (level === "low") for (const pattern of MEDIUM_RISK_PATTERNS) {
+		const hits = changedFiles.filter((f) => minimatch(f, pattern));
+		if (hits.length > 0) {
+			level = "medium";
+			reasons.push(`Medium-risk pattern "${pattern}": ${hits.join(", ")}`);
+		}
+	}
+	if (changedFiles.filter((f) => f.startsWith("DELETE:") || f.startsWith("RENAME:")).length > 0) {
+		if (level === "low") level = "medium";
+		reasons.push(`File deletions or renames detected`);
+	}
+	if (reasons.length === 0) reasons.push("No risk patterns matched — appears to be a low-risk change");
+	return {
+		sha,
+		level,
+		reasons,
+		touchesCustomization: matchedCustomizationIds.length > 0,
+		customizationIds: matchedCustomizationIds
+	};
+}
+//#endregion
+//#region src/risk/risk-tools.ts
+/**
+* @file risk/risk-tools.ts
+*
+* Factory that creates the `classify_commit_risk` agent tool.
+*
+* Risk classification is a deterministic gate that runs **before** any LLM
+* reasoning: the agent calls this tool first, learns the risk level and
+* affected customizations, then decides how to proceed (auto-apply, apply with
+* validation, or escalate to human review).
+*
+* The tool is kept in a separate factory function so that the validated
+* `customizations` object (loaded once at startup) can be captured by closure
+* and reused across every invocation without re-parsing the YAML file.
+*/
+/**
+* Builds and returns the `classify_commit_risk` agent tool.
+*
+* The tool is pre-bound to `config` and `customizations` so that callers only
+* need to provide the commit SHA at invocation time.
+*
+* @param config          - Validated `SyncConfig` (provides `workingDir`).
+* @param customizations  - Validated customizations manifest (provides zone definitions).
+* @returns A single agent tool: `classify_commit_risk`.
+*/
+function makeRiskTool(config, customizations) {
+	return defineTool({
+		name: "classify_commit_risk",
+		description: "Classify the risk level of an upstream commit by analysing which files it changes. Returns 'low', 'medium', or 'high' with human-readable reasons. High risk means the commit touches fork customization zones or build-critical files. This is a deterministic check — no LLM is used here.",
+		inputSchema: z.object({ 
+		/** Full or abbreviated SHA of the upstream commit to classify. */
+sha: z.string().describe("Upstream commit SHA to classify") }),
+		execute: async ({ sha }) => {
+			return classifyRisk(sha, getCommitChangedFiles(config.workingDir, sha), customizations);
+		}
+	});
+}
+//#endregion
+//#region src/validation/commands.ts
+/**
+* @file validation/commands.ts
+*
+* Allowlist-based command runner for the validation suite.
+*
+* **Security model:**
+* The LLM agent may suggest commands to run during validation.  To prevent
+* arbitrary code execution, every command is checked against a fixed prefix
+* allowlist before being executed.  Only standard package-manager test scripts
+* and well-known CLI tools are permitted.  The allowlist is hard-coded in this
+* file and cannot be extended by the agent at runtime.
+*
+* **No shell interpolation:**
+* Commands are split on whitespace and executed via `execFileSync(bin, args[])`
+* (not through a shell).  This prevents shell metacharacter injection even for
+* allowlisted commands.
+*
+* **Failure fast:**
+* `runValidationSuite` stops at the first failing command so that the agent
+* receives a clear, actionable error rather than a wall of cascading output.
+*/
+/**
+* Hard-coded allowlist of command prefixes that the agent is permitted to execute.
+*
+* A command is allowed if and only if it starts with one of these strings.
+* The list is intentionally conservative:
+*  - `"npm run "`     — npm scripts defined in package.json
+*  - `"pnpm run "`    — pnpm equivalent
+*  - `"yarn run "`    — yarn equivalent
+*  - `"npx tsc"`      — TypeScript type-checker
+*  - `"npx eslint"`   — ESLint linter
+*  - `"npx vitest"`   — Vitest unit test runner
+*  - `"node --version"` — Non-destructive version probe (useful for diagnostics)
+*/
+var ALLOWED_COMMAND_PREFIXES = [
+	"npm run ",
+	"pnpm run ",
+	"yarn run ",
+	"npx tsc",
+	"npx eslint",
+	"npx vitest",
+	"node --version"
+];
+/**
+* Returns `true` if the command starts with an allowlisted prefix.
+*
+* The check is intentionally a simple `startsWith` — it does not parse the
+* full command.  This makes the allowlist easy to audit.
+*
+* @param command - The full command string to check.
+* @returns `true` if the command is allowed, `false` if it should be blocked.
+*/
+function isAllowedCommand(command) {
+	return ALLOWED_COMMAND_PREFIXES.some((prefix) => command.startsWith(prefix));
+}
+/**
+* Runs a single validation command and returns its result.
+*
+* If the command is not on the allowlist, it is immediately blocked and a
+* descriptive error is returned without executing anything.
+*
+* Execution details:
+*  - `stdio: ["pipe","pipe","pipe"]` — all streams are captured, not printed.
+*  - `timeout: 120_000` ms — commands are killed if they take more than 2 minutes.
+*  - No `shell: true` — the command is parsed by whitespace split and executed directly.
+*
+* @param command - Full command string, e.g. `"npm run typecheck"`.
+* @param cwd     - Absolute working directory in which to run the command.
+* @returns A `CommandResult` with the success flag, exit code, and captured output.
+*/
+function runValidationCommand(command, cwd) {
+	if (!isAllowedCommand(command)) return {
+		command,
+		success: false,
+		exitCode: 1,
+		output: `Blocked: command "${command}" is not in the allowed list`
+	};
+	const parts = command.split(" ");
+	const bin = parts[0];
+	const args = parts.slice(1);
+	try {
+		return {
+			command,
+			success: true,
+			exitCode: 0,
+			output: execFileSync(bin, args, {
+				cwd,
+				encoding: "utf-8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				],
+				timeout: 12e4
+			})
+		};
+	} catch (err) {
+		const e = err;
+		const output = [
+			e.stdout,
+			e.stderr,
+			e.message
+		].filter(Boolean).join("\n");
+		return {
+			command,
+			success: false,
+			exitCode: e.status ?? 1,
+			output
+		};
+	}
+}
+/**
+* Runs an ordered list of validation commands, stopping on the first failure.
+*
+* "Fail fast" semantics are intentional: the agent should see the first broken
+* command and address it rather than drowning in cascading failures.
+*
+* @param commands - Ordered array of command strings to execute.
+* @param cwd      - Absolute working directory for all commands.
+* @returns Array of `CommandResult` objects, one per executed command.
+*          If a command fails, no subsequent commands are executed.
+*/
+function runValidationSuite(commands, cwd) {
+	const results = [];
+	for (const command of commands) {
+		const result = runValidationCommand(command, cwd);
+		results.push(result);
+		if (!result.success) break;
+	}
+	return results;
+}
+//#endregion
+//#region src/validation/validation-tools.ts
+/**
+* @file validation/validation-tools.ts
+*
+* Factory that creates the `run_validation` agent tool.
+*
+* Validation is the agent's safety net: before accepting a cherry-picked commit
+* as "done", the agent runs the suite appropriate for the commit's risk level to
+* confirm that the fork still builds and passes tests.
+*
+* Risk → suite mapping (configured in `config.validation`):
+*  - `"low"`    → `config.validation.low`    (e.g. only typecheck)
+*  - `"medium"` → `config.validation.medium` (e.g. typecheck + unit tests)
+*  - `"high"`   → `config.validation.high`   (e.g. full build + integration tests)
+*
+* The agent may append extra customization-specific commands via the
+* `extraCommands` input field.  All commands (base suite + extras) are passed
+* through the same `ALLOWED_COMMAND_PREFIXES` allowlist in `commands.ts`.
+*/
+/**
+* Builds and returns the `run_validation` agent tool.
+*
+* The tool is pre-bound to `config` so that the caller only needs to supply the
+* risk level and any optional extra commands at invocation time.
+*
+* @param config - Validated `SyncConfig` (provides `workingDir` and `validation` suites).
+* @returns A single agent tool: `run_validation`.
+*/
+function makeValidationTool(config) {
+	return defineTool({
+		name: "run_validation",
+		description: "Run the validation suite appropriate for a given risk level. 'low' runs only typecheck. 'medium' adds unit tests. 'high' adds build and integration tests. All commands are allowlisted — arbitrary commands are rejected. Returns success status and per-command output.",
+		inputSchema: z.object({
+			/** Risk level computed by `classify_commit_risk`. Determines which suite to run. */
+			riskLevel: z.enum([
+				"low",
+				"medium",
+				"high"
+			]).describe("Risk level determines which suite to run"),
+			/**
+			* Optional additional commands to append to the standard suite.
+			* Useful for customization-specific verification commands listed in
+			* `customizations.yaml` under `testCommands`.
+			* Each command must still match the `ALLOWED_COMMAND_PREFIXES` allowlist.
+			*/
+			extraCommands: z.array(z.string()).optional().describe("Additional commands to append, must match the allowed prefix list")
+		}),
+		execute: async ({ riskLevel, extraCommands = [] }) => {
+			if (config.sync.dryRun) return {
+				dryRun: true,
+				results: [],
+				allPassed: true
+			};
+			const results = runValidationSuite([...{
+				low: config.validation.low,
+				medium: config.validation.medium,
+				high: config.validation.high
+			}[riskLevel], ...extraCommands], config.workingDir);
+			return {
+				riskLevel,
+				results,
+				allPassed: results.every((r) => r.success)
+			};
+		},
+		timeoutMs: 3e5
+	});
+}
+//#endregion
+//#region src/github/github-tools.ts
+/**
+* @file github/github-tools.ts
+*
+* GitHub API tools that allow the agent to manage pull requests on the fork
+* repository.  All operations go through the official `@octokit/rest` client
+* which enforces HTTPS and authenticated requests.
+*
+* The three tools returned by `makeGitHubTools` cover the PR lifecycle:
+*  1. `find_existing_sync_pr` — check whether a previous run already opened a PR,
+*     and if so, recover its machine-readable state so the current run can resume.
+*  2. `create_sync_pr`        — open a new draft PR with the sync branch, embedding
+*     both human-readable Markdown and a hidden machine-readable state block.
+*  3. `add_human_review_comment` — flag specific files or decisions for a human
+*     reviewer by posting a comment on the PR.
+*
+* **Idempotency** is achieved via `STATE_MARKER_START/END` HTML comment markers
+* embedded inside the PR body.  On each run the agent first calls
+* `find_existing_sync_pr`, which extracts and parses the JSON state block if
+* present, allowing the run to skip already-processed commits.
+*
+* **Authentication** is read from the `GITHUB_TOKEN` environment variable at
+* tool invocation time (not at module load time) so that the token is never
+* stored in process memory longer than necessary.
+*/
+/**
+* Creates and returns an authenticated Octokit instance using the `GITHUB_TOKEN`
+* environment variable.
+*
+* Called inside each tool's `execute` function rather than once at module level
+* to keep the token out of long-lived closures.
+*
+* @returns Authenticated `Octokit` REST client.
+* @throws If `GITHUB_TOKEN` is not set in the environment.
+*/
+function makeOctokit() {
+	const token = process.env.GITHUB_TOKEN;
+	if (!token) throw new Error("GITHUB_TOKEN environment variable is required");
+	return new Octokit({ auth: token });
+}
+/**
+* Parses an `"owner/repo"` string into its component parts.
+*
+* @param repoStr - Repository string in `"owner/repo"` format.
+* @returns An object with `owner` and `repo` string fields.
+* @throws If the string does not contain exactly one `/` separator.
+*/
+function parseRepo(repoStr) {
+	const [owner, repo] = repoStr.split("/");
+	if (!owner || !repo) throw new Error(`Invalid repo format: "${repoStr}", expected "owner/repo"`);
+	return {
+		owner,
+		repo
+	};
+}
+/**
+* Opening delimiter of the hidden JSON state block embedded in the PR body.
+*
+* The state block is wrapped in an HTML comment so it is invisible in the
+* rendered PR view but can be extracted programmatically on re-runs.
+* Example embedded block:
+* ```
+* <!-- backport-agent-state
+* { "processedShas": ["abc123", "def456"] }
+* -->
+* ```
+*/
+var STATE_MARKER_START = "<!-- backport-agent-state\n";
+/**
+* Closing delimiter of the hidden JSON state block embedded in the PR body.
+* @see STATE_MARKER_START
+*/
+var STATE_MARKER_END = "\n-->";
+/**
+* Builds and returns the three GitHub API agent tools.
+*
+* All tools capture `fork`, `upstream`, and `sync` from the config via closure.
+* In dry-run mode, every tool returns early with `{ dryRun: true }` and performs
+* no network requests.
+*
+* @param config - Validated `SyncConfig` loaded from `config.json`.
+* @returns Array of three agent tools: `[findExistingPrTool, createSyncPrTool, addHumanReviewCommentTool]`.
+*/
+function makeGitHubTools(config) {
+	const { fork, upstream, sync } = config;
+	return [
+		defineTool({
+			name: "find_existing_sync_pr",
+			description: "Search for an existing open sync PR created by the backport agent. Returns the PR number and current state JSON if found, null otherwise.",
+			inputSchema: z.object({}),
+			execute: async () => {
+				if (sync.dryRun) return {
+					pr: null,
+					dryRun: true
+				};
+				const octokit = makeOctokit();
+				const { owner, repo } = parseRepo(fork.repo);
+				const { data: prs } = await octokit.pulls.list({
+					owner,
+					repo,
+					state: "open",
+					head: `${owner}:${sync.branchPrefix}`,
+					per_page: 10
+				});
+				const agentPr = prs.find((pr) => pr.title.startsWith("Sync upstream") && pr.body?.includes(STATE_MARKER_START));
+				if (!agentPr) return { pr: null };
+				let agentState = null;
+				if (agentPr.body) {
+					const start = agentPr.body.indexOf(STATE_MARKER_START);
+					const end = agentPr.body.indexOf(STATE_MARKER_END, start);
+					if (start !== -1 && end !== -1) try {
+						agentState = JSON.parse(agentPr.body.slice(start + 26, end));
+					} catch {
+						agentState = null;
+					}
+				}
+				return { pr: {
+					number: agentPr.number,
+					url: agentPr.html_url,
+					state: agentState
+				} };
+			}
+		}),
+		defineTool({
+			name: "create_sync_pr",
+			description: "Create a draft pull request on the fork repository with the sync branch. Embeds a hidden state block for idempotent re-runs. Returns the PR URL.",
+			inputSchema: z.object({
+				/** Name of the local/remote sync branch created by `create_sync_branch`. */
+				branchName: z.string(),
+				/** Human-readable Markdown body shown in the GitHub PR UI. */
+				markdownBody: z.string().describe("Human-readable PR body in Markdown"),
+				/** Machine-readable JSON state to embed as a hidden comment for re-run idempotency. */
+				agentState: z.record(z.string(), z.unknown()).describe("Machine-readable state to embed in the PR body"),
+				/** Labels to apply to the PR.  Defaults to `["sync", "agent-generated"]`. */
+				labels: z.array(z.string()).default(["sync", "agent-generated"])
+			}),
+			execute: async ({ branchName, markdownBody, agentState, labels }) => {
+				if (sync.dryRun) return {
+					url: null,
+					dryRun: true
+				};
+				const octokit = makeOctokit();
+				const { owner, repo } = parseRepo(fork.repo);
+				const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+				const body = `${markdownBody}\n\n${`${STATE_MARKER_START}${JSON.stringify(agentState, null, 2)}${STATE_MARKER_END}`}`;
+				const { data: pr } = await octokit.pulls.create({
+					owner,
+					repo,
+					title: `Sync upstream ${upstream.branch} into ${fork.branch} (${date})`,
+					body,
+					head: branchName,
+					base: fork.branch,
+					draft: true
+				});
+				try {
+					await octokit.issues.addLabels({
+						owner,
+						repo,
+						issue_number: pr.number,
+						labels
+					});
+				} catch {}
+				return {
+					url: pr.html_url,
+					number: pr.number
+				};
+			}
+		}),
+		defineTool({
+			name: "add_human_review_comment",
+			description: "Add a comment to the sync PR flagging a specific file or decision for human review. Use when the agent cannot safely resolve a conflict automatically.",
+			inputSchema: z.object({
+				/** PR number on the fork repository to comment on. */
+				prNumber: z.number().int(),
+				/** Markdown-formatted comment body explaining what needs human attention. */
+				comment: z.string().describe("Markdown comment explaining what needs human attention")
+			}),
+			execute: async ({ prNumber, comment }) => {
+				if (sync.dryRun) return {
+					commented: false,
+					dryRun: true
+				};
+				const octokit = makeOctokit();
+				const { owner, repo } = parseRepo(fork.repo);
+				await octokit.issues.createComment({
+					owner,
+					repo,
+					issue_number: prNumber,
+					body: comment
+				});
+				return { commented: true };
+			}
+		})
+	];
+}
+//#endregion
+//#region src/reports/report-tools.ts
+/**
+* @file reports/report-tools.ts
+*
+* Factory that creates the `generate_report` agent tool.
+*
+* The report tool is the **terminal step** of every sync run: the agent calls it
+* after processing all candidate commits.  Setting `lifecycle: { completesRun: true }`
+* signals to the `@sctg/cline-sdk` runtime that the agent should stop after this
+* tool returns, so the tool doubles as both report generator and run terminator.
+*
+* The tool produces:
+*  - A human-readable **Markdown string** suitable for use as a GitHub PR body.
+*  - A compact **agentState** object that can be embedded in the PR body (hidden
+*    HTML comment) for idempotent re-runs (see `github-tools.ts`).
+*  - Boolean flags `allPassed` and `needsHumanReview` for caller logic.
+*  - A detailed **Markdown file** written to `config.report.destination` combining
+*    the PR-body summary, a Mermaid workflow diagram generated by the fast model,
+*    and a full transcript of every AI sub-agent call from the prompts JSONL log.
+*
+* Report sections (PR body):
+*  1. Header — date, upstream ref, fork ref, sync branch name.
+*  2. Summary — counts of applied / needs-review / blocked commits.
+*  3. Applied commits — listed with risk badges and conflict-resolution notes.
+*  4. Human review required — conflicted or validation-failed commits with reasons.
+*  5. Blocked commits — SHAs that were not attempted at all.
+*  6. Agent decision log — ordered audit trail of key agent decisions.
+*
+* Additional sections (detailed file only):
+*  7. Mermaid workflow diagram — generated by the fast LLM from the run summary.
+*  8. AI sub-agent call log — full prompt/response transcript from the JSONL log.
+*/
+/**
+* Reads the JSONL prompt log, returning all valid entries.
+* Silently skips malformed lines so a corrupt log cannot block the report.
+*/
+function readPromptLog(logPath) {
+	if (!existsSync(logPath)) return [];
+	try {
+		return readFileSync(logPath, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+			try {
+				return [JSON.parse(line)];
+			} catch {
+				return [];
+			}
+		});
+	} catch {
+		return [];
+	}
+}
+/**
+* Instantiates a minimal sub-Agent with no tools for a single reasoning turn.
+* Identical in purpose to the helper in `ai-tools.ts` but local to avoid a
+* cross-module import cycle.
+*/
+function makeReportSubAgent(modelId, systemPrompt) {
+	return new Agent({
+		providerId: "keypoollive",
+		modelId,
+		apiKey: "auto",
+		systemPrompt,
+		tools: []
+	});
+}
+/**
+* Calls the fast model to produce a Mermaid flowchart summarising the agent run.
+* Returns a fenced mermaid code block string, or a fallback placeholder on error.
+*/
+async function generateMermaidDiagram(config, runSummary) {
+	const systemPrompt = `You are a technical diagram generator. When given a summary of a Git backport agent run, \
+produce a single Mermaid flowchart (flowchart TD) that visually represents: \
+(1) each candidate commit as a node labelled with its short SHA and subject, \
+(2) the risk level applied to each commit (low / medium / high), \
+(3) which AI tools were invoked (analyze_commit_for_backport, check_customization_compatibility, resolve_conflict_with_ai), \
+(4) the final disposition of each commit (applied ✅, blocked ⛔, needs-review ⚠️, skipped ⟳). \
+Use colour-coded styles: applied=green, blocked=red, needs-review=orange, skipped=grey. \
+Output ONLY the raw Mermaid code, no prose, no code fence.`;
+	const userPrompt = `Agent run summary:\n\n${runSummary}\n\nOutput the Mermaid flowchart now.`;
+	try {
+		return "```mermaid\n" + ((await makeReportSubAgent(config.models.fast, systemPrompt).run(userPrompt)).outputText ?? "").trim().replace(/^```(?:mermaid)?\n?/i, "").replace(/\n?```$/, "").trim() + "\n```";
+	} catch (err) {
+		return `<!-- Mermaid generation failed: ${err instanceof Error ? err.message : String(err)} -->`;
+	}
+}
+/**
+* Zod schema for the result of processing a single upstream commit.
+*
+* The agent populates one `CommitResult` per candidate commit processed during
+* the run.  These are aggregated by the report tool to produce the final summary.
+*/
+var CommitResultSchema = z.object({
+	/** Full SHA of the upstream commit. */
+	sha: z.string(),
+	/** Commit subject line (first line of the message). */
+	subject: z.string(),
+	/** Risk level assigned by `classify_commit_risk`. */
+	riskLevel: z.enum([
+		"low",
+		"medium",
+		"high"
+	]),
+	/**
+	* Final disposition of this commit:
+	*  - `"applied"`           — cherry-picked cleanly with no conflicts.
+	*  - `"skipped"`           — already applied in the fork (git cherry found equivalent patch).
+	*  - `"conflict-resolved"` — had conflicts that the agent resolved automatically.
+	*  - `"conflict-blocked"`  — had conflicts the agent could not safely resolve; needs human review.
+	*  - `"validation-failed"` — cherry-picked cleanly but the validation suite failed.
+	*/
+	status: z.enum([
+		"applied",
+		"skipped",
+		"conflict-resolved",
+		"conflict-blocked",
+		"validation-failed"
+	]),
+	/** Paths of files that had merge conflicts (populated for conflict-* statuses). */
+	conflictedFiles: z.array(z.string()).optional(),
+	/** Human-readable reasons why this commit needs manual review. */
+	humanReviewReasons: z.array(z.string()).optional(),
+	/** Per-command validation results, populated when `status === "validation-failed"`. */
+	validationResults: z.array(z.object({
+		command: z.string(),
+		success: z.boolean(),
+		output: z.string()
+	})).optional()
+});
+/**
+* Builds and returns the `generate_report` agent tool.
+*
+* @param config       - Validated `SyncConfig` — used for model IDs and `report.destination`.
+* @param promptLogPath - Absolute path to the JSONL file written by `logPrompt()` in ai-tools.ts.
+* @returns A single agent tool: `generate_report` (with `completesRun: true`).
+*/
+function makeReportTool(config, promptLogPath) {
+	return defineTool({
+		name: "generate_report",
+		description: "Generate the final sync report as a Markdown string suitable for a PR body. Call this as the LAST step after all commits have been processed. Returns the report text AND signals that the agent run is complete.",
+		inputSchema: z.object({
+			/** Name of the sync branch, or `null` in dry-run mode. */
+			syncBranch: z.string().nullable(),
+			/** Full ref of the upstream branch, e.g. `"upstream/main"`. */
+			upstreamRef: z.string(),
+			/** Full ref of the fork branch, e.g. `"origin/main"`. */
+			forkRef: z.string(),
+			/** Array of per-commit results — one entry per processed candidate. */
+			commitResults: z.array(CommitResultSchema),
+			/** Commits that were not attempted at all, with mandatory reasons. */
+			blockedCommits: z.array(z.object({
+				/** Full or abbreviated SHA of the blocked commit. */
+				sha: z.string(),
+				/** Human-readable reason why this commit was not attempted. */
+				reason: z.string().describe("Why this commit was not attempted (AI analysis result, policy, etc.)"),
+				/** Risk level from classify_commit_risk, if known. */
+				riskLevel: z.enum([
+					"low",
+					"medium",
+					"high"
+				]).optional()
+			})).describe("Commits not attempted, each with a specific reason"),
+			/**
+			* All SHAs returned by list_candidate_commits — used to detect silently dropped commits.
+			* Pass the complete list so the report can cross-check accountability.
+			*/
+			allCandidateShas: z.array(z.string()).optional().describe("Complete list of SHAs from list_candidate_commits, used to detect unaccounted commits"),
+			/** Ordered list of key decisions the agent made during this run, for audit purposes. */
+			agentDecisions: z.array(z.string()).describe("Audit trail of key decisions made during this run")
+		}),
+		lifecycle: { completesRun: true },
+		execute: async ({ syncBranch, upstreamRef, forkRef, commitResults, blockedCommits, agentDecisions, allCandidateShas }) => {
+			const date = (/* @__PURE__ */ new Date()).toISOString();
+			const timestampSlug = date.replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+			const applied = commitResults.filter((r) => ["applied", "conflict-resolved"].includes(r.status));
+			const needsReview = commitResults.filter((r) => ["conflict-blocked", "validation-failed"].includes(r.status));
+			const allPassed = needsReview.length === 0;
+			const processedShas = new Set([...commitResults.map((r) => r.sha), ...blockedCommits.map((c) => c.sha)]);
+			const unaccounted = (allCandidateShas ?? []).filter((sha) => !processedShas.has(sha) && !processedShas.has(sha.slice(0, 8)));
+			const prBodyLines = [
+				"## Backport Agent — Sync Report",
+				"",
+				`**Date**: ${date}`,
+				`**Upstream ref**: \`${upstreamRef}\``,
+				`**Fork ref**: \`${forkRef}\``,
+				`**Sync branch**: ${syncBranch ? `\`${syncBranch}\`` : "_dry-run (no branch created)_"}`,
+				"",
+				"### Summary",
+				"",
+				`- ✅ Applied: ${applied.length}`,
+				`- ⚠️ Needs human review: ${needsReview.length}`,
+				`- ⛔ Blocked (not attempted): ${blockedCommits.length}`,
+				...unaccounted.length > 0 ? [`- 🔴 Unaccounted (agent bug): ${unaccounted.length}`] : [],
+				""
+			];
+			if (applied.length > 0) {
+				prBodyLines.push("### Applied commits", "");
+				for (const r of applied) {
+					const badge = r.status === "conflict-resolved" ? " _(conflict resolved by agent)_" : "";
+					prBodyLines.push(`- \`${r.sha.slice(0, 8)}\` [${r.riskLevel}] ${r.subject}${badge}`);
+				}
+				prBodyLines.push("");
+			}
+			if (needsReview.length > 0) {
+				prBodyLines.push("### ⚠️ Human review required", "");
+				for (const r of needsReview) {
+					prBodyLines.push(`- \`${r.sha.slice(0, 8)}\` ${r.subject}`);
+					if (r.conflictedFiles?.length) prBodyLines.push(`  - Conflicted files: ${r.conflictedFiles.join(", ")}`);
+					if (r.humanReviewReasons?.length) for (const reason of r.humanReviewReasons) prBodyLines.push(`  - ${reason}`);
+				}
+				prBodyLines.push("");
+			}
+			if (blockedCommits.length > 0) {
+				prBodyLines.push("### Blocked commits (not attempted)", "");
+				for (const { sha, reason, riskLevel } of blockedCommits) {
+					const badge = riskLevel ? ` [${riskLevel}]` : "";
+					prBodyLines.push(`- \`${sha.slice(0, 8)}\`${badge} — ${reason}`);
+				}
+				prBodyLines.push("");
+			}
+			if (unaccounted.length > 0) {
+				prBodyLines.push("### 🔴 Unaccounted commits (agent processing gap)", "");
+				for (const sha of unaccounted) prBodyLines.push(`- \`${sha.slice(0, 8)}\` — not processed or reported by agent`);
+				prBodyLines.push("");
+			}
+			if (agentDecisions.length > 0) {
+				prBodyLines.push("### Agent decision log", "");
+				for (const decision of agentDecisions) prBodyLines.push(`- ${decision}`);
+				prBodyLines.push("");
+			}
+			const report = prBodyLines.join("\n");
+			const agentState = {
+				generatedAt: date,
+				appliedShas: applied.map((r) => r.sha),
+				blockedShas: blockedCommits.map((c) => c.sha),
+				needsReviewShas: needsReview.map((r) => r.sha),
+				unaccountedShas: unaccounted
+			};
+			const mermaidBlock = await generateMermaidDiagram(config, [
+				`Upstream: ${upstreamRef}  Fork: ${forkRef}`,
+				`Applied (${applied.length}): ${applied.map((r) => `${r.sha.slice(0, 8)} [${r.riskLevel}] ${r.subject}`).join(" | ") || "none"}`,
+				`Blocked (${blockedCommits.length}): ${blockedCommits.map((c) => `${c.sha.slice(0, 8)} — ${c.reason}`).join(" | ") || "none"}`,
+				`Needs review (${needsReview.length}): ${needsReview.map((r) => r.sha.slice(0, 8)).join(", ") || "none"}`,
+				`AI calls: ${readPromptLog(promptLogPath).map((e) => `${e.tool}(${e.model}, ${e.durationMs}ms)`).join(", ") || "none"}`
+			].join("\n"));
+			const promptEntries = readPromptLog(promptLogPath);
+			const detailedLines = [
+				"# Backport Agent — Detailed Run Report",
+				"",
+				"> This file is generated automatically. It is intended for human analysts and",
+				"> AI reasoning models to assess agent performance, decision quality, and LLM behavior.",
+				"",
+				`**Run timestamp**: ${date}`,
+				`**Models used**: fast=\`${config.models.fast}\`  powerful=\`${config.models.powerful}\``,
+				`**Prompt log**: \`${promptLogPath}\``,
+				"",
+				"---",
+				"",
+				"## Summary (PR body)",
+				"",
+				report,
+				"",
+				"---",
+				"",
+				"## Agent Workflow Diagram",
+				"",
+				"> Generated by the fast model from the run summary. Evaluate the agent's decision path.",
+				"",
+				mermaidBlock,
+				"",
+				"---",
+				"",
+				`## AI Sub-Agent Call Log (${promptEntries.length} call${promptEntries.length === 1 ? "" : "s"})`,
+				"",
+				"> Each entry is one sub-agent invocation. Review prompt/response pairs to assess",
+				"> reasoning quality, hallucinations, and decision accuracy.",
+				""
+			];
+			for (let i = 0; i < promptEntries.length; i++) {
+				const e = promptEntries[i];
+				const statusBadge = e.error ? "❌ Error" : "✅ OK";
+				detailedLines.push(`### Call ${i + 1} / ${promptEntries.length} — \`${e.tool}\` ${statusBadge}`, "", `| Field | Value |`, `|---|---|`, `| **Timestamp** | ${e.timestamp} |`, `| **Tool** | \`${e.tool}\` |`, `| **Model** | \`${e.model}\` |`, `| **Duration** | ${e.durationMs} ms |`, ...e.inputTokens != null ? [`| **Tokens in** | ${e.inputTokens} |`] : [], ...e.outputTokens != null ? [`| **Tokens out** | ${e.outputTokens} |`] : [], ...e.cacheReadTokens != null && e.cacheReadTokens > 0 ? [`| **Cache read** | ${e.cacheReadTokens} |`] : [], ...e.cacheWriteTokens != null && e.cacheWriteTokens > 0 ? [`| **Cache write** | ${e.cacheWriteTokens} |`] : [], ...e.totalCost != null ? [`| **Cost** | $${e.totalCost.toFixed(6)} |`] : [], ...e.error ? [`| **Error** | ${e.error} |`] : [], "", "**Prompt sent to sub-agent:**", "", "```", e.prompt, "```", "", "**Response received:**", "", "```", e.response || "(empty)", "```", "", "---", "");
+			}
+			if (promptEntries.length === 0) detailedLines.push("_No AI sub-agent calls were made during this run._", "", "---", "");
+			if (promptEntries.length > 0) {
+				const totalMs = promptEntries.reduce((sum, e) => sum + e.durationMs, 0);
+				const totalIn = promptEntries.reduce((sum, e) => sum + (e.inputTokens ?? 0), 0);
+				const totalOut = promptEntries.reduce((sum, e) => sum + (e.outputTokens ?? 0), 0);
+				const totalCost = promptEntries.reduce((sum, e) => sum + (e.totalCost ?? 0), 0);
+				const byTool = /* @__PURE__ */ new Map();
+				for (const e of promptEntries) {
+					const cur = byTool.get(e.tool) ?? {
+						count: 0,
+						totalMs: 0,
+						totalIn: 0,
+						totalOut: 0
+					};
+					byTool.set(e.tool, {
+						count: cur.count + 1,
+						totalMs: cur.totalMs + e.durationMs,
+						totalIn: cur.totalIn + (e.inputTokens ?? 0),
+						totalOut: cur.totalOut + (e.outputTokens ?? 0)
+					});
+				}
+				const hasTokenData = totalIn > 0 || totalOut > 0;
+				detailedLines.push("## Performance Summary", "", `**Total AI time**: ${totalMs} ms across ${promptEntries.length} call(s)`, ...hasTokenData ? [
+					`**Total input tokens**: ${totalIn}`,
+					`**Total output tokens**: ${totalOut}`,
+					...totalCost > 0 ? [`**Total estimated cost**: $${totalCost.toFixed(6)}`] : []
+				] : [], "", hasTokenData ? "| Tool | Calls | Total ms | Avg ms | Input tok | Output tok |" : "| Tool | Calls | Total ms | Avg ms |", hasTokenData ? "|---|---|---|---|---|---|" : "|---|---|---|---|", ...[...byTool.entries()].map(([tool, s]) => hasTokenData ? `| \`${tool}\` | ${s.count} | ${s.totalMs} | ${Math.round(s.totalMs / s.count)} | ${s.totalIn} | ${s.totalOut} |` : `| \`${tool}\` | ${s.count} | ${s.totalMs} | ${Math.round(s.totalMs / s.count)} |`), "");
+			}
+			if (config.sync.dryRun) process.stderr.write("[Report] Dry-run mode — detailed report not written to disk.\n");
+			else try {
+				const destDir = resolve(config.workingDir, config.report.destination);
+				mkdirSync(destDir, { recursive: true });
+				const reportFilename = `report.${timestampSlug}.md`;
+				const reportFilePath = join(destDir, reportFilename);
+				writeFileSync(reportFilePath, detailedLines.join("\n"), "utf8");
+				process.stderr.write(`[Report] Detailed report written to: ${reportFilePath}\n`);
+				const relPath = relative(config.workingDir, reportFilePath);
+				if (syncBranch && !relPath.startsWith("..")) {
+					git(["add", relPath], config.workingDir);
+					git([
+						"commit",
+						"-m",
+						`chore(backport): add run report ${reportFilename}`
+					], config.workingDir);
+					git([
+						"push",
+						config.fork.remote,
+						syncBranch
+					], config.workingDir);
+					process.stderr.write(`[Report] Report committed and pushed to ${config.fork.remote}/${syncBranch}\n`);
+				}
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				process.stderr.write(`[Report] Warning: could not write/commit detailed report: ${msg}\n`);
+			}
+			return {
+				report,
+				agentState,
+				allPassed,
+				needsHumanReview: needsReview.length > 0
+			};
+		}
+	});
+}
+//#endregion
+//#region src/ai/ai-tools.ts
+/**
+* @file ai/ai-tools.ts
+*
+* AI-powered agent tools that spawn focused sub-agents for tasks requiring
+* deep language model reasoning beyond what the deterministic rule engine
+* can provide.
+*
+* **Why sub-agents?**
+* The main backport agent drives the orchestration loop and calls deterministic
+* git/GitHub/validation tools.  Some decisions — conflict resolution, semantic
+* understanding of diffs, customisation compatibility — benefit from a dedicated
+* LLM call with a narrowly scoped system prompt and no distracting tool context.
+* Spawning a sub-`Agent` with `tools: []` gives exactly that: a single-turn
+* reasoning call that returns structured JSON.
+*
+* **Tools exported by `makeAiTools`:**
+*
+* 1. `resolve_conflict_with_ai` — Given a three-way conflict (base / ours /
+*    theirs), produce a resolved file body with no conflict markers.
+*    Uses `config.models.powerful` for maximum reasoning quality.
+*
+* 2. `analyze_commit_for_backport` — Given a commit SHA, message, diff, and
+*    changed-file list, produce a structured semantic assessment of what the
+*    commit does and how risky it is to backport.
+*    Uses `config.models.fast` (analytical but not critical-path).
+*
+* 3. `check_customization_compatibility` — Given a diff and a list of
+*    customisation records (pattern + description), reason about whether the
+*    upstream changes could semantically break fork-specific behaviour even
+*    if no textual conflict exists.
+*    Uses `config.models.fast`.
+*
+* **JSON extraction:**
+* Sub-agents are instructed to emit only a JSON object.  In practice, some
+* models wrap the object in a markdown code fence.  `extractJson` strips the
+* fence when present so `JSON.parse` always receives clean text.
+*
+* **Error handling:**
+* If the sub-agent call fails (network error, model error, parse error), each
+* tool returns a structured fallback object with `error` set rather than
+* throwing, so the main agent can log the failure and continue.
+*/
+/**
+* Attempts to extract a JSON value from raw LLM output.
+*
+* The LLM may wrap its JSON in a markdown code fence (```` ```json … ``` ````
+* or ```` ``` … ``` ````).  This helper strips the fences when present so
+* `JSON.parse` receives valid JSON text.
+*
+* @typeParam T - Expected shape of the parsed value.
+* @param text - Raw string output from the sub-agent.
+* @returns The parsed value cast to `T`.
+* @throws `SyntaxError` if no valid JSON can be found in the text.
+*/
+function extractJson(text) {
+	const jsonFenceMatch = text.match(/```json\s*([\s\S]*?)```/);
+	if (jsonFenceMatch) return JSON.parse(jsonFenceMatch[1].trim());
+	const genericFenceMatch = text.match(/```\s*([\s\S]*?)```/);
+	if (genericFenceMatch) return JSON.parse(genericFenceMatch[1].trim());
+	const inlineObjectMatch = text.match(/\{[\s\S]*\}/);
+	if (inlineObjectMatch) return JSON.parse(inlineObjectMatch[0]);
+	return JSON.parse(text.trim());
+}
+/**
+* Appends a single prompt/response record to the run's JSONL log file.
+*
+* The log file path is `./run-<timestamp>.prompts.jsonl` (relative to cwd).
+* It is created on first write and appended on subsequent calls.
+* Each line is a self-contained JSON object — suitable for streaming analysis
+* and incremental loading without parsing the entire file.
+*
+* @param logPath    - Absolute path to the JSONL log file for this run.
+* @param toolName   - The backport agent tool that invoked the sub-agent.
+* @param modelId    - LLM model identifier used for this call.
+* @param prompt     - Full user prompt sent to the sub-agent.
+* @param response   - Raw text response received from the sub-agent.
+* @param durationMs - Wall-clock time for the sub-agent call in milliseconds.
+* @param error      - Optional error message if the call failed.
+* @param usage      - Optional token usage breakdown from the LLM response.
+*/
+function logPrompt(logPath, toolName, modelId, prompt, response, durationMs, error, usage) {
+	const record = {
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		tool: toolName,
+		model: modelId,
+		durationMs,
+		prompt,
+		response,
+		...error ? { error } : {},
+		...usage ? {
+			inputTokens: usage.inputTokens,
+			outputTokens: usage.outputTokens,
+			cacheReadTokens: usage.cacheReadTokens,
+			cacheWriteTokens: usage.cacheWriteTokens,
+			...usage.totalCost != null ? { totalCost: usage.totalCost } : {}
+		} : {}
+	};
+	try {
+		appendFileSync(logPath, JSON.stringify(record) + "\n", "utf8");
+	} catch {
+		process.stderr.write(`[PromptLogger] Warning: could not write to ${logPath}\n`);
+	}
+}
+/**
+* Creates a minimal sub-`Agent` configured with the keypoollive provider.
+*
+* The sub-agent has an empty tools array — it performs a single reasoning turn
+* and returns its text output via `result.outputText`.
+*
+* @param modelId     - Model identifier to use (fast or powerful).
+* @param systemPrompt - System prompt that scopes the sub-agent's behaviour.
+* @returns A configured `Agent` instance ready to call `.run(userPrompt)`.
+*/
+function makeSubAgent(modelId, systemPrompt) {
+	return new Agent({
+		providerId: "keypoollive",
+		modelId,
+		apiKey: "auto",
+		systemPrompt,
+		tools: []
+	});
+}
+/**
+* Builds and returns all AI-powered agent tools pre-bound to the provided config.
+*
+* @param config  - Validated `SyncConfig` loaded from `config.json`.
+* @param logPath - Absolute path to the JSONL prompt log file for this run.
+*                  Created by `main.ts` as `run-<timestamp>.prompts.jsonl`.
+* @returns Array of three agent tools for AI-assisted analysis.
+*/
+function makeAiTools(config, logPath) {
+	return [
+		defineTool({
+			name: "resolve_conflict_with_ai",
+			description: "Resolves a three-way merge conflict in a single file using AI reasoning. Provide the base (common ancestor), our (fork) version, and their (upstream) version of the file, plus the upstream commit message for context. Returns the resolved file content with no conflict markers, a confidence level, and a brief reasoning summary. Use this when cherry_pick_commit reports a conflict and you need to resolve a specific file.",
+			inputSchema: z.object({
+				/**
+				* Repository-relative path to the conflicted file (e.g. `src/core/api/index.ts`).
+				* Used only for display/reasoning context — no filesystem access is performed.
+				*/
+				filePath: z.string().describe("Repo-relative path of the conflicted file"),
+				/**
+				* Content of the file at the common ancestor commit (merge base).
+				* May be an empty string when the file was created on both branches independently.
+				*/
+				baseContent: z.string().describe("File content at the common ancestor (merge base); empty string if none"),
+				/**
+				* Content of the file in the fork branch (our version, with our customisations).
+				*/
+				ourContent: z.string().describe("File content in the fork branch (our customised version)"),
+				/**
+				* Content of the file in the upstream commit (their version).
+				*/
+				theirContent: z.string().describe("File content from the upstream commit (their version)"),
+				/**
+				* The full commit message of the upstream change being cherry-picked.
+				* Helps the model understand the intent of the upstream change.
+				*/
+				commitMessage: z.string().describe("Upstream commit message, used to understand the intent of the change"),
+				/**
+				* Optional: a human-readable note describing relevant fork customisations
+				* in this file (e.g. "This file contains the keypoollive provider registration").
+				* When provided, the model uses it to decide which parts must not be overwritten.
+				*/
+				customizationNote: z.string().optional().describe("Optional description of fork customisations in this file to help preserve them")
+			}),
+			execute: async ({ filePath, baseContent, ourContent, theirContent, commitMessage, customizationNote }) => {
+				/**
+				* System prompt focuses the sub-agent exclusively on conflict resolution.
+				* The model must output only a single JSON object.
+				*/
+				const systemPrompt = [
+					"You are an expert software engineer specialising in Git merge conflict resolution.",
+					"Your sole task is to produce a clean merged version of a conflicted file.",
+					"",
+					"Rules:",
+					"- Output ONLY a valid JSON object. No prose, no explanations outside the JSON.",
+					"- The JSON must have exactly three fields: \"resolvedContent\", \"confidence\", \"reasoning\".",
+					"- \"resolvedContent\": the complete resolved file content as a string. MUST contain zero conflict markers (<<<<<<<, =======, >>>>>>>).",
+					"- \"confidence\": one of \"high\", \"medium\", or \"low\".",
+					"  - \"high\": you are certain the resolution is correct and preserves all intent.",
+					"  - \"medium\": the resolution is plausible but you had to make a judgment call.",
+					"  - \"low\": the resolution is uncertain; a human should review it.",
+					"- \"reasoning\": a single sentence explaining the key decision you made.",
+					"",
+					"Resolution strategy:",
+					"1. Understand what the UPSTREAM change was trying to achieve (read the commit message).",
+					"2. Understand what the FORK version preserves (customisations, local patches).",
+					"3. Integrate both intents: keep fork customisations AND apply the upstream change where safe.",
+					"4. When in doubt, prefer preserving fork customisations and mark confidence as 'low'."
+				].join("\n");
+				const customizationSection = customizationNote ? `\nFork customisation context:\n${customizationNote}\n` : "";
+				const userPrompt = `Resolve the merge conflict in file: ${filePath}\nUpstream commit message: ${commitMessage}\n` + customizationSection + `\n--- BASE (common ancestor) ---\n${baseContent || "(file did not exist at merge base)"}\n\n--- OURS (fork version) ---\n${ourContent}\n\n--- THEIRS (upstream version) ---\n${theirContent}\n\nOutput the JSON object now.`;
+				const modelsToTry = [{
+					modelId: config.models.specialist,
+					label: "specialist"
+				}, {
+					modelId: config.models.powerful,
+					label: "powerful"
+				}];
+				let lastError = null;
+				for (const { modelId, label } of modelsToTry) try {
+					const subAgent = makeSubAgent(modelId, systemPrompt);
+					const t0 = Date.now();
+					const result = await subAgent.run(userPrompt);
+					const durationMs = Date.now() - t0;
+					logPrompt(logPath, "resolve_conflict_with_ai", modelId, userPrompt, result.outputText ?? "", durationMs, null, result.usage);
+					const output = extractJson(result.outputText ?? "");
+					return {
+						resolvedContent: output.resolvedContent,
+						confidence: output.confidence,
+						reasoning: output.reasoning,
+						error: null
+					};
+				} catch (err) {
+					lastError = err instanceof Error ? err.message : String(err);
+					process.stderr.write(`[resolve_conflict_with_ai] ${label} model (${modelId}) failed: ${lastError.slice(0, 120)} — ${label === "specialist" ? "retrying with powerful model" : "giving up"}\n`);
+					logPrompt(logPath, "resolve_conflict_with_ai", modelId, userPrompt, "", 0, lastError);
+				}
+				return {
+					resolvedContent: "",
+					confidence: "low",
+					reasoning: `AI resolution failed on all models: ${lastError}`,
+					error: lastError
+				};
+			}
+		}),
+		defineTool({
+			name: "analyze_commit_for_backport",
+			description: "Performs a semantic analysis of an upstream commit to understand its intent and assess how complex it is to backport into the fork. Returns a structured assessment with a human-readable summary, key changes, complexity rating, semantic risk factors, and a backport recommendation. Use this before cherry-picking a high-risk commit to better understand what it does.",
+			inputSchema: z.object({
+				/**
+				* Full commit SHA (40-character hex string).
+				*/
+				sha: z.string().describe("Full commit SHA"),
+				/**
+				* The commit's subject + body as returned by `git log --format=%B`.
+				*/
+				commitMessage: z.string().describe("Full commit message (subject + body)"),
+				/**
+				* Full unified diff of the commit as returned by `git show --format=` or
+				* `git diff <parent> <sha>`.
+				*/
+				diff: z.string().describe("Full unified diff of the commit"),
+				/**
+				* List of file paths changed by this commit (relative to repo root).
+				*/
+				changedFiles: z.array(z.string()).describe("List of file paths changed by this commit")
+			}),
+			execute: async ({ sha, commitMessage, diff, changedFiles }) => {
+				const systemPrompt = [
+					"You are an expert software engineer specialising in Git history analysis.",
+					"Your task is to analyse a single upstream commit and assess how complex it is to",
+					"backport it into a heavily customised fork.",
+					"",
+					"Output ONLY a valid JSON object with exactly these fields:",
+					"  \"summary\":             string  — 2-3 sentence description of what this commit does.",
+					"  \"keyChanges\":          string[] — bullet-point list of the most important code changes.",
+					"  \"backportComplexity\":  \"trivial\" | \"moderate\" | \"complex\"",
+					"    - \"trivial\":   small, isolated change with no side effects.",
+					"    - \"moderate\":  meaningful change but scope is clear and contained.",
+					"    - \"complex\":   refactor, API change, or broad change that may interact with customisations.",
+					"  \"semanticRiskFactors\": string[] — list of reasons why this commit could break a fork",
+					"                         (e.g. \"renames exported interface\", \"changes provider registration pattern\").",
+					"                         Empty array if no risks detected.",
+					"  \"recommendation\":      \"apply\" | \"apply-with-care\" | \"review-required\" | \"skip\"",
+					"    - \"apply\":            safe to cherry-pick automatically.",
+					"    - \"apply-with-care\":  cherry-pick but verify validation passes.",
+					"    - \"review-required\":  human should review before merging.",
+					"    - \"skip\":             commit should not be backported."
+				].join("\n");
+				const userPrompt = `Commit SHA: ${sha}\nCommit message:\n${commitMessage}\n\nChanged files (${changedFiles.length}):\n${changedFiles.join("\n")}\n\nDiff:\n${diff}\n\nOutput the JSON object now.`;
+				try {
+					const subAgent = makeSubAgent(config.models.fast, systemPrompt);
+					const t0 = Date.now();
+					const result = await subAgent.run(userPrompt);
+					const durationMs = Date.now() - t0;
+					logPrompt(logPath, "analyze_commit_for_backport", config.models.fast, userPrompt, result.outputText ?? "", durationMs, null, result.usage);
+					const output = extractJson(result.outputText ?? "");
+					return {
+						summary: output.summary,
+						keyChanges: output.keyChanges,
+						backportComplexity: output.backportComplexity,
+						semanticRiskFactors: output.semanticRiskFactors,
+						recommendation: output.recommendation,
+						error: null
+					};
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					logPrompt(logPath, "analyze_commit_for_backport", config.models.fast, userPrompt, "", 0, message);
+					return {
+						summary: `Analysis failed: ${message}`,
+						keyChanges: [],
+						backportComplexity: "complex",
+						semanticRiskFactors: [`AI analysis unavailable: ${message}`],
+						recommendation: "review-required",
+						error: message
+					};
+				}
+			}
+		}),
+		defineTool({
+			name: "check_customization_compatibility",
+			description: "Checks whether an upstream diff is semantically compatible with the fork's customisations. Goes beyond file-path glob matching: the AI reads the customisation descriptions and reasons about whether the upstream change could break declared fork-specific behaviour. Returns a compatibility verdict, a list of affected customisations, semantic conflicts, warnings, and a recommendation. Use this when classify_commit_risk returns 'medium' or 'high' and you want deeper insight.",
+			inputSchema: z.object({
+				/**
+				* Full unified diff of the upstream commit being evaluated.
+				*/
+				diff: z.string().describe("Full unified diff of the upstream commit"),
+				/**
+				* List of customisation entries loaded from `customizations.yaml`.
+				* Each entry has a glob pattern (identifying which files are customised)
+				* and a human-readable description of what the customisation does.
+				*/
+				customizations: z.array(z.object({
+					/**
+					* Glob pattern (e.g. `src/core/api/providers/**`) identifying files
+					* that belong to this customisation zone.
+					*/
+					pattern: z.string().describe("Glob pattern for customised file paths"),
+					/**
+					* Human-readable description of what this customisation does and why
+					* it must be preserved.
+					*/
+					description: z.string().describe("Description of the fork customisation")
+				})).describe("Customisation entries from customizations.yaml")
+			}),
+			execute: async ({ diff, customizations }) => {
+				/**
+				* If there are no customisations defined, there is nothing to check.
+				* Return a trivially compatible result without calling the LLM.
+				*/
+				if (customizations.length === 0) return {
+					compatible: true,
+					affectedCustomizations: [],
+					semanticConflicts: [],
+					warnings: [],
+					recommendation: "No customisations defined; upstream change is safe to apply.",
+					error: null
+				};
+				const customizationList = customizations.map((c, i) => `  ${i + 1}. Pattern: ${c.pattern}\n     Description: ${c.description}`).join("\n");
+				const systemPrompt = [
+					"You are an expert software engineer specialising in fork maintenance and semantic conflict detection.",
+					"Your task is to assess whether an upstream Git diff could break the customised behaviour",
+					"of a fork, given a list of declared customisations.",
+					"",
+					"Output ONLY a valid JSON object with exactly these fields:",
+					"  \"compatible\":             boolean — true if the upstream change is unlikely to break any customisation.",
+					"  \"affectedCustomizations\": string[] — names/patterns of customisations potentially affected.",
+					"  \"semanticConflicts\":      string[] — specific ways the upstream change could break fork behaviour.",
+					"                            Each entry is a concrete description (e.g. \"renames ApiProvider enum",
+					"                            value used by keypoollive provider registration\").",
+					"                            Empty array if no conflicts detected.",
+					"  \"warnings\":               string[] — non-blocking concerns worth noting (e.g. \"touches shared types",
+					"                            used by customised components\").",
+					"                            Empty array if none.",
+					"  \"recommendation\":         string — one sentence advising the agent what to do.",
+					"",
+					"Important: focus on SEMANTIC compatibility, not textual conflicts.",
+					"A change can be textually clean but still break the fork (e.g. renaming an interface",
+					"that the fork's custom provider implements)."
+				].join("\n");
+				const userPrompt = `Declared fork customisations:\n${customizationList}\n\nUpstream diff to evaluate:\n${diff}\n\nOutput the JSON object now.`;
+				try {
+					const subAgent = makeSubAgent(config.models.fast, systemPrompt);
+					const t0 = Date.now();
+					const result = await subAgent.run(userPrompt);
+					const durationMs = Date.now() - t0;
+					logPrompt(logPath, "check_customization_compatibility", config.models.fast, userPrompt, result.outputText ?? "", durationMs, null, result.usage);
+					const output = extractJson(result.outputText ?? "");
+					return {
+						compatible: output.compatible,
+						affectedCustomizations: output.affectedCustomizations,
+						semanticConflicts: output.semanticConflicts,
+						warnings: output.warnings,
+						recommendation: output.recommendation,
+						error: null
+					};
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					logPrompt(logPath, "check_customization_compatibility", config.models.fast, userPrompt, "", 0, message);
+					return {
+						compatible: false,
+						affectedCustomizations: [],
+						semanticConflicts: [],
+						warnings: [`AI compatibility check failed: ${message}`],
+						recommendation: "Treat as potentially incompatible; request human review.",
+						error: message
+					};
+				}
+			}
+		})
+	];
+}
+//#endregion
+//#region src/main.ts
+/**
+* @file main.ts
+*
+* Entry point for the Backport Agent CLI.
+*
+* **Initialization sequence:**
+*  1. Parse CLI arguments (`--verbose`, `--config`, `--backport-customizations`,
+*     `--keypool-vault-url`, `--keypool-live-secret`, `--keypool-state-file`, `--dry-run`).
+*  2. Validate required environment variables (`KEYPOOL_VAULT_URL` or `KEYPOOL_LIVE_SECRET`).
+*  3. Load and validate `config.json` via `loadConfig()`.
+*  4. Load and validate `customizations.yaml` via `loadCustomizations()`.
+*  5. Assemble all agent tools from the individual factory functions.
+*  6. Instantiate the `Agent` with the keypoollive provider, system prompt, and tools.
+*  7. Subscribe to runtime events to stream assistant output to stdout.
+*  8. Call `agent.run(task)` with the sync task description.
+*  9. Print the final report (or exit with code 1 on any fatal error).
+*
+* **Provider:**
+* `keypoollive` with `apiKey: "auto"` uses the `KEYPOOL_VAULT_URL` environment
+* variable to resolve API keys at runtime via an encrypted vault, enabling
+* automatic key rotation without storing secrets in the codebase.
+*/
+{
+	const argv = process.argv.slice(2);
+	function getArgValue(name) {
+		const idx = argv.indexOf(name);
+		return idx !== -1 && idx + 1 < argv.length ? argv[idx + 1] : void 0;
+	}
+	function hasFlag(name) {
+		return argv.includes(name);
+	}
+	if (hasFlag("--verbose")) process.env.VERBOSE = "true";
+	if (hasFlag("--dry-run")) process.env.DRY_RUN = "true";
+	const cliConfig = getArgValue("--config");
+	if (cliConfig) process.env._CLI_CONFIG_PATH = cliConfig;
+	const cliCustomizations = getArgValue("--backport-customizations");
+	if (cliCustomizations) process.env.BACKPORT_CUSTOMIZATIONS = cliCustomizations;
+	const cliVaultUrl = getArgValue("--keypool-vault-url");
+	if (cliVaultUrl) process.env.KEYPOOL_VAULT_URL = cliVaultUrl;
+	const cliLiveSecret = getArgValue("--keypool-live-secret");
+	if (cliLiveSecret) process.env.KEYPOOL_LIVE_SECRET = cliLiveSecret;
+	const cliStateFile = getArgValue("--keypool-state-file");
+	if (cliStateFile) process.env.KEYPOOL_STATE_FILE = cliStateFile;
+}
+{
+	const envPath = resolve(process.cwd(), ".env");
+	if (existsSync(envPath)) {
+		const { config } = await import("dotenv");
+		config({ path: envPath });
+	}
+}
+var SYSTEM_PROMPT = `You are the Backport Agent, a specialist in safely synchronizing a customized Git fork with its upstream repository.
+
+## Your mission
+Integrate upstream commits into the fork branch while preserving all fork-specific customizations.
+Produce a draft pull request with a clear report. Never push directly to the main branch.
+
+## Core workflow (follow this exactly)
+
+1. Call fetch_remotes to ensure refs are up to date.
+2. Call list_candidate_commits to get pending upstream commits (already filtered, newest-last).
+   - Record all returned SHAs immediately. You are accountable for every single one.
+3. For each candidate commit (process ALL of them — no silent skips):
+   a. Call get_commit_details to inspect changed files and diff.
+   b. Call classify_commit_risk to determine risk level deterministically.
+   c. Risk-based decision:
+      - LOW risk: proceed directly to step 5 (cherry-pick). No AI analysis needed.
+      - MEDIUM risk: call analyze_commit_for_backport for context, then proceed to cherry-pick.
+      - HIGH risk (touches a customization zone):
+        * MANDATORY: Call check_customization_compatibility — pass the diff and all affected customization IDs.
+        * MANDATORY: Call analyze_commit_for_backport — pass sha, message, diff, and changed files.
+        * Read both responses carefully:
+          - If both tools confirm the change is SAFE or ORTHOGONAL to the customization (e.g., it modifies a
+            different provider, unrelated docs section, or infrastructure that doesn't overlap with fork code):
+            → proceed to cherry-pick (step 5). Do NOT block on risk level alone.
+          - If the tools identify a genuine semantic conflict (same code paths, incompatible invariants):
+            → add to blockedCommits with a precise reason from the AI analysis.
+          - If uncertain: still attempt the cherry-pick; conflicts will surface in step 5c.
+   d. Commits with alreadyApplied: true → record as "skipped" in commitResults.
+4. Create the sync branch via create_sync_branch (once, before first cherry-pick).
+5. For each non-skipped commit (process lowest risk first):
+   a. Call cherry_pick_commit.
+   b. If success: record as "applied" in commitResults and proceed to next.
+   c. If conflicts: for each conflicted file, call get_conflict_context, then attempt resolution.
+      - Check the \`forcedStrategy\` field returned by get_conflict_context:
+        * \`forcedStrategy: "ours"\`   → use \`forkVersion\` directly as resolvedContent; call apply_resolved_file immediately. No AI call needed.
+        * \`forcedStrategy: "theirs"\` → use \`upstreamVersion\` directly as resolvedContent; call apply_resolved_file immediately. No AI call needed.
+        * \`forcedStrategy: null\`     → proceed with AI resolution below.
+      - (When forcedStrategy is null) Call resolve_conflict_with_ai with the base/ours/theirs content to get an AI-proposed resolution.
+      - If confidence is "high" or "medium": verify no conflict markers remain, then call apply_resolved_file, then continue_cherry_pick.
+      - If confidence is "low" or the tool returned an error: call abort_cherry_pick, mark commit as conflict-blocked.
+6. Call run_validation with the highest risk level encountered in this run.
+7. If validation fails: note it in the report, mark relevant commits as validation-failed.
+8. Call push_sync_branch (unless dry-run).
+9. Call find_existing_sync_pr to check for an existing PR.
+10. Call generate_report with the full summary of all decisions.
+11. Call create_sync_pr with the report as body (unless an existing PR was found and up to date).
+
+## Accountability (enforced — never skip)
+- You received a finite list of SHAs from list_candidate_commits.
+- EVERY SHA must appear in generate_report: either in commitResults (as applied/skipped/conflict-blocked/validation-failed) OR in blockedCommits.
+- No commit may be silently dropped. If you are unsure what to do with a commit, add it to blockedCommits with reason "deferred: needs human triage".
+- blockedCommits entries MUST include a specific human-readable reason (not just the SHA).
+- Pass allCandidateShas to generate_report — it cross-checks accountability automatically.
+
+## Hard constraints (never violate)
+- NEVER block a commit solely because classify_commit_risk returns "high" — always run the mandatory AI tools first.
+- NEVER apply a resolved file with conflict markers (<<<, ===, >>>) still present.
+- NEVER call continue_cherry_pick before all conflicted files are staged.
+- NEVER fabricate file content — only use content from get_conflict_context.
+- NEVER run commands that are not available as tools.
+- NEVER skip generate_report — it ends the run and produces the output.
+- If KEYPOOL_VAULT_URL is not set and apiKey is "auto", the run will fail before reaching this point.
+`;
+/**
+* Main async entry point.
+*
+* Orchestrates the full agent lifecycle from environment validation through
+* report output.  On any unhandled error the process exits with code 1.
+*
+* @throws On missing environment variables, invalid config, or agent failure.
+*/
+async function main() {
+	if (!process.env.KEYPOOL_VAULT_URL && !process.env.KEYPOOL_LIVE_SECRET) {
+		console.error("Error: KEYPOOL_VAULT_URL environment variable is required for the keypoollive provider.\nSet it to your encrypted vault URL (e.g. https://raw.githubusercontent.com/.../ai.json.XXXX.enc)\nalong with KEYPOOL_LIVE_SECRET as the decryption key.");
+		process.exit(1);
+	}
+	const config = loadConfig(process.env._CLI_CONFIG_PATH);
+	const customizations = await loadCustomizations(config.customizations ?? process.env.BACKPORT_CUSTOMIZATIONS);
+	applyGitAuth(config);
+	ensureWorkingDir(config);
+	const userInstructionService = createUserInstructionConfigService({ skills: { workspacePath: config.workingDir } });
+	await userInstructionService.start();
+	const gitTools = makeGitTools(config);
+	const riskTool = makeRiskTool(config, customizations);
+	const validationTool = makeValidationTool(config);
+	const githubTools = makeGitHubTools(config);
+	const promptLogPath = resolve(`run-${Date.now()}.prompts.jsonl`);
+	process.stderr.write(`[PromptLogger] Writing sub-agent logs to: ${promptLogPath}\n`);
+	const reportTool = makeReportTool(config, promptLogPath);
+	const aiTools = makeAiTools(config, promptLogPath);
+	const allTools = [
+		...createBuiltinTools({
+			cwd: config.workingDir,
+			enableReadFiles: true,
+			enableSearch: true,
+			enableBash: true,
+			enableWebFetch: true,
+			enableApplyPatch: true,
+			enableEditor: true,
+			enableSkills: true,
+			enableAskQuestion: true,
+			enableSubmitAndExit: true,
+			executors: {
+				skills: async (skill, args) => {
+					const configuredSkills = userInstructionService.listRecords("skill");
+					const match = configuredSkills.find((record) => record.id === skill || record.item.name === skill || record.filePath === skill);
+					if (!match || match.item.disabled) {
+						const availableSkills = configuredSkills.filter((record) => !record.item.disabled).map((record) => record.item.name);
+						return availableSkills.length > 0 ? `Skill "${skill}" is not available. Known skills: ${availableSkills.join(", ")}` : `No configured skills are available in this backport-agent runtime.`;
+					}
+					return [
+						`Skill: ${match.item.name}`,
+						match.item.description ? `Description: ${match.item.description}` : null,
+						args ? `Arguments: ${args}` : null,
+						"Instructions:",
+						match.item.instructions
+					].filter(Boolean).join("\n");
+				},
+				askQuestion: async (question, options) => {
+					return `Question recorded (headless mode): ${question} [${options.length > 0 ? options.join(" | ") : "(no options)"}]`;
+				},
+				submit: async (summary, verified) => `submit_and_exit acknowledged (verified=${verified ? "true" : "false"}): ${summary}`
+			}
+		}),
+		...gitTools,
+		riskTool,
+		validationTool,
+		...githubTools,
+		reportTool,
+		...aiTools
+	];
+	const agent = new Agent({
+		providerId: "keypoollive",
+		modelId: config.models.fast,
+		apiKey: "auto",
+		systemPrompt: SYSTEM_PROMPT,
+		tools: allTools,
+		maxIterations: config.sync.maxIterations,
+		completionPolicy: { requireCompletionTool: true }
+	});
+	const verbose = process.env.VERBOSE === "true";
+	let lastEventWasText = false;
+	let iterationOffset = 0;
+	let lastSeenIteration = 0;
+	let currentAttempt = 1;
+	agent.subscribe((event) => {
+		const rawIter = event.iteration;
+		if (typeof rawIter === "number" && rawIter > lastSeenIteration) lastSeenIteration = rawIter;
+		const displayIter = typeof rawIter === "number" ? iterationOffset + rawIter : "?";
+		if (event.type === "assistant-text-delta") {
+			lastEventWasText = true;
+			process.stdout.write(event.text);
+		} else if (event.type === "tool-started" && verbose) {
+			if (lastEventWasText) process.stderr.write("\n");
+			lastEventWasText = false;
+			const inp = event.toolCall.input;
+			const preview = inp && typeof inp === "object" && Object.keys(inp).length > 0 ? Object.keys(inp).slice(0, 2).map((k) => `${k}=${JSON.stringify(inp[k]).slice(0, 60)}`).join(", ") : "(no input)";
+			process.stderr.write(`[→ iter ${displayIter}] ${event.toolCall.toolName}(${preview})\n`);
+		} else if (event.type === "tool-finished" && verbose) {
+			lastEventWasText = false;
+			const result = event.toolCall;
+			process.stderr.write(`[← iter ${displayIter}] ${result.toolName ?? event.toolCall.toolName} done\n`);
+		} else if ((event.type === "iteration_start" || event.type === "turn-started") && verbose) {
+			const retrySuffix = currentAttempt > 1 ? ` - Retry ${currentAttempt - 1}` : "";
+			process.stderr.write(`\n--- iteration ${displayIter}${retrySuffix} ---\n`);
+		}
+	});
+	const dryRunNote = config.sync.dryRun ? " [DRY RUN — no changes will be pushed]" : "";
+	const task = `Synchronize the fork \`${config.fork.repo}@${config.fork.branch}\` with upstream \`${config.upstream.repo}@${config.upstream.branch}\`.${dryRunNote}\n\nWorking directory: ${config.workingDir}\nMax commits per run: ${config.sync.maxCommitsPerRun}\nBatch size: ${config.sync.batchSize}`;
+	console.error(`\n=== Backport Agent starting${dryRunNote} ===\n`);
+	const RETRIABLE_RE = /503|rate.?limit|too many requests|overloaded|service.?unavailable|high.?demand|try again later|temporarily unavailable|exceeded your current quota|quota.*exceeded|check your plan|billing details/i;
+	const BASE_DELAY_MS = 15e3;
+	const MAX_ATTEMPTS = 5;
+	async function runWithRetry() {
+		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+			currentAttempt = attempt;
+			let result;
+			try {
+				result = await agent.run(task);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				if (attempt < MAX_ATTEMPTS && RETRIABLE_RE.test(msg)) {
+					const delay = BASE_DELAY_MS * attempt;
+					process.stderr.write(`[Retry] Provider error on attempt ${attempt}/${MAX_ATTEMPTS}: ${msg.slice(0, 120)}\n[Retry] Waiting ${delay / 1e3}s before retrying...\n`);
+					iterationOffset += lastSeenIteration;
+					lastSeenIteration = 0;
+					await new Promise((r) => setTimeout(r, delay));
+					continue;
+				}
+				throw err;
+			}
+			if (result.status !== "completed") {
+				const err = result.error ?? /* @__PURE__ */ new Error(`Agent run ended with status "${result.status}" (model API error?)`);
+				const msg = err.message;
+				if (attempt < MAX_ATTEMPTS && RETRIABLE_RE.test(msg)) {
+					const delay = BASE_DELAY_MS * attempt;
+					process.stderr.write(`[Retry] Silent provider error (status=${result.status}) on attempt ${attempt}/${MAX_ATTEMPTS}: ${msg.slice(0, 120)}\n[Retry] Waiting ${delay / 1e3}s before retrying...\n`);
+					iterationOffset += lastSeenIteration;
+					lastSeenIteration = 0;
+					await new Promise((r) => setTimeout(r, delay));
+					continue;
+				}
+				throw err;
+			}
+			return result;
+		}
+		throw new Error("unreachable");
+	}
+	try {
+		const result = await runWithRetry();
+		console.error(`\n=== Run complete ===\n`);
+		if (result.outputText) console.log(result.outputText);
+		else throw new Error("Agent run completed but generate_report was never called (empty output). Check the prompt log for details.");
+	} finally {
+		userInstructionService.stop();
+	}
+}
+main().then(() => process.exit(0)).catch((err) => {
+	console.error("Fatal error:", err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});
+//#endregion
+
+//# sourceMappingURL=main.mjs.map