pagegraph 0.14.1 → 0.15.1

package/dist/{state-BuJP_3Lr.js → state-2ikjo7uI.js}

@@ -1,3 +1,9 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
 //#region node_modules/effect/dist/Pipeable.js
 /**
 * The `Pipeable` module defines the shared interface and implementation helpers
@@ -17629,12 +17635,12 @@ const toReadableStreamEffect = /*#__PURE__*/ dual((args) => isStream(args[0]), (
 //#endregion
 //#region node_modules/effect/dist/internal/schema/annotations.js
 /** @internal */
-function resolve$1(ast) {
+function resolve$2(ast) {
 	return ast.checks ? ast.checks[ast.checks.length - 1].annotations : ast.annotations;
 }
 /** @internal */
 function resolveAt(key) {
-	return (ast) => resolve$1(ast)?.[key];
+	return (ast) => resolve$2(ast)?.[key];
 }
 /** @internal */
 const STRUCTURAL_ANNOTATION_KEY = "~structural";
@@ -17663,7 +17669,7 @@ const resolveIdentifier = /*#__PURE__*/ resolveAt("identifier");
 const resolveIdentifierFallback = /*#__PURE__*/ resolveAt(IDENTIFIER_FALLBACK_KEY);
 /** @internal */
 const getExpected = /*#__PURE__*/ memoize((ast) => {
-	const identifier = resolve$1(ast)?.identifier;
+	const identifier = resolve$2(ast)?.identifier;
 	if (typeof identifier === "string") return identifier;
 	return ast.getExpected(getExpected);
 });
@@ -20413,6 +20419,11 @@ function tuple(elements, checks = void 0) {
 function union(members, options, checks) {
 	return new Union$1(members.map(getAST), options, void 0, checks);
 }
+/** @internal */
+function mutable$1(ast) {
+	if (ast.encoding) throw new Error("mutable does not support encodings");
+	return new Arrays(true, ast.elements, ast.rest, ast.annotations, ast.checks, void 0, ast.context, ast.encodingChecks);
+}
 const toCandidate = /*#__PURE__*/ memoizeIdempotent((ast) => {
 	while (true) {
 		if (isSuspend(ast)) return unknown;
@@ -22255,8 +22266,8 @@ function compile(ast, compile, compileField, base, specialize) {
 /** @internal */
 const invalid = /*#__PURE__*/ Symbol();
 const cache = /*#__PURE__*/ new WeakMap();
-const decodeChild = (ast) => resolve(ast).parser;
-const makeChild = (ast) => resolve(ast).makeEffect;
+const decodeChild = (ast) => resolve$1(ast).parser;
+const makeChild = (ast) => resolve$1(ast).makeEffect;
 const makeField = (ast) => compileField(ast, makeChild);
 var InterpretedEntry = class {
 	ast;
@@ -22274,7 +22285,7 @@ var InterpretedEntry = class {
 	}
 };
 /** @internal */
-function resolve(ast) {
+function resolve$1(ast) {
 	const cached = cache.get(ast);
 	if (cached !== void 0) return cached;
 	const entry = new InterpretedEntry(ast);
@@ -22528,7 +22539,7 @@ function makeConstructorSync(ast) {
 	let entry;
 	let parser;
 	return (input, options) => {
-		entry ??= resolve(ast);
+		entry ??= resolve$1(ast);
 		const parseOptions = options?.disableChecks ? options.parseOptions ? {
 			...options.parseOptions,
 			disableChecks: true
@@ -22547,8 +22558,8 @@ function makeConstructorSync(ast) {
 		return runSync(parserResult((parser ??= entry.makeEffect)(input, parseOptions), input), "Constructor adapter can only throw schema issues");
 	};
 }
-const normalCompiler = (ast) => resolve(ast).parser;
-const constructorCompiler = (ast) => resolve(ast).makeEffect;
+const normalCompiler = (ast) => resolve$1(ast).parser;
+const constructorCompiler = (ast) => resolve$1(ast).makeEffect;
 //#endregion
 //#region node_modules/effect/dist/internal/schema/make.js
 /** @internal */
@@ -24600,6 +24611,33 @@ function Tuple(elements) {
 * @since 4.0.0
 */
 const ArraySchema = /*#__PURE__*/ lambda((schema) => make$5(new Arrays(false, [], [schema.ast]), { value: schema }));
+/**
+* Makes an array or tuple schema mutable, removing the `readonly` modifier.
+*
+* **Gotchas**
+*
+* This combinator does not support an encoding attached to the array or tuple
+* node and throws if one is present. Encodings on element schemas are
+* supported.
+*
+* **Example** (Defining mutable arrays)
+*
+* ```ts import.meta.vitest
+* import { Schema } from "effect"
+*
+* const schema = Schema.mutable(Schema.Array(Schema.Number))
+*
+* // number[]   (mutable)
+* type T = typeof schema.Type
+* const value: T = [1, 2]
+* value.push(3)
+* value // => [1, 2, 3]
+* ```
+*
+* @category transforming
+* @since 3.10.0
+*/
+const mutable = /*#__PURE__*/ lambda((schema) => make$5(mutable$1(schema.ast), { schema }));
 function makeUnion(ast, members) {
 	return make$5(ast, {
 		members,
@@ -25258,6 +25296,53 @@ const Int = /*#__PURE__*/ Number$1.check(/*#__PURE__*/ isInt());
 * @since 4.0.0
 */
 const Natural = /*#__PURE__*/ Int.check(/*#__PURE__*/ isGreaterThanOrEqualTo(0));
+function makeIsMinLength(minLength, minCodePoints, annotations) {
+	return makeFilter((input) => input.length >= minLength, {
+		expected: `a value with a length of at least ${minLength}`,
+		representation: {
+			id: "effect/schema/isMinLength",
+			payload: { minLength }
+		},
+		toJsonSchema: ({ type }) => type === "string" ? minLength <= 1 ? { minLength: minCodePoints } : [{ minLength: minCodePoints }, true] : type === "array" ? { minItems: minLength } : type === void 0 ? [{
+			minLength: minCodePoints,
+			minItems: minLength
+		}, true] : [{}, true],
+		toCode: () => ({ runtime: `Schema.isMinLength(${minLength})` }),
+		[STRUCTURAL_ANNOTATION_KEY]: true,
+		arbitraryConstraint: { minLength },
+		...annotations
+	});
+}
+/**
+* Validates that a value has at least one element. Works with strings and arrays.
+* This is equivalent to `isMinLength(1)`.
+*
+* **Details**
+*
+* JSON Schema:
+*
+* This check corresponds to the `minLength: 1` constraint for strings or the
+* `minItems: 1` constraint for arrays in JSON Schema.
+*
+* Arbitrary:
+*
+* During arbitrary generation, this applies a `minLength: 1`
+* constraint to ensure generated strings or arrays are non-empty.
+*
+* @category validation
+* @since 4.0.0
+*/
+function isNonEmpty(annotations) {
+	return makeIsMinLength(1, 1, annotations);
+}
+/**
+* Schema for non-empty strings. Validates that a string has at least one
+* character.
+*
+* @category schemas
+* @since 3.10.0
+*/
+const NonEmptyString = /*#__PURE__*/ String$2.check(/*#__PURE__*/ isNonEmpty());
 const getErrorOptionsKey = (options) => (options?.includeStack === true ? 1 : 0) | (options?.excludeCause === true ? 2 : 0);
 const getErrorOptions = (key) => {
 	switch (key) {
@@ -25934,6 +26019,27 @@ const Json = /*#__PURE__*/ make$5(/*#__PURE__*/ annotate(Json$1, { toCode: () =>
 	Type: "Schema.Json"
 }) }));
 /**
+* Schema for readonly string-keyed records whose values are JSON-compatible.
+*
+* **When to use**
+*
+* Use when you need to validate a JSON object rather than any JSON value.
+*
+* **Example** (Validating a JSON object)
+*
+* ```ts import.meta.vitest
+* import { Option, Schema } from "effect"
+*
+* Schema.decodeUnknownOption(Schema.JsonObject)({ key: [1, true, null] }) // => Option.some({ key: [1, true, null] })
+* Schema.decodeUnknownOption(Schema.JsonObject)([1, 2, 3]) // => Option.none()
+* ```
+*
+* @see {@link Json} for a schema that also accepts JSON arrays and primitive values
+* @category schemas
+* @since 4.0.0
+*/
+const JsonObject = /*#__PURE__*/ Record(String$2, Json);
+/**
 * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
 * the immutable variant.
 *
@@ -26736,6 +26842,488 @@ function Redacted(name) {
 	return schema(Redacted$1(String$2), name);
 }
 //#endregion
+//#region src/workflows/prompts/summary.md
+var summary_default = "# PageGraph {{workflow}}\n\n- Run: `{{runId}}`\n- Model: `{{model}}`\n- Pages: {{pages}}\n- Decisions: {{decisions}} ({{review}} review)\n- Executor searches: {{executorSearches}}\n- Executor calls: {{executorCalls}}\n- Changed files: {{changedFiles}}\n\n{{summary}}\n";
+//#endregion
+//#region src/workflows/template.ts
+const placeholder = /\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g;
+/** A small immutable builder for checked text templates imported with `type: "text"`. */
+var TextTemplate = class TextTemplate {
+	#source;
+	#values;
+	constructor(source, values) {
+		this.#source = source;
+		this.#values = values;
+	}
+	static from(source) {
+		return new TextTemplate(source, {});
+	}
+	value(name, value) {
+		return new TextTemplate(this.#source, {
+			...this.#values,
+			[name]: String(value)
+		});
+	}
+	values(values) {
+		let template = this;
+		for (const [name, value] of Object.entries(values)) template = template.value(name, value);
+		return template;
+	}
+	render() {
+		const missing = /* @__PURE__ */ new Set();
+		const rendered = this.#source.replace(placeholder, (_match, name) => {
+			const value = this.#values[name];
+			if (value === void 0) {
+				missing.add(name);
+				return "";
+			}
+			return value;
+		});
+		if (missing.size > 0) throw new Error(`Missing template values: ${[...missing].sort().join(", ")}`);
+		return rendered;
+	}
+};
+//#endregion
+//#region src/workflows/artifact.ts
+/** Write JSON through a temporary file and rename, so readers never see a partial artifact. */
+const writeJsonArtifact = (path, value) => {
+	const temporary = resolve(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+			encoding: "utf8",
+			flag: "wx"
+		});
+		renameSync(temporary, path);
+	} catch (cause) {
+		try {
+			unlinkSync(temporary);
+		} catch (cleanup) {
+			if (!(cleanup instanceof Error && "code" in cleanup && cleanup.code === "ENOENT")) throw new AggregateError([cause, cleanup], `Could not write artifact or remove its temporary file: ${path}`);
+		}
+		throw cause;
+	}
+};
+const createRunId = (date = /* @__PURE__ */ new Date(), workflow = "workflow", nonce = randomUUID()) => `${date.toISOString().replaceAll(":", "-").replace(".", "-")}-${nonce.slice(0, 8)}-${workflow.replaceAll(".", "-")}`;
+const resultSummary = (result) => {
+	if (result !== null && typeof result === "object") {
+		const summary = result["summary"];
+		if (typeof summary === "string") return summary;
+	}
+	return "Workflow completed; inspect run.json for the structured result.";
+};
+const summary = (run) => {
+	const counts = run.decisions[0]?.report.counts;
+	return TextTemplate.from(summary_default).values({
+		workflow: run.workflow,
+		runId: run.id,
+		model: `${run.model.provider}/${run.model.id}`,
+		pages: run.targets.pages.length,
+		decisions: counts?.inputs ?? 0,
+		review: counts?.review ?? 0,
+		executorSearches: run.evidence.executor.searches.length,
+		executorCalls: run.evidence.executor.calls.length,
+		changedFiles: run.changes.files.length,
+		summary: resultSummary(run.result)
+	}).render();
+};
+const writeRunBundle = (root, runsDirectory, run) => {
+	const directory = resolve(root, runsDirectory, run.id);
+	mkdirSync(directory, { recursive: true });
+	writeJsonArtifact(resolve(directory, "run.json"), run);
+	writeFileSync(resolve(directory, "summary.md"), summary(run), "utf8");
+	return directory;
+};
+const writeResearchCheckpoint = (root, runsDirectory, checkpoint) => {
+	const directory = resolve(root, runsDirectory, checkpoint.id);
+	mkdirSync(directory, { recursive: true });
+	const path = resolve(directory, "research.json");
+	writeJsonArtifact(path, checkpoint);
+	return path;
+};
+const writeWorkflowFailure = (root, runsDirectory, id, details) => {
+	const directory = resolve(root, runsDirectory, id);
+	mkdirSync(directory, { recursive: true });
+	const path = resolve(directory, "failure.json");
+	writeJsonArtifact(path, details);
+	return path;
+};
+const serializeCause = (value, top = true, seen = /* @__PURE__ */ new Set()) => {
+	if (seen.has(value)) return {
+		name: "CircularCause",
+		message: "Circular error cause"
+	};
+	if (value !== null && typeof value === "object") {
+		seen.add(value);
+		return {
+			message: value instanceof Error ? value.message : "message" in value ? String(value.message) : JSON.stringify(value),
+			name: value instanceof Error ? value.name : "name" in value ? String(value.name) : "Error",
+			...top && value instanceof Error ? { stack: value.stack } : {},
+			..."cause" in value ? { cause: serializeCause(value.cause, false, seen) } : {},
+			...value instanceof AggregateError ? { errors: value.errors.map((error) => serializeCause(error, false, new Set(seen))) } : {}
+		};
+	}
+	return {
+		name: "Error",
+		message: String(value)
+	};
+};
+const writeWorkflowProgress = (root, runsDirectory, progress) => {
+	const directory = resolve(root, runsDirectory, progress.id);
+	mkdirSync(directory, { recursive: true });
+	const path = resolve(directory, "progress.json");
+	writeJsonArtifact(path, progress);
+	return path;
+};
+//#endregion
+//#region src/workflows/repository-paths.ts
+const resolveWorkflowRepositoryRoot = async (appRoot, configuredRoot) => {
+	const root = await realpath(appRoot);
+	if (configuredRoot !== void 0) return realpath(resolve(root, configuredRoot));
+	try {
+		const { stdout } = await promisify(execFile)("git", ["rev-parse", "--show-toplevel"], { cwd: root });
+		return await realpath(stdout.trim());
+	} catch {
+		return root;
+	}
+};
+const missingPath = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const resolveWritablePath = async (path) => {
+	let ancestor = path;
+	const suffix = [];
+	while (true) try {
+		return resolve(await realpath(ancestor), ...suffix);
+	} catch (cause) {
+		if (!missingPath(cause)) throw cause;
+		try {
+			if ((await lstat(ancestor)).isSymbolicLink()) throw new Error(`Repository path has a dangling symlink: ${path}`);
+		} catch (statCause) {
+			if (!missingPath(statCause)) throw statCause;
+		}
+		const parent = dirname(ancestor);
+		if (parent === ancestor) throw cause;
+		suffix.unshift(relative(parent, ancestor));
+		ancestor = parent;
+	}
+};
+const insideRoot = (root, path) => {
+	const pathFromRoot = relative(root, path);
+	return pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot);
+};
+const resolveRepositoryReadPath = async (root, path, options = {}) => {
+	const projectRoot = await realpath(root);
+	const requested = resolve(projectRoot, path);
+	const allowedRoots = [{
+		requested: resolve(root),
+		actual: projectRoot
+	}];
+	if (options.runsDirectory !== void 0) {
+		const runsDirectory = resolve(options.runsDirectory);
+		allowedRoots.push({
+			requested: runsDirectory,
+			actual: await resolveWritablePath(runsDirectory)
+		});
+	}
+	const matchingRoots = allowedRoots.filter((allowed) => insideRoot(allowed.requested, requested) || insideRoot(allowed.actual, requested));
+	if (matchingRoots.length === 0) throw new Error(`Repository path escapes project root: ${path}`);
+	const resolved = await realpath(requested);
+	if (!matchingRoots.some((allowed) => insideRoot(allowed.actual, resolved))) throw new Error(`Repository path escapes project root through a symlink: ${path}`);
+	return resolved;
+};
+/** Resolve an edit target inside the app root, rejecting escapes, protected directories, and hard links. */
+const resolveWorkflowWritePath = async (root, path, options) => {
+	const projectRoot = await realpath(root);
+	const requested = resolve(projectRoot, path);
+	if (!insideRoot(projectRoot, requested)) throw new Error(`Repository path escapes project root: ${path}`);
+	const resolved = await resolveWritablePath(requested);
+	if (!insideRoot(projectRoot, resolved)) throw new Error(`Repository path escapes project root through a symlink: ${path}`);
+	if ([requested, resolved].some((target) => relative(projectRoot, target).split(sep).some((part) => part === ".git" || part === "node_modules"))) throw new Error(`Repository write targets a protected directory: ${path}`);
+	const forbidden = [
+		resolve(projectRoot, ".git"),
+		resolve(projectRoot, "node_modules"),
+		resolve(projectRoot, options.runsDirectory),
+		resolve(projectRoot, options.presetDirectory)
+	];
+	for (const directory of forbidden) {
+		const actual = await resolveWritablePath(directory);
+		if (insideRoot(directory, requested) || insideRoot(actual, resolved)) throw new Error(`Repository write targets a protected directory: ${path}`);
+	}
+	const existing = await lstat(resolved).catch((error) => {
+		if (missingPath(error)) return void 0;
+		throw error;
+	});
+	if (existing !== void 0 && existing.nlink > 1) throw new Error(`Repository write targets a hard-linked file: ${path}`);
+	return resolved;
+};
+//#endregion
+//#region src/workflows/review.ts
+/**
+* One source change. `oldText` is copied exactly from the current file and must match once;
+* omitting it creates `path`, which must not exist yet.
+*/
+const WorkflowEdit = Struct({
+	path: String$2,
+	oldText: optional(NonEmptyString),
+	newText: String$2,
+	reason: String$2,
+	evidence: ArraySchema(String$2)
+});
+/** A recommendation a human must handle because the agent cannot or should not edit it. */
+const WorkflowReviewItem = Struct({
+	path: String$2,
+	reason: String$2,
+	evidence: ArraySchema(String$2)
+});
+/** The structured result an improve workflow's action turn submits. */
+const ActionState = Struct({
+	summary: String$2,
+	edits: ArraySchema(WorkflowEdit),
+	reviewItems: ArraySchema(WorkflowReviewItem)
+});
+const decodeActionState = decodeUnknownSync(ActionState, { errors: "all" });
+const actionDocument = toJsonSchemaDocument(ActionState);
+const actionStateJsonSchema = {
+	...actionDocument.schema,
+	$defs: actionDocument.definitions
+};
+const RecordedEdit = Struct({
+	id: String$2,
+	...WorkflowEdit.fields
+});
+const RecordedReviewItem = Struct({
+	source: Literals(["agent", "decision"]),
+	...WorkflowReviewItem.fields
+});
+const decodeWorkflowEdits = decodeUnknownSync(Struct({
+	kind: Literal("pagegraph-workflow-edits"),
+	schemaVersion: Literal(1),
+	id: String$2,
+	workflow: String$2,
+	/** `write` runs applied these edits before recording them; `dry-run` runs left sources untouched. */
+	mode: Literals(["write", "dry-run"]),
+	/** The app root containing `pagegraph.config.ts`; edit paths are relative to it. */
+	root: String$2,
+	summary: String$2,
+	edits: ArraySchema(RecordedEdit),
+	reviewItems: ArraySchema(RecordedReviewItem)
+}), { errors: "all" });
+/**
+* Re-express agent edit paths relative to the app root. Agents read through the repository read
+* root, so they submit paths in that frame; edits.json and `pagegraph apply` use the app root.
+*/
+const normalizeEditPaths = (state, readRoot, root) => {
+	const repositoryRoot = realpathSync(readRoot);
+	const appRoot = realpathSync(root);
+	return {
+		...state,
+		edits: state.edits.map((edit) => {
+			const absolute = resolve(repositoryRoot, edit.path);
+			if (!insideRoot(appRoot, absolute)) throw new Error(`Edit path is outside the app root ${relative(repositoryRoot, appRoot) || "."}: ${edit.path}`);
+			return {
+				...edit,
+				path: relative(appRoot, absolute)
+			};
+		})
+	};
+};
+const answerSummary = (answers) => {
+	if (answers === null || typeof answers !== "object") return [];
+	return Object.entries(answers).map(([name, answer]) => {
+		if (answer !== null && typeof answer === "object") {
+			const value = answer;
+			if (typeof value.probability === "number") return `${name}: ${value.probability.toFixed(2)}`;
+			if (typeof value.label === "string") {
+				const probability = value.probabilities !== null && typeof value.probabilities === "object" ? value.probabilities[value.label] : void 0;
+				return `${name}: ${value.label}${typeof probability === "number" ? ` (${probability.toFixed(2)})` : ""}`;
+			}
+		}
+		return `${name}: ${JSON.stringify(answer)}`;
+	});
+};
+/** The researched proposal a review decision judged, so a reviewer can act without opening research.json. */
+const decisionProposal = (decisionId, inputs) => {
+	const match = /:(\d+)$/.exec(decisionId);
+	const proposal = match === null ? void 0 : inputs[Number(match[1])];
+	return proposal === void 0 ? [] : [`proposal: ${JSON.stringify(proposal)}`];
+};
+const workflowEditsArtifact = (input) => ({
+	kind: "pagegraph-workflow-edits",
+	schemaVersion: 1,
+	id: input.id,
+	workflow: input.workflow,
+	mode: input.mode,
+	root: input.root,
+	summary: input.action.summary,
+	edits: input.action.edits.map((edit, index) => ({
+		id: `e${index + 1}`,
+		...edit
+	})),
+	reviewItems: [...input.action.reviewItems.map((item) => ({
+		source: "agent",
+		...item
+	})), ...input.decisions.review.map((record) => ({
+		source: "decision",
+		path: record.inputRef,
+		reason: `Jev returned ${record.verdict} for ${record.decisionId} at threshold ${record.threshold}; a human decides whether to change it.`,
+		evidence: [...decisionProposal(record.decisionId, input.decisionInputs), ...answerSummary(record.answers)]
+	}))]
+});
+const fenceFor = (text) => {
+	const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
+	return "`".repeat(longest + 1);
+};
+const prefixed = (prefix, text) => text.split("\n").map((line) => `${prefix}${line}`).join("\n");
+const evidenceList = (evidence) => evidence.length === 0 ? "Evidence: none recorded." : `Evidence:\n\n${evidence.map((item) => `- ${item}`).join("\n")}`;
+const renderReview = (edits, runDirectory) => {
+	const body = edits.edits.map((edit) => {
+		const diff = edit.oldText === void 0 ? prefixed("+ ", edit.newText) : `${prefixed("- ", edit.oldText)}\n${prefixed("+ ", edit.newText)}`;
+		const fence = fenceFor(diff);
+		return [
+			`### ${edit.id} · \`${edit.path}\`${edit.oldText === void 0 ? " (new file)" : ""}`,
+			edit.reason,
+			evidenceList(edit.evidence),
+			`${fence}diff\n${diff}\n${fence}`
+		].join("\n\n");
+	});
+	const review = edits.reviewItems.map((item) => [
+		`### \`${item.path}\` (${item.source})`,
+		item.reason,
+		evidenceList(item.evidence)
+	].join("\n\n"));
+	return [
+		`# PageGraph ${edits.workflow} review`,
+		[
+			`- Run: \`${edits.id}\``,
+			`- Mode: ${edits.mode === "write" ? "write (PageGraph applies these edits during the run)" : "dry-run (source files are unchanged)"}`,
+			`- Edits: ${edits.edits.length}`,
+			`- Review items: ${edits.reviewItems.length}`
+		].join("\n"),
+		edits.summary,
+		`## Edits\n\n${body.length === 0 ? "No edits." : body.join("\n\n")}`,
+		`## Review items\n\n${review.length === 0 ? "No review items." : review.join("\n\n")}`,
+		...edits.mode === "dry-run" && edits.edits.length > 0 ? [[
+			"## Apply",
+			"Check and apply from the directory containing `pagegraph.config.ts`. Edits whose target text changed are refused as stale.",
+			[
+				"```sh",
+				`pagegraph apply ${runDirectory} --check`,
+				`pagegraph apply ${runDirectory}`,
+				`pagegraph apply ${runDirectory} --only e1`,
+				"```"
+			].join("\n")
+		].join("\n\n")] : []
+	].join("\n\n") + "\n";
+};
+/** Write `edits.json` and `review.md` into the run directory. */
+const writeWorkflowEdits = (runDirectory, edits) => {
+	mkdirSync(runDirectory, { recursive: true });
+	const path = resolve(runDirectory, "edits.json");
+	writeJsonArtifact(path, edits);
+	writeFileSync(resolve(runDirectory, "review.md"), renderReview(edits, runDirectory), "utf8");
+	return path;
+};
+/** Resolve `<run-dir|run-id>` the same way `--from` does and decode its `edits.json`. */
+const readWorkflowEdits = (root, runsDirectory, run) => {
+	const directory = isAbsolute(run) || run.includes("/") || run.includes("\\") ? resolve(root, run) : resolve(root, runsDirectory, run);
+	const path = resolve(directory, "edits.json");
+	if (!existsSync(path)) throw new Error(`No edits.json in ${directory}; only completed improve workflow runs record edits.`);
+	try {
+		return {
+			directory,
+			edits: decodeWorkflowEdits(JSON.parse(readFileSync(path, "utf8")))
+		};
+	} catch (cause) {
+		throw new Error(`Invalid edits artifact ${path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+};
+const occurrences = (content, text) => {
+	let count = 0;
+	for (let index = content.indexOf(text); index >= 0; index = content.indexOf(text, index + 1)) count++;
+	return count;
+};
+const readOptional = async (path) => {
+	try {
+		return await readFile(path, "utf8");
+	} catch (cause) {
+		if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") return void 0;
+		throw cause;
+	}
+};
+/**
+* Apply edits in order against current files. Each edit is checked independently: a target that
+* no longer matches exactly once (or a new file that now exists) is `stale` and skipped; a path the
+* write policy refuses or an I/O error is `failed`. `check` reports `applicable` without writing.
+*/
+const applyWorkflowEdits = async (root, edits, options) => {
+	const outcomes = /* @__PURE__ */ new Map();
+	const fail = (edit, cause) => outcomes.set(edit.id, {
+		id: edit.id,
+		path: edit.path,
+		status: "failed",
+		reason: cause instanceof Error ? cause.message : String(cause)
+	});
+	const byTarget = /* @__PURE__ */ new Map();
+	for (const edit of edits) try {
+		const target = await resolveWorkflowWritePath(root, edit.path, options);
+		byTarget.set(target, [...byTarget.get(target) ?? [], edit]);
+	} catch (cause) {
+		fail(edit, cause);
+	}
+	for (const [target, targetEdits] of byTarget) {
+		let content;
+		try {
+			content = await readOptional(target);
+		} catch (cause) {
+			for (const edit of targetEdits) fail(edit, cause);
+			continue;
+		}
+		const matched = [];
+		for (const edit of targetEdits) {
+			const stale = (reason) => outcomes.set(edit.id, {
+				id: edit.id,
+				path: edit.path,
+				status: "stale",
+				reason
+			});
+			if (edit.oldText === void 0) {
+				if (content !== void 0) {
+					stale("file already exists");
+					continue;
+				}
+				content = edit.newText;
+			} else {
+				if (content === void 0) {
+					stale("file not found");
+					continue;
+				}
+				const count = occurrences(content, edit.oldText);
+				if (count !== 1) {
+					stale(count === 0 ? "target text not found" : `target text matches ${count} times`);
+					continue;
+				}
+				const index = content.indexOf(edit.oldText);
+				content = content.slice(0, index) + edit.newText + content.slice(index + edit.oldText.length);
+			}
+			matched.push(edit);
+		}
+		if (matched.length === 0) continue;
+		if (!options.check) try {
+			await mkdir(dirname(target), { recursive: true });
+			const writable = await resolveWorkflowWritePath(root, matched[0].path, options);
+			if (writable !== target) throw new Error(`Repository path changed while applying: ${matched[0].path}`);
+			await writeFile(writable, content, "utf8");
+		} catch (cause) {
+			for (const edit of matched) fail(edit, cause);
+			continue;
+		}
+		for (const edit of matched) outcomes.set(edit.id, {
+			id: edit.id,
+			path: edit.path,
+			status: options.check ? "applicable" : "applied"
+		});
+	}
+	return edits.map((edit) => outcomes.get(edit.id));
+};
+//#endregion
 //#region node_modules/effect/dist/http/HttpBody.js
 const TypeId$5 = "~effect/http/HttpBody";
 const HttpBodyErrorTypeId = "~effect/http/HttpBody/HttpBodyError";
@@ -28081,22 +28669,47 @@ const decodeResearchState = (spec, value, limit) => {
 	if (issues.length > 0) throw new Error(issues.join("\n"));
 	return decoded;
 };
-const ActionState = Struct({
-	summary: String$2,
-	files: ArraySchema(String$2),
-	outcome: Literals([
-		"applied",
-		"dry-run",
-		"no-change"
-	])
-});
-const decodeActionState = decodeUnknownSync(ActionState);
-const actionDocument = toJsonSchemaDocument(ActionState);
-const actionStateJsonSchema = {
-	...actionDocument.schema,
-	$defs: actionDocument.definitions
+/** Recover independently valid recommendations while retaining their original item indexes. */
+const salvageResearchState = (spec, value, limit) => {
+	const normalized = normalizeResearchState(value, limit);
+	if (normalized === null || typeof normalized !== "object" || Array.isArray(normalized)) throw new Error("Workflow result must contain a valid summary and an items or opportunities array.");
+	const record = normalized;
+	const key = Array.isArray(record["opportunities"]) ? "opportunities" : "items";
+	const items = record[key];
+	if (!Array.isArray(items)) throw new Error(`Workflow result requires an ${key} array.`);
+	const sourceItems = value[key];
+	const sourceIndexes = Array.isArray(sourceItems) ? sourceItems.flatMap((item, index) => item === null ? [] : [index]).slice(0, limit) : [];
+	decodeResearchState(spec, {
+		...record,
+		[key]: []
+	}, limit);
+	const valid = [];
+	const rejectedItems = [];
+	for (const [position, item] of items.entries()) {
+		const index = sourceIndexes[position] ?? position;
+		try {
+			decodeResearchState(spec, {
+				...record,
+				[key]: [item]
+			}, limit);
+			valid.push(item);
+		} catch (cause) {
+			rejectedItems.push({
+				index,
+				reason: cause instanceof Error ? cause.message : String(cause)
+			});
+		}
+	}
+	if (valid.length === 0) throw new Error(rejectedItems.map(({ index, reason }) => `${key}[${index}]: ${reason}`).join("\n") || "No valid workflow items were submitted.");
+	return {
+		state: decodeResearchState(spec, {
+			...record,
+			[key]: valid
+		}, limit),
+		rejectedItems
+	};
 };
 //#endregion
-export { decodeUnknownEffect as $, isNotUndefined as $i, tapErrorTag as $n, Error$2 as $r, catchDefect as $t, Defect as A, fromNullishOr as Ai, orDie as An, void_$1 as Ar, transduce as At, Natural as B, none as Bi, runPromise as Bn, LogToStderr as Br, offerUnsafe as Bt, ConfigProvider as C, empty$7 as Ci, logWarning as Cn, isDone as Cr, fromPull as Ct, BooleanLiterals as D, make$19 as Di, matchEffect as Dn, isFailure as Dr, run$1 as Dt, Boolean as E, getUnsafe as Ei, match as En, fail$4 as Er, mkString as Et, Int as F, isNone as Fi, provideService as Fn, findErrorOption as Fr, unwrap$1 as Ft, String$2 as G, assignProperty as Gi, serviceOption as Gn, onExitPrimitive as Gr, interrupt as Gt, Number$1 as H, Prototype as Hi, runSync$1 as Hn, callback$2 as Hr, take as Ht, Json as I, isOption as Ii, raceFirst as In, hasInterruptsOnly as Ir, endUnsafe as It, TaggedStruct as J, redact$1 as Ji, suspend$3 as Jn, suspend$4 as Jr, acquireUseRelease as Jt, Struct as K, BaseProto as Ki, sleep as Kn, succeed$4 as Kr, runIn as Kt, Literal as L, isSome as Li, result as Ln, pretty as Lr, failCauseUnsafe as Lt, Error$1 as M, getOrElse as Mi, promise as Mn, UnknownError as Mr, fromTransform as Mt, FalseLiterals as N, getOrNull as Ni, provide as Nn, done as Nr, mapDone as Nt, Class as O, exists as Oi, onExit$1 as On, isSuccess as Or, runCollect as Ot, Finite as P, getOrUndefined$1 as Pi, provideContext as Pn, fail$5 as Pr, toTransform as Pt, Unknown as Q, isNotNull as Qi, tapError as Qn, MinimumLogLevel as Qr, callback$1 as Qt, Literals as R, map$9 as Ri, runFork as Rn, squash as Rr, make$13 as Rt, option as S, add as Si, logInfo as Sn, doneUnsafe as Sr, fromChannel as St, ArraySchema as T, getOrUndefined as Ti, mapError as Tn, makeUnsafe$4 as Tr, merge$1 as Tt, Record as U, PipeInspectableProto as Ui, scope as Un, flatMap$1 as Ur, make$15 as Ut, NullOr as V, some as Vi, runPromiseExit as Vn, asSome as Vr, poll as Vt, Redacted$1 as W, withFiber$1 as Wi, scoped as Wn, getCurrentFiber as Wr, makeUnsafe$1 as Wt, Tuple as X, isBoolean as Xi, tap as Xn, uninterruptibleMask$1 as Xr, andThen as Xt, TrueLiterals as Y, hasProperty as Yi, sync as Yn, sync$1 as Yr, addFinalizer as Yt, Union as Z, isFunction as Zi, tapCause as Zn, void_$2 as Zr, as as Zt, prependUrl as _, reduce as _i, ignore as _n, addFinalizer$1 as _r, make$10 as _t, layer as a, constVoid as aa, millis as ai, context as an, void_ as ar, is as at, String$1 as b, Reference as bi, logDebug as bn, makeUnsafe$3 as br, decodeText as bt, mapRequest as c, identity as ca, toMillis as ci, ensuring$2 as cn, catchDone as cr, suspend as ct, acceptJson as d, findFirstIndex as di, fn as dn, mergeAll as dr, toCodecStringTree as dt, isNullish as ea, TaggedError$1 as ei, catchFilter as en, timeoutOption as er, decodeUnknownOption as et, bearerToken as f, findLast as fi, fnUntraced as fn, provide$2 as fr, toJsonSchemaDocument as ft, post as g, of as gi, gen as gn, Scope as gr, isRedacted as gt, get as h, match$3 as hi, forkScoped as hn, succeedContext as hr, withDecodingDefault as ht, normalizeResearchState as i, isUndefined as ia, isFinite$1 as ii, clockWith as in, uninterruptibleMask as ir, fromJsonString as it, Duration as j, fromUndefinedOr as ji, orElseSucceed as jn, Done as jr, unwrap as jt, DateTimeUtc as k, flatMap$2 as ki, option$1 as kn, succeed$3 as kr, splitLines as kt, retryTransient as l, pipe as la, empty$6 as li, fail$3 as ln, effect as lr, tag as lt, bodyJsonUnsafe as m, map$6 as mi, forever as mn, succeed$2 as mr, withConstructorDefault as mt, decodeActionState as n, isObject as na, format$1 as ni, catchTags as nn, try_ as nr, encodeEffect as nt, HttpClient as o, dual as oa, minutes as oi, contextWith as on, withFiber as or, optional as ot, bodyJson as p, isReadonlyArrayNonEmpty as pi, forEach as pn, provideMerge as pr, toTaggedUnion as pt, TaggedError as q, format$2 as qi, succeed$1 as qn, succeedNone as qr, acquireRelease as qt, decodeResearchState as r, isString as ra, fromInputUnsafe as ri, catch_ as rn, uninterruptible as rr, encodeSync as rt, filterStatusOk as s, flow as sa, seconds as si, effectify as sn, withSpan as sr, optionalKey as st, actionStateJsonSchema as t, isNumber as ta, taggedEnum as ti, catchTag as tn, tryPromise as tr, decodeUnknownSync as tt, schemaBodyJson as u, pipeArguments as ua, findFirst as ui, flatMap as un, merge$3 as ur, toCodecJson as ut, setHeaders as v, fail$7 as vi, interrupt$1 as vn, addFinalizerExit as vr, value as vt, fromEnv as w, get$1 as wi, map$3 as wn, isDoneUnsafe as wr, isStream as wt, all as x, Service as xi, logError as xn, _await as xr, empty$4 as xt, Redacted as y, succeed$5 as yi, isEffect as yn, close as yr, callback as yt, MutableJson as z, match$5 as zi, runForkWith as zn, ConsoleRef as zr, offer as zt };
+export { JsonObject as $, getOrUndefined$1 as $i, provideContext as $n, fail$5 as $r, toTransform as $t, writeResearchCheckpoint as A, findFirstIndex as Ai, fn as An, mergeAll as Ar, toCodecStringTree as At, fromEnv as B, Service as Bi, logError as Bn, _await as Br, empty$4 as Bt, readWorkflowEdits as C, isUndefined as Ca, isFinite$1 as Ci, clockWith as Cn, uninterruptibleMask as Cr, is as Ct, resolveWorkflowRepositoryRoot as D, identity as Da, toMillis as Di, ensuring$2 as Dn, catchDone as Dr, suspend as Dt, resolveRepositoryReadPath as E, flow as Ea, seconds as Ei, effectify as En, withSpan as Er, optionalKey as Et, Redacted as F, of as Fi, gen as Fn, Scope as Fr, isRedacted as Ft, DateTimeUtc as G, getUnsafe as Gi, match as Gn, fail$4 as Gr, mkString as Gt, Boolean as H, empty$7 as Hi, logWarning as Hn, isDone as Hr, fromPull as Ht, String$1 as I, reduce as Ii, ignore as In, addFinalizer$1 as Ir, make$10 as It, Error$1 as J, flatMap$2 as Ji, option$1 as Jn, succeed$3 as Jr, splitLines as Jt, Defect as K, make$19 as Ki, matchEffect as Kn, isFailure as Kr, run$1 as Kt, all as L, fail$7 as Li, interrupt$1 as Ln, addFinalizerExit as Lr, value as Lt, writeWorkflowFailure as M, isReadonlyArrayNonEmpty as Mi, forEach as Mn, provideMerge as Mr, toTaggedUnion as Mt, writeWorkflowProgress as N, map$6 as Ni, forever as Nn, succeed$2 as Nr, withConstructorDefault as Nt, createRunId as O, pipe as Oa, empty$6 as Oi, fail$3 as On, effect as Or, tag as Ot, TextTemplate as P, match$3 as Pi, forkScoped as Pn, succeedContext as Pr, withDecodingDefault as Pt, Json as Q, getOrNull as Qi, provide as Qn, done as Qr, mapDone as Qt, option as R, succeed$5 as Ri, isEffect as Rn, close as Rr, callback as Rt, normalizeEditPaths as S, isString as Sa, fromInputUnsafe as Si, catch_ as Sn, uninterruptible as Sr, fromJsonString as St, writeWorkflowEdits as T, dual as Ta, minutes as Ti, contextWith as Tn, withFiber as Tr, optional as Tt, BooleanLiterals as U, get$1 as Ui, map$3 as Un, isDoneUnsafe as Ur, isStream as Ut, ArraySchema as V, add as Vi, logInfo as Vn, doneUnsafe as Vr, fromChannel as Vt, Class as W, getOrUndefined as Wi, mapError as Wn, makeUnsafe$4 as Wr, merge$1 as Wt, Finite as X, fromUndefinedOr as Xi, orElseSucceed as Xn, Done as Xr, unwrap as Xt, FalseLiterals as Y, fromNullishOr as Yi, orDie as Yn, void_$1 as Yr, transduce as Yt, Int as Z, getOrElse as Zi, promise as Zn, UnknownError as Zr, fromTransform as Zt, prependUrl as _, isNotNull as _a, MinimumLogLevel as _i, callback$1 as _n, tapError as _r, decodeUnknownEffect as _t, layer as a, none as aa, LogToStderr as ai, offerUnsafe as an, runPromise as ar, NullOr as at, applyWorkflowEdits as b, isNumber as ba, taggedEnum as bi, catchTag as bn, tryPromise as br, encodeEffect as bt, mapRequest as c, PipeInspectableProto as ca, flatMap$1 as ci, make$15 as cn, scope as cr, Redacted$1 as ct, acceptJson as d, BaseProto as da, succeed$4 as di, runIn as dn, sleep as dr, TaggedError as dt, isNone as ea, findErrorOption as ei, unwrap$1 as en, provideService as er, Literal as et, bearerToken as f, format$2 as fa, succeedNone as fi, acquireRelease as fn, succeed$1 as fr, TaggedStruct as ft, post as g, isFunction as ga, void_$2 as gi, as as gn, tapCause as gr, Unknown as gt, get as h, isBoolean as ha, uninterruptibleMask$1 as hi, andThen as hn, tap as hr, Union as ht, salvageResearchState as i, match$5 as ia, ConsoleRef as ii, offer as in, runForkWith as ir, Null as it, writeRunBundle as j, findLast as ji, fnUntraced as jn, provide$2 as jr, toJsonSchemaDocument as jt, serializeCause as k, pipeArguments as ka, findFirst as ki, flatMap as kn, merge$3 as kr, toCodecJson as kt, retryTransient as l, withFiber$1 as la, getCurrentFiber as li, makeUnsafe$1 as ln, scoped as lr, String$2 as lt, bodyJsonUnsafe as m, hasProperty as ma, sync$1 as mi, addFinalizer as mn, sync as mr, Tuple as mt, dropNulls as n, isSome as na, pretty as ni, failCauseUnsafe as nn, result as nr, MutableJson as nt, HttpClient as o, some as oa, asSome as oi, poll as on, runPromiseExit as or, Number$1 as ot, bodyJson as p, redact$1 as pa, suspend$4 as pi, acquireUseRelease as pn, suspend$3 as pr, TrueLiterals as pt, Duration as q, exists as qi, onExit$1 as qn, isSuccess as qr, runCollect as qt, normalizeResearchState as r, map$9 as ra, squash as ri, make$13 as rn, runFork as rr, Natural as rt, filterStatusOk as s, Prototype as sa, callback$2 as si, take as sn, runSync$1 as sr, Record as st, decodeResearchState as t, isOption as ta, hasInterruptsOnly as ti, endUnsafe as tn, raceFirst as tr, Literals as tt, schemaBodyJson as u, assignProperty as ua, onExitPrimitive as ui, interrupt as un, serviceOption as ur, Struct as ut, setHeaders as v, isNotUndefined as va, Error$2 as vi, catchDefect as vn, tapErrorTag as vr, decodeUnknownOption as vt, workflowEditsArtifact as w, constVoid as wa, millis as wi, context as wn, void_ as wr, mutable as wt, decodeActionState as x, isObject as xa, format$1 as xi, catchTags as xn, try_ as xr, encodeSync as xt, actionStateJsonSchema as y, isNullish as ya, TaggedError$1 as yi, catchFilter as yn, timeoutOption as yr, decodeUnknownSync as yt, ConfigProvider as z, Reference as zi, logDebug as zn, makeUnsafe$3 as zr, decodeText as zt };
 
-//# sourceMappingURL=state-BuJP_3Lr.js.map
+//# sourceMappingURL=state-2ikjo7uI.js.map