pagegraph 0.8.3 → 0.8.4

package/README.md

@@ -229,6 +229,8 @@ export default defineSeoConfig({
     opencode: {
       configDirectory: ".pagegraph/opencode",
       defaultModel: "openrouter/example/model",
+      // Optional per-completion budget in milliseconds; default 180000.
+      timeoutMs: 360_000,
       models: {
         "research.keywords": "openrouter/example/research-model",
       },
@@ -254,9 +256,23 @@ pagegraph research keywords \
 ```
 
 Every workflow starts from the selected graph and context files, asks the SEO agent to search
-Executor's live catalog and compose suitable tools, then evaluates its structured observations with
-Jev. Tool paths are discovered at runtime; the generated skills contain editable starter recipes,
-not a fixed integration list.
+Executor's live catalog and inspect the discovered tools' argument schemas, then evaluates its
+structured observations with Jev. Tool paths are discovered at runtime; the generated skills contain
+editable starter recipes, not a fixed integration list.
+
+`workflows.opencode.timeoutMs` sets the positive integer deadline in milliseconds for each OpenCode
+completion (maximum `2147483647`). It covers prompt admission, model execution, and any workflow JSON
+repair prompt. A later action or continuation turn gets a separate budget. The default is `180000`.
+
+Selecting pages preserves their incoming and outgoing relationships to non-selected pages in
+`evidence.neighborhood`. Those neighbors supply architecture context without becoming workflow
+targets or consuming `--limit`. The agent receives the limit before research, and PageGraph also caps
+the decoded result before decisions.
+
+After research is validated, the run directory contains `research.json`: an incomplete checkpoint
+with the collected evidence, decision inputs, and OpenCode transcript. A downstream failure reports
+its path so the evidence remains available for diagnosis. Only a completed workflow writes
+`run.json` and `summary.md`; a research checkpoint is not a final recommendation.
 
 | Command | Result |
 | --- | --- |

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import * as NFS from "node:fs";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import * as NodeChildProcess from "node:child_process";
 import { execFileSync, spawn } from "node:child_process";
 import { PassThrough } from "node:stream";
@@ -9,7 +9,7 @@ import { createHash, randomUUID } from "node:crypto";
 import * as OS from "node:os";
 import { tmpdir } from "node:os";
 import * as Path from "node:path";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import * as NodeUrl from "node:url";
 import { pathToFileURL } from "node:url";
 import * as readline from "node:readline";
@@ -35710,7 +35710,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.8.3";
+var version = "0.8.4";
 //#endregion
 //#region src/core/projections.ts
 const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
@@ -36166,12 +36166,13 @@ const findConfigFile = (from) => {
 const isStringArray = (value) => Array.isArray(value) && value.every(isString);
 const isCoverageRules = (value) => Array.isArray(value) && value.every((rule) => isObject$1(rule) && isString(rule["path"]) && Number.isSafeInteger(rule["minInbound"]) && rule["minInbound"] > 0);
 const isStringRecord = (value) => isObject$1(value) && Object.values(value).every(isString);
+const isWorkflowTimeout = (value) => Number.isSafeInteger(value) && value > 0 && value <= 2147483647;
 const isStringArrayRecord = (value) => isObject$1(value) && Object.values(value).every(isStringArray);
 const isWorkflowConfig = (value) => {
 	if (!isObject$1(value) || !isObject$1(value["opencode"])) return false;
 	const opencode = value["opencode"];
 	const context = value["context"];
-	return isString(opencode["configDirectory"]) && isString(opencode["defaultModel"]) && (opencode["models"] === void 0 || isStringRecord(opencode["models"])) && (context === void 0 || isObject$1(context) && (context["files"] === void 0 || isStringArray(context["files"])) && (context["byWorkflow"] === void 0 || isStringArrayRecord(context["byWorkflow"]))) && (value["runsDirectory"] === void 0 || isString(value["runsDirectory"]));
+	return isString(opencode["configDirectory"]) && isString(opencode["defaultModel"]) && (opencode["models"] === void 0 || isStringRecord(opencode["models"])) && (opencode["timeoutMs"] === void 0 || isWorkflowTimeout(opencode["timeoutMs"])) && (context === void 0 || isObject$1(context) && (context["files"] === void 0 || isStringArray(context["files"])) && (context["byWorkflow"] === void 0 || isStringArrayRecord(context["byWorkflow"]))) && (value["runsDirectory"] === void 0 || isString(value["runsDirectory"]));
 };
 /**
 * `seo.config.ts` is the consumer's file and may be plain JS, so its types are
@@ -42084,6 +42085,13 @@ const writeRunBundle = (root, runsDirectory, 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");
+	writeFileSync(path, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+	return path;
+};
 //#endregion
 //#region node_modules/effect/dist/unstable/ai/Decision.js
 /**
@@ -43281,6 +43289,30 @@ const selectGraph = (graph, options) => {
 		collisions: graph.collisions
 	};
 };
+const selectNeighborhood = (graph, targetPaths) => {
+	const inbound = [];
+	const outbound = [];
+	for (const edge of graph.edges) {
+		if (targetPaths.has(edge.to) && !targetPaths.has(edge.from)) {
+			const node = graph.nodes.get(edge.from);
+			if (node !== void 0) inbound.push({
+				edge,
+				node: serializeNode(node)
+			});
+		}
+		if (targetPaths.has(edge.from) && !targetPaths.has(edge.to)) {
+			const node = graph.nodes.get(edge.to);
+			if (node !== void 0) outbound.push({
+				edge,
+				node: serializeNode(node)
+			});
+		}
+	}
+	return {
+		inbound,
+		outbound
+	};
+};
 const collectContextFiles = (root, workflow, context) => {
 	const paths = [...context?.files ?? [], ...context?.byWorkflow?.[workflow] ?? []];
 	return [...new Set(paths)].map((path) => ({
@@ -43288,14 +43320,18 @@ const collectContextFiles = (root, workflow, context) => {
 		content: readFileSync(resolve(root, path), "utf8")
 	}));
 };
-const collectWorkflowEvidence = (graph, options, root, workflow, context) => ({
-	graph: serializeGraph(selectGraph(graph, options)),
-	sources: collectContextFiles(root, workflow, context)
-});
+const collectWorkflowEvidence = (graph, options, root, workflow, context) => {
+	const selected = selectGraph(graph, options);
+	return {
+		graph: serializeGraph(selected),
+		neighborhood: selectNeighborhood(graph, new Set(selected.nodes.keys())),
+		sources: collectContextFiles(root, workflow, context)
+	};
+};
 //#endregion
 //#region src/workflows/git.ts
-const run$1 = (root, args) => execFileSync("git", args, {
-	cwd: root,
+const run$1 = (cwd, args) => execFileSync("git", args, {
+	cwd,
 	encoding: "utf8",
 	stdio: [
 		"ignore",
@@ -43304,38 +43340,36 @@ const run$1 = (root, args) => execFileSync("git", args, {
 	]
 }).trim();
 const nul = (value) => value.split("\0").filter((item) => item.length > 0);
-const fingerprint = (root, path) => {
+const fingerprint = (root, gitRoot, path) => {
 	const absolute = resolve(root, path);
-	const content = existsSync(absolute) ? readFileSync(absolute) : Buffer.from("<deleted>");
-	const status = run$1(root, [
+	const gitPath = relative(gitRoot, absolute);
+	const status = run$1(gitRoot, [
 		"status",
 		"--short",
 		"--",
-		path
+		gitPath
 	]);
+	let content;
+	if (!existsSync(absolute)) content = Buffer.from("<deleted>");
+	else if (statSync(absolute).isDirectory()) {
+		const stage = run$1(gitRoot, [
+			"ls-files",
+			"--stage",
+			"--",
+			gitPath
+		]);
+		if (stage.split(/\s+/, 1)[0] !== "160000") throw new Error(`Cannot fingerprint directory reported as a Git file: ${path}`);
+		const submoduleRoot = realpathSync(run$1(absolute, ["rev-parse", "--show-toplevel"]));
+		if (submoduleRoot !== realpathSync(absolute)) throw new Error(`Git submodule is unavailable: ${path}`);
+		content = Buffer.from(`gitlink:${stage}\0${JSON.stringify(inspectGit(submoduleRoot))}`);
+	} else content = readFileSync(absolute);
 	return createHash("sha256").update(status).update("\0").update(content).digest("hex");
 };
 const inspectGit = (root) => {
+	const absoluteRoot = realpathSync(root);
+	let gitTopLevel;
 	try {
-		const tracked = nul(run$1(root, [
-			"diff",
-			"--name-only",
-			"-z",
-			"HEAD"
-		]));
-		const untracked = nul(run$1(root, [
-			"ls-files",
-			"--others",
-			"--exclude-standard",
-			"-z"
-		]));
-		const files = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].sort();
-		return {
-			head: run$1(root, ["rev-parse", "HEAD"]),
-			dirty: files.length > 0,
-			files,
-			fingerprints: Object.fromEntries(files.map((path) => [path, fingerprint(root, path)]))
-		};
+		gitTopLevel = run$1(absoluteRoot, ["rev-parse", "--show-toplevel"]);
 	} catch {
 		return {
 			dirty: false,
@@ -43343,6 +43377,27 @@ const inspectGit = (root) => {
 			fingerprints: {}
 		};
 	}
+	const gitRoot = realpathSync(gitTopLevel);
+	const tracked = nul(run$1(gitRoot, [
+		"diff",
+		"--name-only",
+		"-z",
+		"HEAD"
+	]));
+	const untracked = nul(run$1(gitRoot, [
+		"ls-files",
+		"--others",
+		"--exclude-standard",
+		"--full-name",
+		"-z"
+	]));
+	const files = [.../* @__PURE__ */ new Set([...tracked, ...untracked])].map((path) => relative(absoluteRoot, resolve(gitRoot, path))).sort();
+	return {
+		head: run$1(gitRoot, ["rev-parse", "HEAD"]),
+		dirty: files.length > 0,
+		files,
+		fingerprints: Object.fromEntries(files.map((path) => [path, fingerprint(absoluteRoot, gitRoot, path)]))
+	};
 };
 const changedFiles = (before, after) => [.../* @__PURE__ */ new Set([...before.files, ...after.files])].filter((path) => before.fingerprints[path] !== after.fingerprints[path]).sort();
 //#endregion
@@ -43478,9 +43533,20 @@ const decodeToolPart = decodeUnknownOption(Struct({
 	state: Struct({
 		status: String$6,
 		input: optionalKey(Unknown),
-		content: optionalKey(Unknown)
+		content: optionalKey(Unknown),
+		error: optionalKey(Unknown),
+		metadata: optionalKey(Unknown)
 	})
 }));
+const decodeCodeModeMetadata = decodeUnknownOption(Struct({ toolCalls: ArraySchema(Struct({
+	tool: String$6,
+	status: Literals$2([
+		"running",
+		"completed",
+		"error"
+	]),
+	input: optionalKey(Unknown)
+})) }));
 const toolParts = (transcript) => decodeTranscript(transcript).messages.flatMap((message) => {
 	const assistant = decodeAssistantMessage(message);
 	if (isNone(assistant)) return [];
@@ -43489,15 +43555,6 @@ const toolParts = (transcript) => decodeTranscript(transcript).messages.flatMap(
 		return isSome(decoded) ? [decoded.value] : [];
 	});
 });
-const toolText = (value) => {
-	if (typeof value === "string") return value;
-	if (Array.isArray(value)) return value.map(toolText).join("\n");
-	if (value === null || typeof value !== "object") return "";
-	const record = value;
-	if (record["type"] === "text" && typeof record["text"] === "string") return record["text"];
-	return Object.values(record).map(toolText).join("\n");
-};
-const pathsIn = (value) => [...toolText(value).matchAll(/tools\.([A-Za-z0-9_.-]+)/g)].map((match) => match[1] ?? "").filter(Boolean);
 const toolPathPattern = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+$/;
 const pathsInSearchOutput = (value) => {
 	const found = /* @__PURE__ */ new Set();
@@ -43526,27 +43583,50 @@ const pathsInSearchOutput = (value) => {
 const evidenceRecord = (part) => ({
 	tool: part.name,
 	input: part.state.input ?? null,
-	output: part.state.content ?? null
+	output: part.state.content ?? part.state.error ?? null
 });
 const collectExecutorEvidence = (transcript) => {
 	const discovered = /* @__PURE__ */ new Set();
 	const searches = [];
 	const calls = [];
 	for (const part of toolParts(transcript)) {
-		const inputPaths = pathsIn(part.state.input);
-		const inputText = toolText(part.state.input);
-		if (part.name === "executor_search" || part.name === "executor.search" || inputPaths.some((path) => path === "executor.search")) {
+		const metadata = decodeCodeModeMetadata(part.state.metadata);
+		if (isSome(metadata)) {
+			const invocations = metadata.value.toolCalls;
+			for (const invocation of invocations) {
+				if (invocation.status !== "completed") continue;
+				const record = codeModeEvidenceRecord(invocation, part.state.content);
+				if (invocation.tool === "executor.search") {
+					for (const path of pathsInSearchOutput(part.state.content)) if (path !== "executor.search") discovered.add(path);
+					searches.push(record);
+					continue;
+				}
+				if ([...discovered].some((path) => matchesToolPath(invocation.tool, path))) calls.push(record);
+			}
+			continue;
+		}
+		if (part.state.status === "completed" && (part.name === "executor_search" || part.name === "executor.search")) {
 			for (const path of pathsInSearchOutput(part.state.content)) if (path !== "executor.search") discovered.add(path);
 			searches.push(evidenceRecord(part));
 			continue;
 		}
-		if ([...discovered].some((path) => part.name === path || part.name === path.replaceAll(".", "_") || inputPaths.includes(path) || inputText.includes(path))) calls.push(evidenceRecord(part));
+		if (part.state.status === "completed" && [...discovered].some((path) => matchesToolPath(part.name, path))) calls.push(evidenceRecord(part));
 	}
 	return {
 		searches,
 		calls
 	};
 };
+const codeModeEvidenceRecord = (invocation, codeModeOutput) => ({
+	tool: invocation.tool,
+	input: invocation.input ?? null,
+	output: {
+		status: invocation.status,
+		scope: "shared CodeMode execution result",
+		content: codeModeOutput ?? null
+	}
+});
+const matchesToolPath = (tool, path) => tool === path || tool === path.replaceAll(".", "_");
 const interactionEventError = (event, sessionId) => {
 	if (event === null || typeof event !== "object") return void 0;
 	const record = event;
@@ -43559,15 +43639,61 @@ const interactionEventError = (event, sessionId) => {
 		if (form !== null && typeof form === "object" && form["sessionID"] === sessionId) return /* @__PURE__ */ new Error("OpenCode requested a form; embedded PageGraph workflows are noninteractive.");
 	}
 };
+const recordWorkflowActivity = (activity, event) => {
+	if (event.type === "log.synced") return;
+	activity.lastActivity = {
+		type: event.type,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		seq: event.durable.seq
+	};
+	if (event.type === "session.step.started") {
+		activity.modelSteps += 1;
+		activity.lastModel = `${event.data.model.providerID}/${event.data.model.id}`;
+		return;
+	}
+	if (event.type === "session.tool.input.started") {
+		activity.toolNames.set(event.data.id, event.data.name);
+		activity.lastTool = {
+			id: event.data.id,
+			name: event.data.name,
+			status: "input"
+		};
+		return;
+	}
+	if (event.type === "session.tool.called") {
+		activity.lastTool = {
+			id: event.data.id,
+			name: activity.toolNames.get(event.data.id) ?? event.data.id,
+			status: "called"
+		};
+		return;
+	}
+	if (event.type === "session.tool.success" || event.type === "session.tool.failed") {
+		activity.completedTools += 1;
+		activity.lastTool = {
+			id: event.data.id,
+			name: activity.toolNames.get(event.data.id) ?? event.data.id,
+			status: event.type === "session.tool.success" ? "succeeded" : "failed"
+		};
+	}
+};
+const describeWorkflowActivity = (activity, stage) => {
+	const lastActivity = activity.lastActivity ? `${activity.lastActivity.type} at ${activity.lastActivity.at}${activity.lastActivity.seq === void 0 ? "" : ` (seq ${activity.lastActivity.seq})`}` : `none observed during ${stage}`;
+	const lastTool = activity.lastTool ? `; last tool ${activity.lastTool.name} (${activity.lastTool.id}, ${activity.lastTool.status})` : "";
+	const model = activity.lastModel ? `; last model ${activity.lastModel}` : "";
+	return `Model steps: ${activity.modelSteps}; completed tools: ${activity.completedTools}; last activity: ${lastActivity}${model}${lastTool}.`;
+};
 const waitForIdle = async (host, sessionId, options) => {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+	const controller = options.signal === void 0 ? new AbortController() : void 0;
+	const signal = options.signal ?? controller.signal;
+	const timer = controller === void 0 ? void 0 : setTimeout(() => controller.abort(), options.timeoutMs);
 	try {
 		for await (const event of host.sessions.log({
 			sessionID: sessionId,
 			follow: true,
 			after: options.after
-		}, { signal: controller.signal })) {
+		}, { signal })) {
+			if (options.activity !== void 0) recordWorkflowActivity(options.activity, event);
 			const interactionError = interactionEventError(event, sessionId);
 			if (interactionError !== void 0) throw interactionError;
 			if (event.type === "session.execution.succeeded" && event.data.sessionID === sessionId) return event.durable.seq;
@@ -43575,13 +43701,44 @@ const waitForIdle = async (host, sessionId, options) => {
 			if (event.type === "session.execution.interrupted" && event.data.sessionID === sessionId) throw new Error(`OpenCode session was interrupted: ${event.data.reason}.`);
 		}
 	} catch (cause) {
-		if (controller.signal.aborted) throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs ?? options.timeoutMs}ms.`, { cause });
+		if (controller?.signal.aborted) throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs ?? options.timeoutMs}ms.`, { cause });
 		throw cause;
 	} finally {
-		clearTimeout(timer);
+		if (timer !== void 0) clearTimeout(timer);
 	}
 	throw new Error("OpenCode session log ended before the SEO agent completed.");
 };
+const runWorkflowTurn = async (host, sessionId, prompt, options) => {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+	let stage = options.stage;
+	try {
+		await host.sessions.prompt({
+			sessionID: sessionId,
+			text: prompt,
+			...options.skills === void 0 ? {} : { skills: options.skills.map((id) => ({ id })) }
+		}, { signal: controller.signal });
+		if (stage === "prompt admission") stage = "model execution";
+		return await waitForIdle(host, sessionId, {
+			timeoutMs: options.timeoutMs,
+			configuredTimeoutMs: options.configuredTimeoutMs,
+			after: options.after,
+			signal: controller.signal,
+			activity: options.activity
+		});
+	} catch (cause) {
+		if (!controller.signal.aborted) throw cause;
+		let interruption = "unknown";
+		try {
+			interruption = (await host.sessions.interrupt({ sessionID: sessionId }, { signal: AbortSignal.timeout(5e3) })).interrupted ? "active execution interrupted" : "no active execution to interrupt";
+		} catch (interruptCause) {
+			interruption = `interrupt request failed: ${interruptCause instanceof Error ? interruptCause.message : String(interruptCause)}`;
+		}
+		throw new Error(`OpenCode session did not complete within ${options.configuredTimeoutMs}ms during ${stage}; ${describeWorkflowActivity(options.activity, stage)} Timeout handling: ${interruption}.`, { cause });
+	} finally {
+		clearTimeout(timer);
+	}
+};
 const acquireWorkflowHost = async (options) => {
 	const model = parseModel(options.model ?? options.config.defaultModel);
 	const configDirectory = resolve(options.root, options.config.configDirectory);
@@ -43603,18 +43760,21 @@ const acquireWorkflowHost = async (options) => {
 				sessionID: sessionId,
 				permissions: [...workflowOptions.permissions]
 			});
-			const configuredTimeoutMs = options.timeoutMs ?? 18e4;
+			const configuredTimeoutMs = options.timeoutMs ?? options.config.timeoutMs ?? 18e4;
 			const deadline = Date.now() + configuredTimeoutMs;
 			const remaining = () => Math.max(0, deadline - Date.now());
-			await host.sessions.prompt({
-				sessionID: sessionId,
-				text: prompt,
-				skills: workflowOptions.skills.map((id) => ({ id }))
-			});
-			let cursor = await waitForIdle(host, sessionId, {
+			const activity = {
+				modelSteps: 0,
+				completedTools: 0,
+				toolNames: /* @__PURE__ */ new Map()
+			};
+			let cursor = await runWorkflowTurn(host, sessionId, prompt, {
 				timeoutMs: remaining(),
 				configuredTimeoutMs,
-				after: cursors.get(sessionId)
+				stage: "prompt admission",
+				after: cursors.get(sessionId),
+				skills: workflowOptions.skills,
+				activity
 			});
 			cursors.set(sessionId, cursor);
 			let transcript = await host.sessions.export({
@@ -43632,14 +43792,12 @@ const acquireWorkflowHost = async (options) => {
 					}]
 				});
 				try {
-					await host.sessions.prompt({
-						sessionID: sessionId,
-						text: STATE_REPAIR_PROMPT
-					});
-					cursor = await waitForIdle(host, sessionId, {
+					cursor = await runWorkflowTurn(host, sessionId, STATE_REPAIR_PROMPT, {
 						timeoutMs: remaining(),
 						configuredTimeoutMs,
-						after: cursor
+						stage: "workflow state repair",
+						after: cursor,
+						activity
 					});
 					cursors.set(sessionId, cursor);
 					transcript = await host.sessions.export({
@@ -43691,7 +43849,7 @@ const acquireWorkflowHost = async (options) => {
 var action_default = "Continue PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nObserved state:\n{{state}}\n\nJev decisions:\n{{decisions}}\n\nApply only records in the resolved set whose verdict calls for a change. Never apply review records;\nleave them in the artifact for a human. If nothing is safely resolved, return no-change.\n\nRepository mutation mode: {{mutationMode}}. {{mutationInstruction}}\n\nReturn only one JSON object with this shape:\n{\"summary\":\"...\",\"files\":[\"relative/path\"],\"outcome\":\"applied|dry-run|no-change\"}\n";
 //#endregion
 //#region src/workflows/prompts/research.md
-var research_default = "You are running PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nUse these skills: {{skills}}. Treat the supplied project evidence as the deterministic baseline.\nSearch Executor's live catalog in one Code Mode turn, then call at least one exact returned tool\npath in a later turn. Compose whichever current integrations best support this workflow. Do not\nassume fixed provider or tool names. Preserve source references in the structured state.\n\nReturn only one JSON object matching this JSON Schema:\n{{stateSchema}}\n\nMarket: {{market}}\nLanguage: {{language}}\nDevice: {{device}}\nRefresh requested: {{refresh}}\nDo not ask questions, request permissions, or create interactive forms. Fail clearly if required\ninput is missing.\nSeed queries: {{queries}}\nCompetitor seeds: {{competitors}}\nAuthority-domain seeds: {{domains}}\nDeterministic evidence:\n{{evidence}}\n";
+var research_default = "You are running PageGraph's {{workflow}} workflow.\n\n{{instructions}}\n\nUse these skills: {{skills}}. Treat the supplied project evidence as the deterministic baseline.\nThe graph contains the selected target pages. Its neighborhood preserves incoming and outgoing\nrelationships to pages outside that selection; those neighbors are context, not additional targets.\nReturn at most {{limit}} items or opportunities. Keep exploration scoped to these targets and stop\nwhen the collected evidence supports the requested decision; do not expand into a site-wide audit.\n\nSearch Executor's live catalog with a short intent phrase, then use Code Mode's local `search` for\nthe exact returned path to inspect its current argument signature before calling it in a later turn.\nCatalog discovery returns tool names and descriptions, not complete input schemas. Never guess\narguments from a description. If discovery returns no matches, simplify the query. Compose whichever\ncurrent integrations best support this workflow; tool names and providers are discovered dynamically.\nCall at least one relevant discovered tool and preserve source references and provider errors in the\nstructured state. Do not treat an errored call or empty dataset as proof of indexing or traffic.\nDistinguish project market settings from the country, language, device, and date filters actually\napplied to provider data; report only the segments supported by the call and its response.\n\nReturn only one JSON object matching this JSON Schema:\n{{stateSchema}}\n\nMarket: {{market}}\nLanguage: {{language}}\nDevice: {{device}}\nRefresh requested: {{refresh}}\nDo not ask questions, request permissions, or create interactive forms. Fail clearly if required\ninput is missing.\nSeed queries: {{queries}}\nCompetitor seeds: {{competitors}}\nAuthority-domain seeds: {{domains}}\nDeterministic evidence:\n{{evidence}}\n";
 //#endregion
 //#region src/workflows/run.ts
 const defaultDecide = async (inputs, spec) => {
@@ -43720,6 +43878,7 @@ const capState = (state, limit) => {
 };
 const researchPrompt = (spec, evidence, options) => TextTemplate.from(research_default).values({
 	workflow: spec.id,
+	limit: options.limit,
 	instructions: spec.researchInstructions,
 	skills: spec.skills.join(", "),
 	stateSchema: JSON.stringify(spec.stateJsonSchema),
@@ -43782,54 +43941,88 @@ const runWorkflow = async (input, dependencies = {}) => {
 			const error = spec.validateDecisionInput(item);
 			if (error !== void 0) throw new Error(error);
 		}
-		const decisionReport = await (dependencies.decide ?? defaultDecide)(decisionInputs, spec);
-		const acted = spec.mutatesFiles ? await host.continue(researched.sessionId, actionPrompt(spec, state, decisionReport, mutation), {
-			skills: spec.skills,
-			permissions: actionPermissions
-		}) : researched;
-		const gitAfter = inspectGit(input.root);
-		const files = changedFiles(gitAtStart, gitAfter);
-		if ((!spec.mutatesFiles || input.options.dryRun) && files.length > 0) throw new Error(`${spec.id} changed repository files while running in read-only mode: ${files.join(", ")}`);
-		const run = {
-			kind: "pagegraph-workflow-run",
+		const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
+		const checkpoint = {
+			kind: "pagegraph-workflow-research-checkpoint",
 			schemaVersion: 1,
 			id,
 			workflow: spec.id,
 			startedAt: started.toISOString(),
-			finishedAt: now().toISOString(),
+			checkpointedAt: now().toISOString(),
 			project: {
 				root: input.root,
 				head: gitAtStart.head,
-				dirtyAtStart: gitAtStart.dirty
+				dirtyAtStart: gitAtStart.dirty,
+				filesAtStart: gitAtStart.files
 			},
 			options: input.options,
-			model: host.model,
-			targets: {
-				pages: evidence.graph.nodes.map((node) => node.path),
-				queries: input.options.queries,
-				kinds: input.options.kinds
-			},
 			evidence: {
 				...evidence,
-				executor: acted.executor
-			},
-			decisions: [decisionArtifact(spec, decisionInputs, decisionReport)],
-			changes: {
-				files,
-				providerCalls: acted.executor.calls.map((call) => call.tool)
+				executor: researched.executor
 			},
-			result: spec.mutatesFiles ? acted.state : state,
+			state,
+			decisionInputs,
 			opencode: {
 				agent: "seo",
-				sessionId: acted.sessionId,
-				transcript: acted.transcript
+				sessionId: researched.sessionId,
+				model: host.model,
+				transcript: researched.transcript
 			}
 		};
-		const runsDirectory = input.out ?? workflows.runsDirectory ?? ".pagegraph/runs";
-		return {
-			run,
-			directory: writeRunBundle(input.root, runsDirectory, run)
-		};
+		const checkpointPath = writeResearchCheckpoint(input.root, runsDirectory, checkpoint);
+		const gitAtCheckpoint = inspectGit(input.root);
+		try {
+			const decisionReport = await (dependencies.decide ?? defaultDecide)(decisionInputs, spec);
+			const acted = spec.mutatesFiles ? await host.continue(researched.sessionId, actionPrompt(spec, state, decisionReport, mutation), {
+				skills: spec.skills,
+				permissions: actionPermissions
+			}) : researched;
+			const gitAfter = inspectGit(input.root);
+			const files = changedFiles(gitAtCheckpoint, gitAfter);
+			if ((!spec.mutatesFiles || input.options.dryRun) && files.length > 0) throw new Error(`${spec.id} changed repository files while running in read-only mode: ${files.join(", ")}`);
+			const run = {
+				kind: "pagegraph-workflow-run",
+				schemaVersion: 1,
+				id,
+				workflow: spec.id,
+				startedAt: started.toISOString(),
+				finishedAt: now().toISOString(),
+				project: {
+					root: input.root,
+					head: gitAtStart.head,
+					dirtyAtStart: gitAtStart.dirty
+				},
+				options: input.options,
+				model: host.model,
+				targets: {
+					pages: evidence.graph.nodes.map((node) => node.path),
+					queries: input.options.queries,
+					kinds: input.options.kinds
+				},
+				evidence: {
+					...evidence,
+					executor: acted.executor
+				},
+				decisions: [decisionArtifact(spec, decisionInputs, decisionReport)],
+				changes: {
+					files,
+					providerCalls: acted.executor.calls.map((call) => call.tool)
+				},
+				result: spec.mutatesFiles ? acted.state : state,
+				opencode: {
+					agent: "seo",
+					sessionId: acted.sessionId,
+					transcript: acted.transcript
+				}
+			};
+			return {
+				run,
+				directory: writeRunBundle(input.root, runsDirectory, run)
+			};
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new Error(`${message}\nResearch checkpoint: ${checkpointPath}`, { cause });
+		}
 	} finally {
 		await host.close();
 	}
@@ -44361,7 +44554,7 @@ var executor_default$1 = "# Executor Starters for SERP Analysis\n\nThese snippet
 var SKILL_default = "---\nname: site-architecture\ndescription: Plan clear route ownership, hierarchy, collections, and contextual navigation.\n---\n\n# Site Architecture\n\nUse PageGraph's deterministic route nodes and edges as the primary model. Read\n[Executor Starters](references/executor.md) when owned search or crawl evidence can resolve an\nownership or discoverability question.\n\nAssign one clear intent owner, identify useful collections and parent-child relationships, and\nprefer consolidation when multiple pages compete for the same need. Propose new routes only when a\ndistinct supported intent lacks an adequate owner. Treat URL changes as consequential and preserve\nredirect and canonical requirements in the recommendation.\n\nReturn the structured state requested by the workflow. This planning workflow does not move routes,\nedit navigation, or submit sitemaps.\n";
 //#endregion
 //#region src/cli/preset/opencode/skills/site-architecture/references/executor.md
-var executor_default = "# Executor Starters for Site Architecture\n\nThese snippets are starting points, not an inventory. Discover owned page/query, crawl, sitemap,\nand URL evidence only when the deterministic graph does not answer the question.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Google Search Console page query canonical indexing\", limit: 8 }),\n  tools.executor.search({ query: \"Bing Webmaster crawl sitemap URL information\", limit: 8 }),\n]);\n~~~\n\nIn a later turn:\n\n~~~ts\nconst pages = (await search({ query: \"tools.<exact-owned-pages-path>\", limit: 1 })).items[0];\nreturn pages.path.split(\".\").reduce((node, segment) => node[segment], tools)({\n  siteUrl,\n  startDate,\n  endDate,\n  dimensions: [\"PAGE\", \"QUERY\"],\n});\n~~~\n\nKeep submitted, crawled, indexed, ranking, and clicked evidence distinct. Record reporting dates,\nfilters, canonical state, task status, errors, and cost. Do not request indexing, submit sitemaps,\nor update provider projects.\n";
+var executor_default = "# Executor Starters for Site Architecture\n\nThese snippets are starting points, not an inventory. Discover owned page/query, crawl, sitemap,\nand URL evidence only when the deterministic graph does not answer the question.\n\n~~~ts\nreturn Promise.all([\n  tools.executor.search({ query: \"Search Console page performance\", limit: 8 }),\n  tools.executor.search({ query: \"Bing Webmaster crawl\", limit: 8 }),\n]);\n~~~\n\nInspect a selected tool's signature before executing it. This is Code Mode's local schema lookup;\nit does not call the provider:\n\n~~~ts\nreturn await search({ query: \"tools.<exact-path-returned-by-executor>\", limit: 1 });\n~~~\n\nIn a later turn, call that exact path with the required fields from its returned signature. Property,\nproject, URL, date, and dimension arguments differ between integrations. Do not copy guessed fields\nfrom a recipe. Prefer page/query performance for demand and ownership questions; use URL inspection\nwhen the question actually concerns crawl, canonical, or indexing state.\n\nKeep submitted, crawled, indexed, ranking, and clicked evidence distinct. Record reporting dates,\nfilters, canonical state, task status, errors, and cost. Do not request indexing, submit sitemaps,\nor update provider projects.\n";
 //#endregion
 //#region src/cli/preset/opencode/preset.ts
 const skill = (name, definition, executor) => ({