@ckeditor/ckeditor5-dev-agents 0.0.1 → 62.4.0

package/dist/cli.js

@@ -0,0 +1,2186 @@
+import { parseArgs, promisify } from "node:util";
+import upath from "upath";
+import { existsSync, globSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { cp, glob, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { simpleGit } from "simple-git";
+import { Octokit } from "@octokit/rest";
+import { tmpdir } from "node:os";
+import { ModelRuntime, SessionManager, SettingsManager, createAgentSession, createExtensionRuntime, defineTool, loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
+import { parse, stringify } from "yaml";
+import { execFile, spawn } from "node:child_process";
+import { hash } from "node:crypto";
+import { decodeHTMLStrict } from "entities";
+import { posix } from "node:path";
+//#region src/constants.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* The directory, relative to the target root, that holds the state of every task.
+*/
+const STATE_DIRECTORY = ".ai-tasks";
+/**
+* The prefix of report branches: `ai-tasks/<task>/<target>/<branch>`.
+*/
+const REPORT_BRANCH_PREFIX = "ai-tasks";
+/**
+* The tools an agent may use while judging. None of them can change a file.
+*/
+const READ_ONLY_TOOLS = [
+	"read",
+	"grep",
+	"find",
+	"ls"
+];
+/**
+* Every built-in tool of the Pi agent. The agent ignores unknown tool names, so the configuration is checked against it.
+*/
+const AGENT_TOOLS = [
+	"read",
+	"bash",
+	"powershell",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls"
+];
+//#endregion
+//#region src/config/importmodules.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Imports the default export of every file matching the pattern in the directory, sorted by path.
+*/
+async function importDefaultExports(directory, pattern) {
+	const files = globSync(pattern, { cwd: directory });
+	const modules = [];
+	for (const file of files.map((file) => upath.normalize(file)).sort()) {
+		const { default: value } = await import(pathToFileURL(upath.join(directory, file)).href);
+		modules.push({
+			file,
+			value
+		});
+	}
+	return modules;
+}
+//#endregion
+//#region src/config/loadtasks.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Loads every task from `<tasksPath>/<id>/index.{js,mjs,ts,mts}`. Adding a task means adding a directory.
+*/
+async function loadTasks(tasksPath) {
+	const tasks = /* @__PURE__ */ new Map();
+	for (const { file, value } of await importDefaultExports(tasksPath, "*/index.{js,mjs,ts,mts}")) {
+		const id = upath.dirname(file);
+		if (tasks.has(id)) throw new Error(`The "${id}" task has more than one \`index\` file.`);
+		validateTask(value, id);
+		tasks.set(id, {
+			task: value,
+			directory: upath.join(tasksPath, id)
+		});
+	}
+	return tasks;
+}
+/**
+* Checks the rules of a task that its type cannot express.
+*/
+function validateTask(task, id) {
+	const invalid = (message) => /* @__PURE__ */ new Error(`The "${id}" task is invalid: ${message}`);
+	if (task?.id !== id) throw invalid(`the module must export by default a task whose \`id\` matches the directory name ("${id}").`);
+	if (!Array.isArray(task.ruleIds)) throw invalid("`ruleIds` must be an array of rule IDs.");
+	if (task.ruleIds.some((ruleId) => typeof ruleId !== "string" || ruleId === "" || ruleId.includes("|"))) throw invalid("every rule ID must be a non-empty string without \"|\".");
+	if (new Set(task.ruleIds).size !== task.ruleIds.length) throw invalid("`ruleIds` must be unique.");
+	if (!task.scope && !task.include?.length) throw invalid("it needs `scope()`, or `include` to work on the matching files.");
+	if (task.writes?.length && !task.fix) throw invalid("a task with `writes` must define `fix()`.");
+	if (task.fix && !task.writes?.length) throw invalid("a task with `fix()` must define `writes`: the files the fix may change.");
+	if (task.verify && !task.fix) throw invalid("`verify()` checks a fix, so it requires `fix()`.");
+	const unmatchablePatterns = (task.writes ?? []).filter((pattern) => /^\.{0,2}\//.test(pattern));
+	if (unmatchablePatterns.length) throw invalid(`\`writes\` must be globs relative to the target root, without a leading "./", "../" or "/". Fix: ${unmatchablePatterns.join(", ")}.`);
+	for (const field of ["maxUnits", "concurrency"]) {
+		const value = task[field];
+		if (value !== void 0 && !(Number.isInteger(value) && value >= 1)) throw invalid(`\`${field}\` must be an integer of 1 or more.`);
+	}
+	const unknownTools = [...task.agent?.judgeTools ?? [], ...task.agent?.fixTools ?? []].filter((tool) => !AGENT_TOOLS.includes(tool));
+	if (unknownTools.length) throw invalid(`the agent has no such tools: ${[...new Set(unknownTools)].join(", ")}. The available tools are: ${AGENT_TOOLS.join(", ")}.`);
+	const writingTools = (task.agent?.judgeTools ?? []).filter((tool) => !READ_ONLY_TOOLS.includes(tool));
+	if (writingTools.length) throw invalid(`\`agent.judgeTools\` may contain only read-only tools (${READ_ONLY_TOOLS.join(", ")}). Remove: ${writingTools.join(", ")}.`);
+}
+//#endregion
+//#region src/utils/files.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Runs the read and returns `null` instead of throwing when the file does not exist.
+*/
+async function readIfExists(read) {
+	try {
+		return await read();
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+/**
+* Whether a normalized relative path points outside of the directory it is relative to.
+*/
+function isOutside(relativePath) {
+	return relativePath === ".." || relativePath.startsWith("../") || upath.isAbsolute(relativePath);
+}
+//#endregion
+//#region src/utils/strings.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Compares strings by code units, independently of the locale, so sorted state files are the same on every machine.
+*/
+function compare(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+/**
+* Joins the lines of a text into one line, for example to show a multi-line error in a list.
+*/
+function inline(text) {
+	return text.replace(/\s*\n\s*/g, " ").trim();
+}
+/**
+* Returns the message of a thrown value. Hooks of a task may throw anything, for example a string.
+*/
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function plural(count, word) {
+	return count === 1 ? word : `${word}s`;
+}
+//#endregion
+//#region src/config/loadtargets.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const DEFAULT_MAX_UNITS = 100;
+/**
+* Loads every target from `<targetsPath>/<name>.{js,mjs,ts,mts}`. Adding a repository means adding a file.
+*/
+async function loadTargets(targetsPath, tasks) {
+	const targets = /* @__PURE__ */ new Map();
+	for (const { file, value } of await importDefaultExports(targetsPath, "*.{js,mjs,ts,mts}")) {
+		const name = file.replace(/\.(js|mjs|ts|mts)$/, "");
+		if (targets.has(name)) throw new Error(`The "${name}" target is defined in more than one file.`);
+		targets.set(name, normalizeTarget(value, {
+			name,
+			tasks
+		}));
+	}
+	assertSeparateStates([...targets.values()]);
+	return targets;
+}
+function normalizeTarget(config, { name, tasks }) {
+	const invalid = (message) => /* @__PURE__ */ new Error(`The "${name}" target is invalid: ${message}`);
+	if (!config || !/^[\w.-]+\/[\w.-]+$/.test(config.slug)) throw invalid("the module must export by default a target with a `slug` like \"owner/repository\".");
+	const root = upath.normalize(config.root ?? ".");
+	if (isOutside(root)) throw invalid("`root` must be a path inside the repository.");
+	if (typeof config.tasks !== "object" || config.tasks === null || Array.isArray(config.tasks)) throw invalid("`tasks` must be an object that maps task names to their settings.");
+	const instances = /* @__PURE__ */ new Map();
+	for (const [instanceId, entry] of Object.entries(config.tasks)) {
+		if (instanceId === "" || /[|/\\]/.test(instanceId)) throw invalid(`the "${instanceId}" task name may not be empty or contain "|", "/" or "\\".`);
+		const loaded = tasks.get(entry.task ?? instanceId);
+		if (!loaded) throw invalid(`the "${entry.task ?? instanceId}" task does not exist.`);
+		const instance = resolveInstance(instanceId, entry, loaded);
+		try {
+			validateTask(instance.task, instanceId);
+		} catch (error) {
+			throw invalid(getErrorMessage(error));
+		}
+		instances.set(instanceId, instance);
+	}
+	return {
+		name,
+		slug: config.slug,
+		root,
+		tasks: instances
+	};
+}
+/**
+* Throws when two targets would keep the state of a task in the same directory of the same repository. Each run would
+* then drop the baseline and the findings of the other target.
+*/
+function assertSeparateStates(targets) {
+	const owners = /* @__PURE__ */ new Map();
+	for (const target of targets) for (const instanceId of target.tasks.keys()) {
+		const statePath = upath.join(target.root, STATE_DIRECTORY, instanceId);
+		const key = `${target.slug}:${statePath}`;
+		const owner = owners.get(key);
+		if (owner) throw new Error(`The "${owner}" and "${target.name}" targets keep the state of the "${instanceId}" task in the same directory of ${target.slug}: "${statePath}". Give them different roots, or name the task differently in one of them.`);
+		owners.set(key, target.name);
+	}
+}
+/**
+* Puts the task under the name of the instance and applies the overrides of the target. An instance that runs a task
+* under another name says so in its title, so its report pull request can be told apart from the one of the task.
+*/
+function resolveInstance(instanceId, entry, { task, directory }) {
+	return {
+		task: {
+			...task,
+			id: instanceId,
+			title: instanceId === task.id ? task.title : `${task.title} (${instanceId})`,
+			include: entry.include ?? task.include ?? [],
+			exclude: entry.exclude ?? task.exclude ?? [],
+			maxUnits: entry.maxUnits ?? task.maxUnits ?? DEFAULT_MAX_UNITS,
+			options: {
+				...task.defaultOptions,
+				...entry.options
+			}
+		},
+		directory,
+		enabled: entry.enabled !== false
+	};
+}
+//#endregion
+//#region src/config/loadconfig.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Loads the targets of the config directory, with their tasks. A directory without tasks or targets is almost always
+* the wrong one, so it throws.
+*/
+async function loadConfig(configPath) {
+	const tasks = await loadTasks(upath.join(configPath, "tasks"));
+	const targets = await loadTargets(upath.join(configPath, "targets"), tasks);
+	for (const [name, items] of [["tasks", tasks], ["targets", targets]]) if (!items.size) throw new Error(`No ${name} found in "${upath.join(configPath, name)}". Check that "--config" points to the directory with "tasks/" and "targets/".`);
+	return targets;
+}
+//#endregion
+//#region src/config/selecttargets.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Returns the targets to run in a checkout of the `originSlug` repository: the named ones, or every target of
+* the repository. A checkout belongs to one repository, so only the targets of that repository can run in it.
+*/
+function selectTargets(targets, { originSlug, names, taskIds }) {
+	for (const name of names) if (!targets.has(name)) throw new Error(`The "${name}" target does not exist. Available targets: ${[...targets.keys()].join(", ")}.`);
+	const origin = originSlug ?? "an unknown repository";
+	const selected = names.length ? names.map((name) => targets.get(name)) : [...targets.values()].filter((target) => target.slug === originSlug);
+	for (const target of selected) if (target.slug !== originSlug) throw new Error(`The "${target.name}" target is for "${target.slug}", but the checkout is a clone of ${origin}.`);
+	if (!selected.length) throw new Error(`No target is configured for the checkout, which is a clone of ${origin}.`);
+	for (const taskId of taskIds) if (!selected.some((target) => target.tasks.has(taskId))) throw new Error(`The "${taskId}" task is not configured in any of the selected targets.`);
+	return selected;
+}
+//#endregion
+//#region src/git/gitworkspace.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Opens the checkout that contains `cwd`. The checkout is prepared by whoever runs the framework: cloned, with
+* the dependencies installed, and with the base branch checked out. The `author` is needed only to commit.
+*/
+async function openWorkspace({ cwd, author }) {
+	const gitOptions = { config: [...author ? [`user.name=${author.name}`, `user.email=${author.email}`] : [], "commit.gpgsign=false"] };
+	let topLevel;
+	try {
+		topLevel = (await simpleGit({ baseDir: cwd }).revparse(["--show-toplevel"])).trim();
+	} catch (error) {
+		throw new Error(`"${cwd}" is not inside a git repository.`, { cause: error });
+	}
+	const path = upath.normalize(await realpath(topLevel));
+	const git = simpleGit({
+		...gitOptions,
+		baseDir: path
+	});
+	const branch = (await git.revparse(["--abbrev-ref", "HEAD"])).trim();
+	const baseCommit = (await git.revparse(["HEAD"])).trim();
+	let reportBranch;
+	let needsForcePush = false;
+	return {
+		path,
+		branch,
+		originSlug: await getOriginSlug(git),
+		async assertPublishable(paths) {
+			if (branch === "HEAD") throw new Error("Publishing needs a checked-out branch, but HEAD is detached. Check out the base branch first.");
+			if ((await git.raw(["rev-parse", "--is-shallow-repository"])).trim() === "true") throw new Error("Publishing needs the full history of the checkout, but it is shallow. Configure the checkout in CI to fetch the whole history.");
+			if ((await git.raw(["status", "--porcelain"])).trim()) throw new Error("Publishing needs a clean working tree, but it has uncommitted changes. Commit or remove them first.");
+			const ignored = paths.length ? (await git.raw([
+				"check-ignore",
+				"--",
+				...paths
+			])).trim() : "";
+			if (ignored) throw new Error(`Publishing commits the state of the tasks, but a \`.gitignore\` file ignores it: ${ignored.split("\n").join(", ")}. Stop ignoring these paths first.`);
+		},
+		async checkoutReportBranch({ name, continueExisting }) {
+			const existsRemotely = Boolean((await git.raw([
+				"ls-remote",
+				"--heads",
+				"origin",
+				name
+			])).trim());
+			reportBranch = name;
+			if (!continueExisting || !existsRemotely) {
+				needsForcePush = existsRemotely;
+				await git.checkout([
+					"-B",
+					name,
+					baseCommit
+				]);
+				return;
+			}
+			needsForcePush = false;
+			await git.fetch("origin", `+refs/heads/${name}:refs/remotes/origin/${name}`);
+			await git.checkout([
+				"-B",
+				name,
+				`origin/${name}`
+			]);
+			try {
+				await git.merge([
+					"--no-edit",
+					"-m",
+					`Merge ${branch} into ${name}.`,
+					baseCommit
+				]);
+			} catch (error) {
+				await git.merge(["--abort"]).catch(() => {});
+				throw new Error(`Merging "${branch}" into "${name}" failed. Resolve the conflict in the report pull request by hand. Details: ${error.message}`, { cause: error });
+			}
+		},
+		async commit(paths, message) {
+			await git.add([
+				"--all",
+				"--",
+				...paths
+			]);
+			if (!(await git.diff([
+				"--cached",
+				"--name-only",
+				"--",
+				...paths
+			])).trim()) return false;
+			await git.raw([
+				"commit",
+				"--quiet",
+				"-m",
+				message,
+				"--",
+				...paths
+			]);
+			return true;
+		},
+		async push() {
+			await git.push("origin", reportBranch, needsForcePush ? ["--force"] : []);
+			needsForcePush = false;
+		},
+		async returnToBase() {
+			await git.raw([
+				"reset",
+				"--hard",
+				"--quiet"
+			]);
+			await git.raw([
+				"clean",
+				"-fd",
+				"--quiet"
+			]);
+			await git.checkout(branch);
+		},
+		async refExists(ref) {
+			return succeeds(() => git.raw([
+				"rev-parse",
+				"--verify",
+				`${ref}^{commit}`
+			]));
+		},
+		async hasChanges(paths) {
+			return Boolean((await git.raw([
+				"status",
+				"--porcelain",
+				"--",
+				...paths
+			])).trim());
+		},
+		async restore(paths, ref) {
+			for (const file of paths) if (await succeeds(() => git.raw([
+				"cat-file",
+				"-e",
+				`${ref}:${file}`
+			]))) await git.raw([
+				"checkout",
+				ref,
+				"--",
+				file
+			]);
+			else {
+				await git.raw([
+					"rm",
+					"--cached",
+					"--quiet",
+					"--ignore-unmatch",
+					"--",
+					file
+				]);
+				await rm(upath.join(path, file), { force: true });
+			}
+		}
+	};
+}
+/**
+* Returns the GitHub slug of `origin`. Supports the SSH (`git@github.com:owner/repo.git`) and the HTTPS
+* (`https://github.com/owner/repo`) forms.
+*/
+async function getOriginSlug(git) {
+	return ((await git.getRemotes(true)).find((remote) => remote.name === "origin")?.refs.fetch ?? "").match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1];
+}
+async function succeeds(command) {
+	try {
+		await command();
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/github/githubclient.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const API_VERSION = "2026-03-10";
+const REQUEST_TIMEOUT = 3e4;
+/**
+* Creates a minimal client of the GitHub REST API with the calls that report pull requests need.
+*/
+function createGitHubClient(token) {
+	const octokit = new Octokit({ auth: token });
+	octokit.hook.before("request", (options) => {
+		options.headers["x-github-api-version"] = API_VERSION;
+		options.request = {
+			...options.request,
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT)
+		};
+	});
+	octokit.hook.error("request", (error) => {
+		const { status, request } = error;
+		if (!status || !request) throw error;
+		const message = `GitHub API request "${request.method} ${request.url}" failed with status ${status}: ${error.message}`;
+		throw new Error(message, { cause: error });
+	});
+	return {
+		async findOpenPullRequest({ slug, head }) {
+			const [owner, repo] = splitSlug(slug);
+			const { data } = await octokit.pulls.list({
+				owner,
+				repo,
+				state: "open",
+				head: `${owner}:${head}`
+			});
+			return data[0] ?? null;
+		},
+		async createPullRequest({ slug, head, base, title, body }) {
+			const [owner, repo] = splitSlug(slug);
+			return (await octokit.pulls.create({
+				owner,
+				repo,
+				head,
+				base,
+				title,
+				body
+			})).data;
+		},
+		async updatePullRequest({ slug, number, body }) {
+			const [owner, repo] = splitSlug(slug);
+			return (await octokit.pulls.update({
+				owner,
+				repo,
+				pull_number: number,
+				body
+			})).data;
+		},
+		async createComment({ slug, number, body }) {
+			const [owner, repo] = splitSlug(slug);
+			return (await octokit.issues.createComment({
+				owner,
+				repo,
+				issue_number: number,
+				body
+			})).data;
+		}
+	};
+}
+function splitSlug(slug) {
+	const [owner, repo] = slug.split("/");
+	return [owner, repo];
+}
+//#endregion
+//#region src/utils/githuburls.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+function getBlobUrl(target, branch, path) {
+	return `https://github.com/${target.slug}/blob/${encodePath(branch)}/${encodePath(upath.join(target.root, path))}`;
+}
+function getHistoryUrl(target, branch, path) {
+	return `https://github.com/${target.slug}/commits/${encodePath(branch)}/${encodePath(upath.join(target.root, path))}`;
+}
+function encodePath(path) {
+	return path.split("/").map(encodeURIComponent).join("/");
+}
+//#endregion
+//#region src/report/renderpullrequest.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Renders the description of the report pull request. It is rewritten on every run that pushes,
+* so it always shows the current number of findings.
+*/
+function renderPullRequestBody({ task, target, branch, reportBranch, open, fixed }) {
+	const reportUrl = getBlobUrl(target, reportBranch, `${STATE_DIRECTORY}/${task.id}/report.md`);
+	return [
+		`This pull request is maintained by the "${task.title}" task (\`${task.id}\`) of \`@ckeditor/ckeditor5-dev-agents\`. It covers \`${target.name}\` at \`${branch}\`. Every run pushes new commits here and comments with what it found.`,
+		"",
+		`**${open}** open ${plural(open, "finding")}, **${fixed}** fixed in this pull request. See [report.md](${reportUrl}) for the findings and how to review them.`,
+		"",
+		`Merge this pull request to record the state on \`${branch}\`. Until then, the next runs continue this branch, so no unit is judged twice.`,
+		""
+	].join("\n");
+}
+/**
+* Renders the comment posted after every run that pushed something.
+*/
+function renderRunComment({ today, summary, buildUrl }) {
+	return [
+		buildUrl ? `### [Run](${buildUrl}) on ${today}` : `### Run on ${today}`,
+		"",
+		...renderSummary(summary)
+	].join("\n");
+}
+function renderSummary(summary) {
+	const lines = [
+		"| Units | Changed | Judged | Left | New findings | Already open | Rejected | Fixed | Discarded | Files changed | Errors | Open | Cost |",
+		"| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+		"| " + [
+			summary.units,
+			summary.changed,
+			summary.judged,
+			summary.deferred,
+			summary.newFindings,
+			summary.alreadyOpen,
+			summary.rejected,
+			summary.fixed,
+			summary.discarded,
+			summary.changedFiles,
+			summary.errors,
+			summary.open,
+			`$${summary.cost.toFixed(2)}`
+		].join(" | ") + " |",
+		""
+	];
+	const problems = summary.problems.map(({ unit, message }) => `* ${unit ? `\`${unit}\`: ` : ""}${inline(message)}`);
+	if (problems.length) lines.push("#### Problems", "", ...problems, "");
+	return lines;
+}
+//#endregion
+//#region src/agent/createagent.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const RESULT_TOOL_NAME = "submit_result";
+const AGENT_DIRECTORY = upath.join(tmpdir(), "ckeditor5-dev-agents");
+const DEFAULT_TIMEOUT = 1800;
+const MAX_RETRIES = 3;
+const MAX_ARGUMENTS_LENGTH = 120;
+const modelRuntimes = /* @__PURE__ */ new Map();
+/**
+* Creates the `agent` of one phase of a task. Every `run()` starts a new in-memory Pi session that is configured only
+* by the task: its instructions, skills, tools and model. The API key comes from the task config (`agent.apiKey`),
+* never from the environment of the process.
+*/
+function createAgent(options) {
+	const { taskId, config, taskDirectory, cwd, tools, usage, log, warn } = options;
+	let resources;
+	const loadResources = async (agentConfig) => createResourceLoader({
+		systemPrompt: await getInstructions(agentConfig, taskDirectory),
+		skills: getSkills(agentConfig, taskDirectory, (message) => {
+			log(`[agent] ${message}`);
+			warn(message);
+		})
+	});
+	return { async run({ prompt, outputSchema }) {
+		if (!config) throw new Error(`The "${taskId}" task calls \`agent.run()\`, but it does not configure \`agent\`.`);
+		if (!config.apiKey) throw new Error(`The "${taskId}" task calls \`agent.run()\`, but \`agent.apiKey\` is empty. Provide the API key of the "${config.model.provider}" provider in the task config.`);
+		const modelRuntime = await getModelRuntime(config.model.provider, config.apiKey);
+		const model = modelRuntime.getModel(config.model.provider, config.model.id);
+		if (!model) throw new Error(`The "${config.model.provider}/${config.model.id}" model is not available.`);
+		let result;
+		const resultTool = outputSchema && defineTool({
+			name: RESULT_TOOL_NAME,
+			label: "Submit result",
+			description: "Submits the result of the task. Call it exactly once, when you are done.",
+			parameters: outputSchema,
+			async execute(_toolCallId, params) {
+				result = params;
+				return {
+					content: [{
+						type: "text",
+						text: "The result was received. You are done."
+					}],
+					details: void 0
+				};
+			}
+		});
+		const { session } = await createAgentSession({
+			cwd,
+			agentDir: AGENT_DIRECTORY,
+			model,
+			modelRuntime,
+			thinkingLevel: config.thinkingLevel,
+			tools: resultTool ? [...tools, RESULT_TOOL_NAME] : [...tools],
+			customTools: resultTool ? [resultTool] : [],
+			sessionManager: SessionManager.inMemory(cwd),
+			settingsManager: SettingsManager.inMemory({
+				enableInstallTelemetry: false,
+				retry: {
+					enabled: true,
+					maxRetries: MAX_RETRIES
+				}
+			}),
+			resourceLoader: await (resources ??= loadResources(config))
+		});
+		const unsubscribe = session.subscribe((event) => {
+			if (event.type === "tool_execution_start" && event.toolName !== RESULT_TOOL_NAME) log(`[agent] ${event.toolName} ${summarizeArguments(event.args)}`);
+		});
+		const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+		let hasTimedOut = false;
+		const timer = setTimeout(() => {
+			hasTimedOut = true;
+			session.abort().catch(() => {});
+		}, timeout * 1e3);
+		const sendPrompt = async (text) => {
+			try {
+				await session.prompt(text);
+			} catch (error) {
+				if (!hasTimedOut) throw error;
+			}
+			if (hasTimedOut) throw new Error(`The agent did not finish within ${timeout} seconds.`);
+		};
+		try {
+			await sendPrompt(resultTool ? `${prompt}\n\nWhen you are done, call the \`${RESULT_TOOL_NAME}\` tool exactly once with the result. Do not write the result as text.` : prompt);
+			if (resultTool && result === void 0) await sendPrompt(`You have not called the \`${RESULT_TOOL_NAME}\` tool. Call it now with the result.`);
+			const lastMessage = session.messages.findLast((message) => message.role === "assistant");
+			if (lastMessage?.stopReason === "error") throw new Error(`The agent failed: ${lastMessage.errorMessage ?? "unknown error"}`);
+			if (resultTool && result === void 0) throw new Error(`The agent did not return a result through the \`${RESULT_TOOL_NAME}\` tool.`);
+			return {
+				output: result,
+				text: session.getLastAssistantText() ?? ""
+			};
+		} finally {
+			const stats = session.getSessionStats();
+			usage.cost += stats.cost;
+			usage.tokens += stats.tokens.total;
+			clearTimeout(timer);
+			unsubscribe();
+			session.dispose();
+		}
+	} };
+}
+function getModelRuntime(provider, apiKey) {
+	const key = `${provider}\0${apiKey}`;
+	if (!modelRuntimes.has(key)) modelRuntimes.set(key, createModelRuntime(provider, apiKey));
+	return modelRuntimes.get(key);
+}
+async function createModelRuntime(provider, apiKey) {
+	const modelRuntime = await ModelRuntime.create({
+		credentials: new InMemoryCredentialStore(),
+		modelsPath: null,
+		allowModelNetwork: false
+	});
+	await modelRuntime.setRuntimeApiKey(provider, apiKey);
+	return modelRuntime;
+}
+async function getInstructions(config, taskDirectory) {
+	if (config.instructions) return config.instructions;
+	if (config.instructionsPath) return readFile(upath.resolve(taskDirectory, config.instructionsPath), "utf8");
+}
+function getSkills(config, taskDirectory, warn) {
+	return (config.skills ?? []).flatMap((directory) => {
+		const { skills, diagnostics } = loadSkillsFromDir({
+			dir: upath.resolve(taskDirectory, directory),
+			source: "task"
+		});
+		for (const diagnostic of diagnostics) warn(`A skill could not be loaded: ${diagnostic.message}`);
+		return skills;
+	});
+}
+/**
+* Gives the agent only the system prompt and the skills of the task, so a run behaves the same on every machine,
+* whatever user and project resources (`AGENTS.md`, `~/.pi`, extensions, prompt templates) it has.
+*/
+function createResourceLoader({ systemPrompt, skills }) {
+	return {
+		getExtensions: () => ({
+			extensions: [],
+			errors: [],
+			runtime: createExtensionRuntime()
+		}),
+		getSkills: () => ({
+			skills,
+			diagnostics: []
+		}),
+		getPrompts: () => ({
+			prompts: [],
+			diagnostics: []
+		}),
+		getThemes: () => ({
+			themes: [],
+			diagnostics: []
+		}),
+		getAgentsFiles: () => ({ agentsFiles: [] }),
+		getSystemPrompt: () => systemPrompt,
+		getSystemPromptSource: () => void 0,
+		getAppendSystemPrompt: () => [],
+		getAppendSystemPromptSources: () => [],
+		extendResources: () => {},
+		reload: async () => {}
+	};
+}
+function summarizeArguments(args) {
+	const text = String(JSON.stringify(args));
+	return text.length > MAX_ARGUMENTS_LENGTH ? `${text.slice(0, 117)}...` : text;
+}
+//#endregion
+//#region src/state/decisions.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const REQUIRED_FIELDS = [
+	"unit",
+	"rule",
+	"fragment",
+	"reason"
+];
+const OPTIONAL_FIELDS = ["discriminator", "finding"];
+/**
+* Loads every decision file (`*.yml`) from the directory. A file that cannot be used does not stop
+* the run. It is skipped and reported as a warning, so the finding it was meant to reject is reported again.
+*/
+async function loadDecisions(decisionsPath) {
+	const files = globSync("*.yml", { cwd: decisionsPath });
+	const decisions = [];
+	const warnings = [];
+	for (const file of files.sort()) try {
+		const content = await readFile(upath.join(decisionsPath, file), "utf8");
+		decisions.push({
+			file,
+			...parseDecision(content)
+		});
+	} catch (error) {
+		warnings.push(`The "decisions/${file}" decision file was skipped: ${error.message.split("\n")[0]}`);
+	}
+	return {
+		decisions,
+		warnings
+	};
+}
+/**
+* Returns the decisions about the same claim as the finding: the same unit, rule and discriminator.
+*/
+function findDecisions(decisions, finding) {
+	return decisions.filter((decision) => {
+		return decision.unit === finding.unit && decision.rule === finding.ruleId && decision.discriminator === finding.discriminator;
+	});
+}
+/**
+* Returns the decisions about the unit, each marked as expired or not. The harness hands them to `judge()`,
+* so a model reads the human reasoning, including the reasoning about content that has changed since.
+*/
+function getPriorDecisions(decisions, unitKey, fragment) {
+	return decisions.filter((decision) => decision.unit === unitKey).map(({ unit, rule, discriminator, fragment: decisionFragment, finding, reason }) => ({
+		unit,
+		rule,
+		discriminator,
+		fragment: decisionFragment,
+		finding,
+		reason,
+		expired: decisionFragment !== fragment
+	}));
+}
+function parseDecision(content) {
+	const decision = parse(content, { schema: "failsafe" });
+	if (!decision || typeof decision !== "object" || Array.isArray(decision)) throw new Error("It must contain a single YAML mapping.");
+	const fields = decision;
+	for (const field of REQUIRED_FIELDS) if (typeof fields[field] !== "string" || fields[field].trim() === "") throw new Error(`The "${field}" field must be a non-empty string.`);
+	for (const field of OPTIONAL_FIELDS) if (fields[field] !== void 0 && typeof fields[field] !== "string") throw new Error(`The "${field}" field must be a string.`);
+	const text = (field) => (fields[field] ?? "").trim();
+	return {
+		unit: text("unit"),
+		rule: text("rule"),
+		discriminator: text("discriminator"),
+		fragment: text("fragment"),
+		finding: text("finding"),
+		reason: text("reason")
+	};
+}
+/**
+* Renders the decision file that rejects the finding.
+*/
+function renderDecision(finding, reason) {
+	return stringify({
+		unit: finding.unit,
+		rule: finding.ruleId,
+		discriminator: finding.discriminator || void 0,
+		fragment: finding.fragment,
+		finding: finding.detail,
+		reason
+	}, { lineWidth: 0 });
+}
+/**
+* Returns a readable file name, without the extension, for the decision about the finding, for example
+* `b2-docs-features-tables`.
+*/
+function getDecisionFileName({ ruleId, unit, discriminator }) {
+	return [
+		ruleId,
+		unit.replace(/\.md$/, ""),
+		discriminator
+	].filter(Boolean).join("-").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+//#endregion
+//#region src/state/statestore.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Reads the state of one task: `baseline.json`, `open.json` and `decisions/*.yml`. Missing files mean
+* an empty state, which is what the first run of a task sees.
+*/
+async function readTaskState(taskStatePath) {
+	const baseline = await readJson(taskStatePath, "baseline.json", {});
+	const open = await readJson(taskStatePath, "open.json", []);
+	const { decisions, warnings } = await loadDecisions(upath.join(taskStatePath, "decisions"));
+	if (!baseline || typeof baseline !== "object" || Array.isArray(baseline)) throw new Error("The \"baseline.json\" file must contain an object.");
+	if (!Array.isArray(open)) throw new Error("The \"open.json\" file must contain an array.");
+	return {
+		baseline,
+		open,
+		decisions,
+		warnings
+	};
+}
+/**
+* Writes the state of one task. Keys and findings are sorted, so the diff shows only what really changed.
+*/
+async function writeTaskState(taskStatePath, { baseline, open, report }) {
+	const sortedBaseline = Object.fromEntries(Object.keys(baseline).sort().map((key) => [key, baseline[key]]));
+	const sortedOpen = open.toSorted((a, b) => compare(a.fingerprint, b.fingerprint));
+	await mkdir(taskStatePath, { recursive: true });
+	await writeFile(upath.join(taskStatePath, "baseline.json"), toJson(sortedBaseline));
+	await writeFile(upath.join(taskStatePath, "open.json"), toJson(sortedOpen));
+	await writeFile(upath.join(taskStatePath, "report.md"), report);
+}
+async function readJson(directory, file, defaultValue) {
+	const content = await readIfExists(() => readFile(upath.join(directory, file), "utf8"));
+	if (content === null) return defaultValue;
+	try {
+		return JSON.parse(content);
+	} catch (error) {
+		throw new Error(`The "${file}" file is not valid JSON: ${error.message}`, { cause: error });
+	}
+}
+function toJson(value) {
+	return JSON.stringify(value, null, "	") + "\n";
+}
+//#endregion
+//#region src/report/renderreport.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Renders `report.md` of one task from its findings. The file is regenerated on every run,
+* so `open.json` stays the only source of truth.
+*/
+function renderReport({ task, target, branch, open }) {
+	const taskStatePath = `${STATE_DIRECTORY}/${task.id}`;
+	const sorted = open.toSorted((a, b) => compare(a.fingerprint, b.fingerprint));
+	const fixed = sorted.filter((finding) => finding.fix);
+	const unresolved = sorted.filter((finding) => !finding.fix);
+	const lines = [
+		"<!-- Generated from open.json by @ckeditor/ckeditor5-dev-agents. Edit open.json instead. -->",
+		"",
+		`# ${task.title}`,
+		""
+	];
+	if (!open.length) {
+		lines.push("There are no findings.", "");
+		return lines.join("\n");
+	}
+	lines.push(`**${unresolved.length}** open ${plural(unresolved.length, "finding")}, **${fixed.length}** fixed in the report pull request.`, "", "Resolve each finding in one of these ways, using the ID in its heading:", "", "* Keep it: keep the proposed fix, or fix it yourself in the report pull request.", `* Reject it: check out the report branch and run \`ckeditor5-dev-agents reject <id> --reason "…"\`. It records why the finding is wrong in \`${upath.join(target.root, taskStatePath)}/decisions/\`, removes it from \`open.json\`, and reverts its fix. The decision holds until the judged content changes. Commit and push the result.`, "* Dismiss it: `ckeditor5-dev-agents dismiss <id>` does the same without a decision, so it may be reported again once the judged content changes.", "", "Reverting a fix by hand, without rejecting the finding, means the task finds the problem and fixes it again on a later run.", "");
+	const renderFinding = (finding) => {
+		const findingLines = [
+			`#### ${finding.discriminator ? `${finding.ruleId}: ${finding.discriminator}` : finding.ruleId} \`[${finding.id}]\``,
+			"",
+			`<!-- fp: ${finding.fingerprint} -->`,
+			"",
+			finding.detail,
+			""
+		];
+		if (finding.fix) {
+			const files = finding.fix.files.map((file) => `\`${file}\``).join(", ");
+			findingLines.push(`**Proposed fix:** ${files}. Review it in the diff.`, "");
+		}
+		if (finding.previousDecision) {
+			const { file, fragment, finding: claim, reason } = finding.previousDecision;
+			const historyUrl = getHistoryUrl(target, branch, `${taskStatePath}/decisions/${file}`);
+			findingLines.push("> [!NOTE]", `> This finding was rejected before, in \`${file}\` ([history](${historyUrl})). It is reported again because the judged content changed: \`${fragment}\` → \`${finding.fragment}\`.`, ...claim ? [">", `> **Previous claim:** ${inline(claim)}`] : [], ">", `> **Answer:** ${inline(reason)}`, "");
+		}
+		return findingLines;
+	};
+	const renderFindings = (heading, findings) => {
+		if (!findings.length) return;
+		lines.push(`## ${heading}`, "");
+		const byUnit = /* @__PURE__ */ new Map();
+		for (const finding of findings) byUnit.set(finding.unit, [...byUnit.get(finding.unit) ?? [], finding]);
+		for (const [unit, unitFindings] of byUnit) {
+			const { path } = unitFindings[0];
+			lines.push(`### ${path ? `[\`${unit}\`](${getBlobUrl(target, branch, path)})` : `\`${unit}\``}`, "");
+			for (const finding of unitFindings) lines.push(...renderFinding(finding));
+		}
+	};
+	renderFindings("Fixed in the report pull request", fixed);
+	renderFindings("Open", unresolved);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/utils/text.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const HASH_LENGTH = 12;
+const CHARACTERS = {
+	"‘": "'",
+	"’": "'",
+	"‚": "'",
+	"‛": "'",
+	"′": "'",
+	"“": "\"",
+	"”": "\"",
+	"„": "\"",
+	"‟": "\"",
+	"″": "\"",
+	"‐": "-",
+	"‑": "-",
+	"‒": "-",
+	"–": "-",
+	"—": "-",
+	"―": "-",
+	"−": "-",
+	"…": "..."
+};
+const CHARACTERS_PATTERN = new RegExp(`[${Object.keys(CHARACTERS).join("")}]`, "g");
+/**
+* Normalises prose by folding HTML entities, typographic quotes and dashes, and whitespace.
+* Use only when these differences are irrelevant to the audit; whitespace and entities can be significant in code.
+*/
+function normalise(text) {
+	return decodeHTMLStrict(text).replace(CHARACTERS_PATTERN, (character) => CHARACTERS[character]).replace(/\s+/g, " ").trim();
+}
+/**
+* Returns a short, stable hash of a text. It is what the baseline and the decision files store.
+*/
+function hash$1(text) {
+	return hash("sha256", text, "hex").slice(0, HASH_LENGTH);
+}
+//#endregion
+//#region src/runner/createcontext.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Creates the `ctx` of the judging phase. It can read the target, but not change it.
+*/
+function createTaskContext({ root, phase, options, agent, log }) {
+	return {
+		phase,
+		options,
+		agent,
+		log,
+		normalise,
+		hash: hash$1,
+		repo: {
+			root,
+			async list(patterns, { ignore = [] } = {}) {
+				const entries = glob(patterns, {
+					cwd: root,
+					withFileTypes: true,
+					exclude: ["**/node_modules/**", ...ignore]
+				});
+				const files = [];
+				for await (const entry of entries) if (!entry.isDirectory()) files.push(upath.relative(root, upath.join(entry.parentPath, entry.name)));
+				return files.sort();
+			},
+			async read(path) {
+				return readFile(resolveInside(root, path), "utf8");
+			}
+		}
+	};
+}
+/**
+* Creates the `ctx` of `fix()` and `verify()`. It can also change files and run commands in the target root.
+*/
+function createWritableTaskContext(options) {
+	const context = createTaskContext(options);
+	return {
+		...context,
+		repo: {
+			...context.repo,
+			async write(path, content) {
+				const absolutePath = resolveInside(options.root, path);
+				await mkdir(upath.dirname(absolutePath), { recursive: true });
+				await writeFile(absolutePath, content);
+			},
+			async remove(path) {
+				await rm(resolveInside(options.root, path), { force: true });
+			}
+		},
+		exec(command, args = [], { timeout } = {}) {
+			return execute({
+				command,
+				args,
+				cwd: options.root,
+				timeout
+			});
+		}
+	};
+}
+function resolveInside(root, path) {
+	const absolutePath = upath.resolve(root, path);
+	if (isOutside(upath.relative(root, absolutePath))) throw new Error(`The "${path}" path is outside of the target root.`);
+	return absolutePath;
+}
+function execute({ command, args, cwd, timeout }) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd,
+			timeout,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let output = "";
+		const append = (data) => {
+			output = (output + data).slice(-4e3);
+		};
+		child.stdout.setEncoding("utf8").on("data", append);
+		child.stderr.setEncoding("utf8").on("data", append);
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === 0) {
+				resolve({ output });
+				return;
+			}
+			let reason = `exited with code ${code}`;
+			if (timeout && child.killed) reason = `did not finish within ${timeout} ms`;
+			else if (signal) reason = `was stopped by ${signal}`;
+			reject(/* @__PURE__ */ new Error(`"${[command, ...args].join(" ")}" ${reason}:\n${output}`));
+		});
+	});
+}
+//#endregion
+//#region src/runner/changetracker.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const MAX_GIT_OUTPUT_SIZE = 268435456;
+const execFileAsync = promisify(execFile);
+/**
+* Tracks what `fix()` changes in a git working tree. It sees every file git sees: tracked files and untracked files
+* that are not ignored. The working tree may already have changes (the kept fixes of earlier units, or local changes
+* in a local run). Only what changes after a snapshot counts.
+*
+* A snapshot stores the working tree as a tree object, written through a copy of the index, so the real index
+* is never touched.
+*/
+async function createChangeTracker(root) {
+	const top = upath.normalize((await git(root, ["rev-parse", "--show-toplevel"])).trim());
+	const indexPath = (await git(top, [
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-path",
+		"index"
+	])).trim();
+	const snapshotIndexPath = `${indexPath}.ckeditor5-dev-agents`;
+	const snapshotIndex = { GIT_INDEX_FILE: snapshotIndexPath };
+	await rm(snapshotIndexPath, { force: true });
+	const rawContent = {
+		args: [
+			"-c",
+			"core.autocrlf=false",
+			"-c",
+			`core.attributesFile=${snapshotIndexPath}.attributes`
+		],
+		env: { GIT_ATTR_SOURCE: (await git(top, ["write-tree"], snapshotIndex)).trim() }
+	};
+	const getHead = async () => (await git(top, ["rev-parse", "HEAD"])).trim();
+	const writeTree = async () => {
+		try {
+			await readIfExists(() => cp(indexPath, snapshotIndexPath, { preserveTimestamps: true }));
+			await git(top, [
+				...rawContent.args,
+				"add",
+				"--all"
+			], {
+				...snapshotIndex,
+				...rawContent.env
+			});
+			return (await git(top, ["write-tree"], snapshotIndex)).trim();
+		} finally {
+			await rm(snapshotIndexPath, { force: true });
+		}
+	};
+	return {
+		async capture() {
+			return {
+				head: await getHead(),
+				tree: await writeTree(),
+				index: await readIfExists(() => readFile(indexPath))
+			};
+		},
+		async collect(snapshot) {
+			const tree = await writeTree();
+			return {
+				changed: (await git(top, [
+					"diff-tree",
+					"-r",
+					"--name-only",
+					"-z",
+					"--no-renames",
+					snapshot.tree,
+					tree
+				])).split("\0").filter(Boolean).map((path) => upath.join(top, path)).sort(),
+				headMoved: await getHead() !== snapshot.head
+			};
+		},
+		async restore(snapshot, paths) {
+			if (await getHead() !== snapshot.head) await git(top, [
+				"reset",
+				"--mixed",
+				"--quiet",
+				snapshot.head
+			]);
+			if (paths.length) {
+				const inSnapshot = (await git(top, [
+					"--literal-pathspecs",
+					"ls-tree",
+					"-r",
+					"--name-only",
+					"-z",
+					snapshot.tree,
+					"--",
+					...paths.map((path) => upath.relative(top, path))
+				])).split("\0").filter(Boolean);
+				for (const path of paths) await rm(path, {
+					force: true,
+					recursive: true
+				});
+				if (inSnapshot.length) await git(top, [
+					...rawContent.args,
+					"--literal-pathspecs",
+					"restore",
+					"--source",
+					snapshot.tree,
+					"--worktree",
+					"--",
+					...inSnapshot
+				], rawContent.env);
+			}
+			if (snapshot.index) await writeFile(indexPath, snapshot.index);
+			else await rm(indexPath, { force: true });
+		}
+	};
+}
+/**
+* Runs git directly, because simple-git rejects a custom environment together with the `GIT_CONFIG_*` variables that
+* may be set for the process.
+*/
+async function git(cwd, args, env = {}) {
+	const { stdout } = await execFileAsync("git", args, {
+		cwd,
+		env: {
+			...process.env,
+			...env
+		},
+		encoding: "utf8",
+		maxBuffer: MAX_GIT_OUTPUT_SIZE
+	});
+	return stdout;
+}
+//#endregion
+//#region src/runner/fixunit.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Fixes one unit transactionally. Every affected unit is checked, including units whose hash depends on
+* files outside their own path. A later fix must preserve the accepted judgments of earlier fixes.
+*/
+async function fixUnit(runner, record, actionable) {
+	const { task, shared, tracker, fixContext, verifyContext } = runner;
+	const { unit } = record;
+	const snapshot = await tracker.capture();
+	try {
+		await step("`fix()`", () => task.fix({
+			...fixContext,
+			shared,
+			unit,
+			findings: actionable
+		}));
+		const initial = await step("Inspecting the fix", () => tracker.collect(snapshot));
+		assertAllowedChanges(runner, initial);
+		if (!initial.changed.length) return { status: "none" };
+		await step("`verify()`", () => task.verify?.({
+			...verifyContext,
+			shared,
+			unit
+		}));
+		const final = await step("Inspecting the fix", () => tracker.collect(snapshot));
+		assertAllowedChanges(runner, final);
+		const affected = await step("Judging the fixed unit", async () => {
+			const fragments = /* @__PURE__ */ new Map();
+			for (const candidate of runner.units.values()) {
+				if (candidate !== record && !candidate.current) continue;
+				const fragment = await step(`\`contentHash()\` of "${candidate.unit.key}"`, () => runner.contentHash(candidate.unit));
+				if (candidate === record || fragment !== candidate.current?.fragment) fragments.set(candidate, fragment);
+			}
+			const unjudged = [...fragments.keys()].filter((candidate) => !candidate.current?.findings);
+			if (unjudged.length) {
+				const proposed = await tracker.capture();
+				await tracker.restore(snapshot, final.changed);
+				try {
+					for (const candidate of unjudged) {
+						const fragment = await runner.contentHash(candidate.unit);
+						candidate.current = {
+							fragment,
+							findings: await runner.judge(candidate.unit, fragment)
+						};
+					}
+				} finally {
+					await tracker.restore(proposed, final.changed);
+				}
+			}
+			return fragments;
+		});
+		const observations = /* @__PURE__ */ new Map();
+		const resolved = /* @__PURE__ */ new Map();
+		for (const [candidate, fragment] of affected) {
+			const findings = await step("Judging the fixed unit", () => runner.judge(candidate.unit, fragment));
+			const before = candidate.current.findings;
+			const known = new Set(before.filter((finding) => !runner.isRejected(finding)).map((finding) => finding.fingerprint));
+			const rejected = new Set(before.filter((finding) => runner.isRejected(finding)).map((finding) => finding.fingerprint));
+			const introduced = findings.filter((finding) => {
+				return !known.has(finding.fingerprint) && !rejected.has(finding.fingerprint) && !runner.isRejected(finding);
+			});
+			if (introduced.length) throw new Error(`The fix introduced new findings: ${introduced.map((finding) => finding.ruleId).join(", ")}.`);
+			const remaining = new Set(findings.map((finding) => finding.fingerprint));
+			resolved.set(candidate, new Set([...known].filter((fingerprint) => !remaining.has(fingerprint))));
+			observations.set(candidate, {
+				fragment,
+				findings
+			});
+		}
+		if (!actionable.some((finding) => resolved.get(record).has(finding.fingerprint))) throw new Error("The fix did not resolve any finding.");
+		for (const [candidate, observation] of observations) candidate.current = observation;
+		return {
+			status: "kept",
+			files: final.changed,
+			resolved
+		};
+	} catch (error) {
+		await tracker.restore(snapshot, (await tracker.collect(snapshot)).changed);
+		return {
+			status: "discarded",
+			message: getErrorMessage(error),
+			findings: actionable.length
+		};
+	}
+}
+/**
+* Prepends the step to the message when it fails. The checks of the harness throw outside of a step, because their
+* messages are complete on their own.
+*/
+async function step(label, callback) {
+	try {
+		return await callback();
+	} catch (error) {
+		throw new Error(`${label} failed: ${getErrorMessage(error)}`, { cause: error });
+	}
+}
+function assertAllowedChanges(runner, { changed, headMoved }) {
+	if (headMoved) throw new Error("The fix created commits. Only the harness may commit.");
+	const outside = changed.map((file) => upath.relative(runner.root, file)).filter((file) => isOutside(file) || !runner.task.writes.some((pattern) => posix.matchesGlob(file, pattern)));
+	if (outside.length) throw new Error(`The fix changed files outside \`writes\`: ${outside.map((file) => `\`${file}\``).join(", ")}.`);
+}
+//#endregion
+//#region src/runner/validatefindings.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const KNOWN_FIELDS = [
+	"fingerprint",
+	"id",
+	"task",
+	"unit",
+	"ruleId",
+	"discriminator",
+	"detail",
+	"fragment",
+	"path",
+	"reportedAt",
+	"previousDecision",
+	"fix"
+];
+/**
+* Returns the identity of a finding. Two findings with the same fingerprint are the same claim,
+* so the harness reports it only once.
+*/
+function getFingerprint({ task, unit, ruleId, discriminator }) {
+	return [
+		task,
+		unit,
+		ruleId,
+		discriminator
+	].map((part) => part.replace(/[\\|]/g, "\\$&")).join("|");
+}
+/**
+* Returns the full digest of a fingerprint. Its first 12 characters are the `id` of the finding. Longer prefixes
+* resolve collisions between IDs.
+*/
+function getFindingId(fingerprint) {
+	return hash("sha256", fingerprint, "hex");
+}
+/**
+* Checks what `judge()` returned and turns it into findings the harness can store.
+* It throws when anything is malformed, because a judge that half-worked must not advance the baseline.
+*/
+function validateFindings(findings, { task, unit, fragment }) {
+	if (!Array.isArray(findings)) throw new Error("`judge()` must return an array of findings.");
+	return findings.map((finding, index) => {
+		if (!finding || typeof finding !== "object" || Array.isArray(finding)) throw new Error(`Finding #${index} must be an object.`);
+		const fields = finding;
+		if (typeof fields.ruleId !== "string" || !task.ruleIds.includes(fields.ruleId)) throw new Error(`Finding #${index} refers to the unknown "${String(fields.ruleId)}" rule.`);
+		if (typeof fields.detail !== "string" || fields.detail.trim() === "") throw new Error(`Finding #${index} must have a non-empty "detail".`);
+		if (fields.discriminator !== void 0 && typeof fields.discriminator !== "string") throw new Error(`The "discriminator" of finding #${index} must be a string.`);
+		const extraFields = Object.fromEntries(Object.entries(fields).filter(([key]) => !KNOWN_FIELDS.includes(key)));
+		const identity = {
+			task: task.id,
+			unit: unit.key,
+			ruleId: fields.ruleId,
+			discriminator: fields.discriminator ?? ""
+		};
+		const fingerprint = getFingerprint(identity);
+		return {
+			fingerprint,
+			id: hash$1(fingerprint),
+			...identity,
+			detail: fields.detail.trim(),
+			fragment,
+			...unit.path ? { path: unit.path } : {},
+			...extraFields
+		};
+	});
+}
+//#endregion
+//#region src/runner/runtask.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const DEFAULT_CONCURRENCY = 1;
+/**
+* Judges a bounded batch, applies verified fixes, and writes the state for the caller to publish.
+* Failed units and discarded fixes keep their previous baseline so the next run retries them.
+* Existing open findings remain until a human resolves them or a new report prunes reviewed fixes.
+*/
+async function runTask(runOptions) {
+	const { instance: { task, directory }, target, branch, today, pruneFixed, log } = runOptions;
+	const { options, include, exclude } = task;
+	const root = upath.normalize(await realpath(runOptions.root));
+	const statePath = upath.join(root, STATE_DIRECTORY, task.id);
+	const state = await readTaskState(statePath);
+	const usage = {
+		cost: 0,
+		tokens: 0
+	};
+	const agentWarnings = /* @__PURE__ */ new Set();
+	const createPhaseAgent = (tools) => createAgent({
+		taskId: task.id,
+		config: task.agent,
+		taskDirectory: directory,
+		cwd: root,
+		tools,
+		usage,
+		log,
+		warn: (message) => agentWarnings.add(message)
+	});
+	const judgeAgent = createPhaseAgent(task.agent?.judgeTools ?? READ_ONLY_TOOLS);
+	const fixAgent = createPhaseAgent(task.agent?.fixTools ?? [
+		...READ_ONLY_TOOLS,
+		"edit",
+		"write"
+	]);
+	const judgeContext = createTaskContext({
+		root,
+		phase: "judge",
+		options,
+		agent: judgeAgent,
+		log
+	});
+	const fixContext = createWritableTaskContext({
+		root,
+		phase: "fix",
+		options,
+		agent: fixAgent,
+		log
+	});
+	const verifyContext = createWritableTaskContext({
+		root,
+		phase: "verify",
+		options,
+		agent: fixAgent,
+		log
+	});
+	const shared = task.prepare ? await task.prepare(judgeContext) : void 0;
+	const units = task.scope ? await task.scope({
+		...judgeContext,
+		shared,
+		include,
+		exclude
+	}) : (await judgeContext.repo.list(include, { ignore: exclude })).map((path) => ({
+		key: path,
+		path
+	}));
+	const { decisions } = state;
+	const operations = {
+		async contentHash(unit) {
+			return task.contentHash({
+				...judgeContext,
+				shared,
+				unit
+			});
+		},
+		async judge(unit, fragment) {
+			const payload = await task.payload({
+				...judgeContext,
+				shared,
+				unit
+			});
+			const priorDecisions = getPriorDecisions(decisions, unit.key, fragment);
+			const findings = validateFindings(await task.judge({
+				...judgeContext,
+				shared,
+				unit,
+				payload,
+				priorDecisions
+			}), {
+				task,
+				unit,
+				fragment
+			});
+			return [...new Map(findings.map((finding) => [finding.fingerprint, finding])).values()];
+		},
+		isRejected(finding) {
+			return findDecisions(decisions, finding).some((decision) => decision.fragment === finding.fragment);
+		}
+	};
+	const unitRuns = /* @__PURE__ */ new Map();
+	for (const unit of units.toSorted((a, b) => compare(a.key, b.key))) {
+		if (unitRuns.has(unit.key)) throw new Error(`\`scope()\` returned the "${unit.key}" unit more than once.`);
+		unitRuns.set(unit.key, {
+			unit,
+			fixes: /* @__PURE__ */ new Map()
+		});
+	}
+	for (const record of unitRuns.values()) try {
+		record.current = { fragment: await operations.contentHash(record.unit) };
+	} catch (error) {
+		record.error = `contentHash() failed: ${getErrorMessage(error)}`;
+	}
+	const baseline = Object.fromEntries(Object.entries(state.baseline).filter(([key]) => unitRuns.has(key)));
+	const open = state.open.filter((finding) => !pruneFixed || !finding.fix);
+	const openFingerprints = new Set(open.map((finding) => finding.fingerprint));
+	const changedUnits = [...unitRuns.values()].filter(({ unit, current }) => current && current.fragment !== baseline[unit.key]);
+	const takenUnits = changedUnits.slice(0, task.maxUnits);
+	const deferred = changedUnits.length - takenUnits.length;
+	log(`${units.length} units in scope, ${changedUnits.length} changed, ${takenUnits.length} taken in this run` + (deferred ? ` (${deferred} left for the next runs).` : "."));
+	if (takenUnits.length) log(`Judging ${takenUnits.length} units...`);
+	const queue = [...takenUnits];
+	await Promise.all(Array.from({ length: task.concurrency ?? DEFAULT_CONCURRENCY }, async () => {
+		for (let record = queue.shift(); record; record = queue.shift()) try {
+			record.judged = await operations.judge(record.unit, record.current.fragment);
+			record.current.findings = record.judged;
+		} catch (error) {
+			record.error = getErrorMessage(error);
+		}
+	}));
+	const getActionable = (record) => {
+		return record.judged ? record.current.findings.filter((finding) => !operations.isRejected(finding)) : [];
+	};
+	const toFix = takenUnits.filter((record) => getActionable(record).length).length;
+	let files = [];
+	if (task.fix && toFix) {
+		const tracker = await createChangeTracker(root);
+		const beforeFixes = await tracker.capture();
+		const fixer = {
+			...operations,
+			task,
+			shared,
+			root,
+			units: unitRuns,
+			tracker,
+			fixContext,
+			verifyContext
+		};
+		log(`Fixing ${toFix} units...`);
+		for (const record of takenUnits) {
+			const actionable = getActionable(record);
+			if (!actionable.length) continue;
+			const outcome = await fixUnit(fixer, record, actionable);
+			if (outcome.status === "kept") {
+				const fix = {
+					files: outcome.files.map((file) => upath.relative(root, file)),
+					fixedAt: today
+				};
+				for (const [affected, fingerprints] of outcome.resolved) for (const fingerprint of fingerprints) affected.fixes.set(fingerprint, fix);
+			} else if (outcome.status === "discarded") record.discarded = outcome;
+		}
+		files = (await tracker.collect(beforeFixes)).changed;
+	}
+	const judged = [...unitRuns.values()].filter((record) => record.judged);
+	const counts = {
+		newFindings: 0,
+		alreadyOpen: 0,
+		rejected: 0
+	};
+	for (const { unit, current, judged: findings, discarded } of judged) {
+		for (const finding of findings) if (openFingerprints.has(finding.fingerprint)) counts.alreadyOpen++;
+		else if (operations.isRejected(finding)) counts.rejected++;
+		else {
+			const decision = findDecisions(decisions, finding).at(-1);
+			counts.newFindings++;
+			open.push({
+				...finding,
+				reportedAt: today,
+				previousDecision: decision && {
+					file: decision.file,
+					fragment: decision.fragment,
+					finding: decision.finding,
+					reason: decision.reason
+				}
+			});
+		}
+		if (!discarded) baseline[unit.key] = current.fragment;
+	}
+	const fixed = open.filter((finding) => unitRuns.get(finding.unit)?.fixes.has(finding.fingerprint));
+	for (const finding of fixed) {
+		const record = unitRuns.get(finding.unit);
+		finding.fix = {
+			...record.fixes.get(finding.fingerprint),
+			fragment: record.current.fragment
+		};
+	}
+	await writeTaskState(statePath, {
+		baseline,
+		open,
+		report: renderReport({
+			task,
+			target,
+			branch,
+			open
+		})
+	});
+	const errors = [...unitRuns.values()].filter((record) => record.error !== void 0).map(({ unit, error }) => ({
+		unit: unit.key,
+		message: error
+	}));
+	const discardedRuns = judged.filter((record) => record.discarded);
+	return {
+		summary: {
+			task: task.id,
+			title: task.title,
+			units: units.length,
+			changed: changedUnits.length,
+			judged: judged.length,
+			deferred,
+			...counts,
+			fixed: fixed.length,
+			discarded: discardedRuns.reduce((total, record) => total + record.discarded.findings, 0),
+			changedFiles: files.length,
+			open: open.filter((finding) => !finding.fix).length,
+			errors: errors.length,
+			problems: [
+				...errors,
+				...discardedRuns.map(({ unit, discarded }) => ({
+					unit: unit.key,
+					message: `The fix was discarded. ${discarded.message}`
+				})),
+				...[...state.warnings, ...agentWarnings].map((message) => ({ message }))
+			],
+			cost: usage.cost,
+			tokens: usage.tokens
+		},
+		files,
+		open
+	};
+}
+//#endregion
+//#region src/runner/runtarget.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Runs the selected tasks against one target, in the working tree of the checkout.
+*
+* Both flows judge, fix, and write the state in the checkout. Kept fixes and the state stay in the files. A local run
+* stops there: nothing is committed or pushed. A published run does every task on its own report branch: it continues
+* the open report pull request or starts a new branch at the base branch, commits and pushes once, opens or updates
+* the pull request, and checks out the base branch again.
+*/
+async function runTarget(options) {
+	const { target, workspace, github, log } = options;
+	const instances = [...target.tasks.values()].filter(({ task, enabled }) => {
+		return options.taskIds.length ? options.taskIds.includes(task.id) : enabled;
+	});
+	if (!instances.length) {
+		log(`No tasks are enabled for the "${target.name}" target. Skipping.`);
+		return [];
+	}
+	const root = upath.join(workspace.path, target.root);
+	if (!existsSync(root)) throw new Error(`The root of the "${target.name}" target, "${target.root}", does not exist in the checkout.`);
+	const results = [];
+	for (const instance of instances) {
+		const { task } = instance;
+		const startedAt = Date.now();
+		let result;
+		log(`Running the "${task.id}" task...`);
+		try {
+			result = github ? await publishTask(options, github, root, instance) : { summary: (await executeTask(options, root, instance, false)).summary };
+		} catch (error) {
+			result = { failure: getErrorMessage(error) };
+		}
+		if (result.failure) log(`  The "${task.id}" task failed: ${result.failure}`);
+		results.push({
+			task: task.id,
+			title: task.title,
+			durationMs: Date.now() - startedAt,
+			...result
+		});
+	}
+	return results;
+}
+function getReportBranch(taskId, target, branch) {
+	return `${REPORT_BRANCH_PREFIX}/${taskId}/${target.name}/${branch}`;
+}
+function executeTask(options, root, instance, pruneFixed) {
+	const { target, workspace, today, log } = options;
+	return runTask({
+		instance,
+		target,
+		root,
+		branch: workspace.branch,
+		today,
+		pruneFixed,
+		log: (message) => log(`  ${message}`)
+	});
+}
+async function publishTask(options, github, root, instance) {
+	const { target, workspace, today, buildUrl, log } = options;
+	const { task } = instance;
+	const { branch } = workspace;
+	const reportBranch = getReportBranch(task.id, target, branch);
+	let pullRequest = await github.findOpenPullRequest({
+		slug: target.slug,
+		head: reportBranch
+	});
+	let saved;
+	let failure;
+	try {
+		await workspace.checkoutReportBranch({
+			name: reportBranch,
+			continueExisting: Boolean(pullRequest)
+		});
+		log(pullRequest ? `  Continuing the open report pull request: ${pullRequest.html_url}` : `  Starting the "${reportBranch}" report branch at "${branch}".`);
+		saved = await executeTask(options, root, instance, !pullRequest);
+		const paths = [upath.join(target.root, STATE_DIRECTORY, task.id), ...saved.files.map((file) => upath.relative(workspace.path, file))];
+		const judged = saved.summary.judged;
+		if (await workspace.commit(paths, `${task.title}: ${judged} ${plural(judged, "unit")} judged.`)) {
+			await workspace.push();
+			const fixed = saved.open.filter((finding) => finding.fix).length;
+			const body = renderPullRequestBody({
+				task,
+				target,
+				branch,
+				reportBranch,
+				open: saved.open.length - fixed,
+				fixed
+			});
+			if (pullRequest) await github.updatePullRequest({
+				slug: target.slug,
+				number: pullRequest.number,
+				body
+			});
+			else {
+				pullRequest = await github.createPullRequest({
+					slug: target.slug,
+					head: reportBranch,
+					base: branch,
+					title: `${task.title}: ${target.name} (${branch})`,
+					body
+				});
+				log(`  Opened the report pull request: ${pullRequest.html_url}`);
+			}
+			await github.createComment({
+				slug: target.slug,
+				number: pullRequest.number,
+				body: renderRunComment({
+					today,
+					buildUrl,
+					summary: saved.summary
+				})
+			});
+		} else log("  Nothing new. Nothing was pushed.");
+	} catch (error) {
+		failure = getErrorMessage(error);
+	} finally {
+		try {
+			await workspace.returnToBase();
+		} catch (error) {
+			const message = `Returning to the base branch failed: ${getErrorMessage(error)}`;
+			failure = failure ? `${failure}\n${message}` : message;
+		}
+	}
+	return saved ? {
+		summary: saved.summary,
+		failure,
+		pullRequestUrl: pullRequest?.html_url
+	} : { failure };
+}
+//#endregion
+//#region src/runtasks.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Runs the tasks against the targets in the checkout. The result is not `ok` when a task or a unit failed. Findings
+* never make a run fail.
+*/
+async function runTasks(options) {
+	const { log = console.log, tasks: taskIds, token } = options;
+	const targets = await loadConfig(options.configPath);
+	const workspace = await openWorkspace({
+		cwd: options.cwd,
+		author: options.author
+	});
+	const selectedTargets = selectTargets(targets, {
+		originSlug: workspace.originSlug,
+		names: options.targets,
+		taskIds
+	});
+	const publish = Boolean(token);
+	const github = publish ? createGitHubClient(token) : void 0;
+	const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const { branch } = workspace;
+	const results = [];
+	if (publish) await workspace.assertPublishable(selectedTargets.flatMap((target) => [...target.tasks.keys()].map((taskId) => {
+		return upath.join(target.root, STATE_DIRECTORY, taskId, "open.json");
+	})));
+	for (const target of selectedTargets) {
+		const targetResult = {
+			target: target.name,
+			branch,
+			publish
+		};
+		log(`\n○ Running "${target.name}" (${target.slug}, ${branch})...`);
+		try {
+			results.push({
+				...targetResult,
+				results: await runTarget({
+					target,
+					taskIds,
+					workspace,
+					github,
+					today,
+					buildUrl: options.buildUrl,
+					log: (message) => log(`  ${message}`)
+				})
+			});
+		} catch (error) {
+			log(`  Running "${target.name}" failed: ${getErrorMessage(error)}`);
+			results.push({
+				...targetResult,
+				results: [],
+				error: getErrorMessage(error)
+			});
+		}
+	}
+	return {
+		ok: results.every(({ results: taskResults, error }) => {
+			return !error && taskResults.every(({ failure, summary }) => !failure && !summary?.errors);
+		}),
+		targets: results
+	};
+}
+//#endregion
+//#region src/report/renderconsolesummary.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Renders what a run did, as plain text for the console: one block per task of every target.
+*/
+function renderConsoleSummary(targets) {
+	return targets.flatMap((target) => {
+		const heading = `${target.target} (${target.branch})`;
+		if (target.error) return [[`${heading} · failed`, row("Error", inline(target.error))].join("\n")];
+		if (!target.results.length) return [`${heading} · no enabled tasks`];
+		return target.results.map((result) => renderTask(result, `${heading} · ${target.publish ? "published" : "local"}`));
+	}).join("\n\n");
+}
+function renderTask(result, heading) {
+	const lines = [`${result.title} · ${heading}`];
+	const { summary, failure } = result;
+	if (!summary) {
+		lines.push(row("Failed", inline(failure)), row("Time", formatDuration(result.durationMs)));
+		return lines.join("\n");
+	}
+	const problems = [...failure ? [`Publishing failed: ${inline(failure)}`] : [], ...summary.problems.map(({ unit, message }) => inline(unit ? `${unit}: ${message}` : message))];
+	lines.push(row("Units", `${summary.units} in scope · ${summary.changed} changed · ${summary.judged} judged` + (summary.deferred ? ` · ${summary.deferred} left for the next runs` : "")), row("Findings", `${summary.newFindings} new · ${summary.alreadyOpen} already open · ${summary.rejected} rejected`), row("Fixes", `${summary.fixed} fixed · ${summary.discarded} discarded`), row("Files", `${summary.changedFiles} changed`), row("Open", String(summary.open)), row("Cost", `$${summary.cost.toFixed(2)} · ${summary.tokens} tokens · ${formatDuration(result.durationMs)}`), row("Problems", problems.length ? String(problems.length) : "none"), ...problems.map((problem) => row("", `• ${problem}`)));
+	if (result.pullRequestUrl) lines.push(row("Pull request", result.pullRequestUrl));
+	return lines.join("\n");
+}
+function row(label, value) {
+	return `  ${label.padEnd(13)}${value}`;
+}
+function formatDuration(milliseconds) {
+	const tenths = Math.round(milliseconds / 100);
+	if (tenths < 600) return `${(tenths / 10).toFixed(1)} s`;
+	const seconds = Math.round(milliseconds / 1e3);
+	return `${Math.floor(seconds / 60)} min ${seconds % 60} s`;
+}
+//#endregion
+//#region src/commands/resolvefinding.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Rejects or dismisses one finding in the working tree of the checkout, by its short ID:
+*
+* 1. If the finding has a fix, every file of the fix is restored: from the base branch on a report branch,
+*    from `HEAD` otherwise.
+* 2. If other fixes changed any of those files, they are lost too. Without `force`, nothing changes and the error
+*    lists them. With `force`, all their files are restored as well, their findings lose the fix, and their units are
+*    judged and fixed again by the next run.
+* 3. The finding leaves `open.json`. When rejecting, a decision file records the reason.
+* 4. `report.md` is regenerated. The changes stay in the working tree for a human to review and commit.
+*/
+async function resolveFinding(options) {
+	const { tasks: taskIds } = options;
+	const targets = await loadConfig(options.configPath);
+	const workspace = await openWorkspace({ cwd: options.cwd });
+	const selectedTargets = selectTargets(targets, {
+		originSlug: workspace.originSlug,
+		names: options.targets,
+		taskIds
+	});
+	const entries = await readStates(workspace, [...targets.values()].filter((target) => target.slug === workspace.originSlug));
+	const { entry, finding } = findFinding(entries.filter((entry) => selectedTargets.includes(entry.target) && (!taskIds.length || taskIds.includes(entry.task.id))), options.id);
+	const reportBranch = parseReportBranch(workspace.branch);
+	if (reportBranch && (reportBranch.task !== entry.task.id || reportBranch.target !== entry.target.name)) throw new Error(`The [${finding.id}] finding belongs to the "${entry.task.id}" task in the "${entry.target.name}" target, but the "${workspace.branch}" report branch is checked out. Check out "${getReportBranch(entry.task.id, entry.target, reportBranch.base)}" first.`);
+	const affected = getAffectedFixes(entries, finding);
+	const others = affected.filter((item) => item.finding !== finding);
+	if (others.length && !options.force) throw new Error([
+		`Reverting the fix of [${finding.id}] also undoes these fixes, because they changed the same files:`,
+		...others.map(({ finding: other, files }) => {
+			return `  [${other.id}] ${describe(other)} (${other.task}): ${files.join(", ")}`;
+		}),
+		"Nothing was changed. Re-run with \"--force\" to revert them too. Their findings then stay open, and the next run judges and fixes them again."
+	].join("\n"));
+	const baseBranch = reportBranch?.base;
+	const fixFiles = [...new Set(affected.flatMap((item) => item.files))].sort();
+	const canRestore = !fixFiles.length || Boolean(baseBranch) || await workspace.hasChanges(fixFiles);
+	const revertedFiles = canRestore ? fixFiles : [];
+	if (revertedFiles.length) await workspace.restore(revertedFiles, baseBranch ? await getRestoreRef(workspace, baseBranch) : "HEAD");
+	for (const item of affected) {
+		delete item.entry.state.baseline[item.finding.unit];
+		delete item.finding.fix;
+	}
+	entry.state.open = entry.state.open.filter((candidate) => candidate !== finding);
+	const decisionFile = options.action === "reject" ? await writeDecision(entry, finding, options.reason, workspace) : void 0;
+	for (const { target, task, statePath, state: { baseline, open } } of /* @__PURE__ */ new Set([entry, ...affected.map((item) => item.entry)])) await writeTaskState(statePath, {
+		baseline,
+		open,
+		report: renderReport({
+			task,
+			target,
+			branch: baseBranch ?? workspace.branch,
+			open
+		})
+	});
+	return {
+		action: options.action,
+		target: entry.target.name,
+		finding,
+		decisionFile,
+		revertedFiles,
+		unrevertedFiles: canRestore ? [] : fixFiles,
+		reopened: others.map((item) => item.finding)
+	};
+}
+/**
+* Renders what `resolveFinding()` did, as plain text for the console.
+*/
+function renderResolvedFinding(result) {
+	const { finding } = result;
+	const lines = [`${result.action === "reject" ? "Rejected" : "Dismissed"} [${finding.id}] ${describe(finding)} (${finding.task}, ${result.target}).`];
+	if (result.decisionFile) lines.push(`  Decision  ${result.decisionFile}`);
+	if (result.unrevertedFiles.length) lines.push(`  Reverted  nothing: ${result.unrevertedFiles.join(", ")} had no uncommitted changes. If the fix is committed, revert it by hand.`);
+	else if (result.revertedFiles.length) lines.push(`  Reverted  ${result.revertedFiles.join(", ")}`);
+	else lines.push("  Reverted  nothing (the finding had no fix)");
+	for (const item of result.reopened) lines.push(`  Reopened  [${item.id}] ${describe(item)} (${item.task}), fixed again on the next run`);
+	lines.push("", "Nothing was committed. Review the changes with \"git status\" and \"git diff HEAD\", then commit them.");
+	return lines.join("\n");
+}
+async function readStates(workspace, targets) {
+	const entries = [];
+	for (const target of targets) for (const { task } of target.tasks.values()) {
+		const statePath = upath.join(workspace.path, target.root, STATE_DIRECTORY, task.id);
+		entries.push({
+			target,
+			task,
+			statePath,
+			state: await readTaskState(statePath)
+		});
+	}
+	return entries;
+}
+function findFinding(entries, id) {
+	const prefix = id.trim().toLowerCase().replace(/^\[|\]$/g, "");
+	const matches = entries.flatMap((entry) => {
+		return entry.state.open.filter((finding) => getFindingId(finding.fingerprint).startsWith(prefix)).map((finding) => ({
+			entry,
+			finding
+		}));
+	});
+	if (!prefix || !matches.length) throw new Error(`No open finding has the "${id}" ID.`);
+	if (matches.length > 1) throw new Error([`The "${id}" ID matches more than one finding. Use more characters of the ID:`, ...matches.map(({ finding }) => `  [${getFindingId(finding.fingerprint)}] ${describe(finding)} (${finding.task})`)].join("\n"));
+	return matches[0];
+}
+/**
+* Returns the fix of the finding, and every other fix that shares a file with the ones found so far. Restoring a shared
+* file undoes all of them, so each of them is undone completely.
+*/
+function getAffectedFixes(entries, finding) {
+	const fixed = entries.flatMap((entry) => entry.state.open.filter((item) => item.fix).map((item) => ({
+		entry,
+		finding: item,
+		files: item.fix.files.map((file) => upath.join(entry.target.root, file))
+	})));
+	const start = fixed.find((item) => item.finding === finding);
+	if (!start) return [];
+	const affected = [start];
+	const files = new Set(start.files);
+	for (let index = 0; index < affected.length; index++) for (const item of fixed) if (!affected.includes(item) && item.files.some((file) => files.has(file))) {
+		affected.push(item);
+		item.files.forEach((file) => files.add(file));
+	}
+	return affected;
+}
+/**
+* Splits the name of a report branch, `ai-tasks/<task>/<target>/<base branch>`, into its parts.
+*/
+function parseReportBranch(branch) {
+	const [prefix, task, target, ...base] = branch.split("/");
+	return prefix === "ai-tasks" && task && target && base.length ? {
+		task,
+		target,
+		base: base.join("/")
+	} : void 0;
+}
+async function getRestoreRef(workspace, baseBranch) {
+	for (const ref of [`origin/${baseBranch}`, baseBranch]) if (await workspace.refExists(ref)) return ref;
+	throw new Error(`The "${baseBranch}" base branch of the "${workspace.branch}" report branch does not exist. Fetch it first.`);
+}
+async function writeDecision(entry, finding, reason, workspace) {
+	const directory = upath.join(entry.statePath, "decisions");
+	const name = getDecisionFileName(finding);
+	let path = upath.join(directory, `${name}.yml`);
+	for (let suffix = 2; existsSync(path); suffix++) path = upath.join(directory, `${name}-${suffix}.yml`);
+	await mkdir(directory, { recursive: true });
+	await writeFile(path, renderDecision(finding, reason));
+	return upath.relative(workspace.path, path);
+}
+function describe(finding) {
+	return `${finding.ruleId}${finding.discriminator ? ` (${finding.discriminator})` : ""} in ${finding.unit}`;
+}
+//#endregion
+//#region src/cli.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const COMMON_OPTIONS = {
+	config: {
+		type: "string",
+		default: "ai-tasks"
+	},
+	cwd: {
+		type: "string",
+		default: "."
+	},
+	target: {
+		type: "string",
+		multiple: true,
+		default: []
+	},
+	task: {
+		type: "string",
+		multiple: true,
+		default: []
+	}
+};
+/**
+* Parses the arguments of the `ckeditor5-dev-agents` command:
+*
+* * `--config <path>`: the directory with `tasks/` and `targets/`. Default: `ai-tasks`.
+* * `--cwd <path>`: a directory inside the checkout to run in. Default: the current directory.
+* * `--target <name>`: the targets to run (repeatable or comma-separated). Default: the targets of the checkout.
+* * `--task <id>`: the tasks to run (repeatable or comma-separated). Default: the tasks each target enables.
+* * `--publish`: commit and push the state and the fixes, and open or update the report pull requests.
+*
+* Paths are relative to the current directory.
+*/
+function parseArguments(cliArguments, { cwd = process.cwd(), env = process.env } = {}) {
+	const { values } = parseArgs({
+		args: cliArguments,
+		options: {
+			...COMMON_OPTIONS,
+			publish: {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	if (values.publish && !env.AI_TASKS_GITHUB_TOKEN) throw new Error("A published run needs a GitHub token in the \"AI_TASKS_GITHUB_TOKEN\" environment variable.");
+	return {
+		...resolveCommonArguments(values, cwd),
+		token: values.publish ? env.AI_TASKS_GITHUB_TOKEN : void 0,
+		author: {
+			name: env.AI_TASKS_GIT_NAME || "CKEditor AI Tasks",
+			email: env.AI_TASKS_GIT_EMAIL || "ai-tasks@users.noreply.github.com"
+		},
+		buildUrl: env.AI_TASKS_BUILD_URL
+	};
+}
+/**
+* Parses the arguments of the `reject` and `dismiss` commands:
+*
+* * `ckeditor5-dev-agents reject <id> --reason "…"`: the finding is wrong. A decision records why.
+* * `ckeditor5-dev-agents dismiss <id>`: the finding is dropped without a decision.
+*
+* Both accept `--force` (continue when other fixes change the same files), `--config`, `--cwd`, `--target` and `--task`.
+*/
+function parseResolveArguments(cliArguments, { cwd = process.cwd() } = {}) {
+	const { values, positionals } = parseArgs({
+		args: cliArguments,
+		allowPositionals: true,
+		options: {
+			...COMMON_OPTIONS,
+			reason: { type: "string" },
+			force: {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	const [action, id, ...rest] = positionals;
+	const reason = values.reason?.trim();
+	if (action !== "reject" && action !== "dismiss" || !id || rest.length) throw new Error("Usage: ckeditor5-dev-agents reject <id> --reason \"…\" | ckeditor5-dev-agents dismiss <id>");
+	if (action === "reject" && !reason) throw new Error("Rejecting a finding needs a reason. Pass it with \"--reason\".");
+	if (action === "dismiss" && values.reason) throw new Error("The \"--reason\" argument works only with \"reject\". A dismissed finding has no decision.");
+	return {
+		action,
+		id,
+		reason,
+		force: values.force,
+		...resolveCommonArguments(values, cwd)
+	};
+}
+/**
+* Runs the `ckeditor5-dev-agents` command. Returns the exit code.
+*/
+async function runCli(cliArguments) {
+	const args = cliArguments.filter((argument) => argument !== "--");
+	try {
+		if (args[0] === "reject" || args[0] === "dismiss") {
+			console.log(renderResolvedFinding(await resolveFinding(parseResolveArguments(args))));
+			return 0;
+		}
+		const { ok, targets } = await runTasks(parseArguments(args));
+		console.log(`\n${renderConsoleSummary(targets)}`);
+		if (!ok) console.error("\nSome tasks did not finish cleanly. See the problems above.");
+		return ok ? 0 : 1;
+	} catch (error) {
+		console.error(getErrorMessage(error));
+		return 1;
+	}
+}
+function resolveCommonArguments(values, cwd) {
+	return {
+		configPath: upath.resolve(cwd, values.config),
+		cwd: upath.resolve(cwd, values.cwd),
+		targets: splitList(values.target),
+		tasks: splitList(values.task)
+	};
+}
+/**
+* CI passes pipeline parameters as one string, so `--target=cs,ckbox` means the same as `--target=cs --target=ckbox`.
+*/
+function splitList(values) {
+	return [...new Set(values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))];
+}
+//#endregion
+export { parseArguments, parseResolveArguments, runCli };