@krapht/ork 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/{src-BxUJPGa5.mjs → src-cmmXKHn1.mjs}

@@ -1,6 +1,6 @@
-import { $n as timeoutMs, $t as parseTemplate, At as runScope, F as declaredProblem, Jn as beforeOf, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Qt as evaluate, Vn as markValue, Xn as isToolNode, Zn as programsRunBy, en as renderTemplate, er as INTEGRATIONS, ft as sessionDriver, jt as calledWorkflows, mt as reportSchemaFor, nr as integrationFor, s as planReason, tr as TOOL_PREFIX, ut as planNodeSession } from "./src-hrj2h0IZ.mjs";
+import { Bt as mcpNotText, Ft as declaredOutputOf, Hn as beforeOf, Mt as calledWorkflows, Nt as envReadsOf, Un as programsRunBy, Vt as serversIn, ar as timeoutMs, cr as integrationFor, ct as planNodeSession, en as evaluate, er as isClaudeNode, ft as reportSchemaFor, jt as declaredProblem, kt as runScope, nn as renderTemplate, or as INTEGRATIONS, qn as markValue, s as planReason, sr as TOOL_PREFIX, tn as parseTemplate, tr as isToolNode, ut as sessionDriver, yt as heldTimeout, zt as MCP_FILE } from "./src-Df6KOIDC.mjs";
 import path from "node:path";
-import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -35,7 +35,7 @@ const callExecutor = (context) => {
 		output: { status: "fail" },
 		error: "This run cannot call workflows."
 	});
-	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const scope = runScope(context.inputs, context.outputs, context.runId, context.item);
 	const render = (text) => {
 		const template = parseTemplate(text);
 		return template.ok ? renderTemplate(template.parts, scope) : text;
@@ -61,6 +61,32 @@ const callExecutor = (context) => {
 		}
 	}, context.signal).then(limitedCall);
 };
+// ../nodes/src/claude-plan.ts
+/**
+* @file What a Claude node's session is planned with, read from the node's
+*   context.
+*/
+/** The plan options every session of a node starts from. */
+const planOptionsOf = (context, inPlace) => {
+	const planOptions = {
+		cwd: context.cwd,
+		inputs: context.inputs,
+		outputs: context.outputs,
+		inPlace,
+		workflowDir: context.workflowDir,
+		projectRoot: context.projectRoot,
+		...context.orkDir === void 0 ? {} : { orkDir: context.orkDir },
+		pluginDir: path.join(context.runDir, "plugins", context.id)
+	};
+	if (context.checkout !== void 0) planOptions.checkout = context.checkout;
+	if (context.brief !== void 0) planOptions.brief = context.brief;
+	if (context.template !== void 0) planOptions.template = context.template;
+	if (context.item !== void 0) planOptions.item = context.item;
+	if (context.ownership !== void 0) planOptions.ownership = context.ownership;
+	if (context.mailbox !== void 0) planOptions.mailbox = context.mailbox;
+	if (context.claims !== void 0) planOptions.claims = context.claims;
+	return planOptions;
+};
 // ../nodes/src/claude-result.ts
 /**
 * @file A finished session as a node's result: its report is the output, held
@@ -123,6 +149,156 @@ const resultOf = (outcome, declared) => {
 	if (!result.ok) result.error = report.summary;
 	return result;
 };
+// ../nodes/src/environ.ts
+/** A variable of the user's. */
+const readEnv = (environ, name) => Object.hasOwn(environ, name) ? environ[name] : void 0;
+// ../nodes/src/mcp-servers.ts
+/**
+* @file Reading an MCP server's definition from the project's `.mcp.json`, the
+*   file Claude Code reads too, so a server is defined in one place (RFC-006).
+*   `${VAR}` and `${VAR:-default}` read the user's environment, which is where
+*   secrets stay: Ork stores none, and a run masks each value read this way. A
+*   server that needs an OAuth sign-in holds Claude Code's tokens, not Ork's,
+*   so it is refused.
+*/
+const VARIABLE = /\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}/gu;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stringsOf = (value) => isRecord(value) ? Object.fromEntries(Object.entries(value).flatMap(([key, item]) => typeof item === "string" ? [[key, item]] : [])) : {};
+const listOf = (value) => Array.isArray(value) ? value.flatMap((item) => typeof item === "string" ? [item] : []) : [];
+/** The server as written, or why Ork can't call it. */
+const readMcpServer = (root, name) => {
+	const servers = serversIn(root);
+	if (!servers.ok) return servers;
+	const known = Object.keys(servers.value);
+	const server = Object.hasOwn(servers.value, name) ? servers.value[name] : void 0;
+	if (!isRecord(server)) return {
+		ok: false,
+		error: `no MCP server \`${name}\` in ${MCP_FILE}${known.length === 0 ? "" : `, which has ${known.join(", ")}`}`
+	};
+	if ("oauth" in server) return {
+		ok: false,
+		error: `MCP server \`${name}\` signs in with OAuth, whose tokens are Claude Code's: give it a token through headers and \`env:\`, or call it from a session`
+	};
+	const notText = mcpNotText(server);
+	if (notText !== void 0) return {
+		ok: false,
+		error: `MCP server \`${name}\` has a value in ${notText} that isn't a string: write it in quotes`
+	};
+	const { type, url, command } = server;
+	if (type === "http" && typeof url === "string") return {
+		ok: true,
+		value: {
+			kind: "http",
+			url,
+			headers: stringsOf(server["headers"])
+		}
+	};
+	if ((type === void 0 || type === "stdio") && typeof command === "string") return {
+		ok: true,
+		value: {
+			kind: "stdio",
+			command,
+			args: listOf(server["args"]),
+			env: stringsOf(server["env"])
+		}
+	};
+	return {
+		ok: false,
+		error: `MCP server \`${name}\` is not one Ork can call: it takes stdio and http servers`
+	};
+};
+/**
+* The named servers' entries as written, for a session: `${VAR}` stays text for
+* the `claude` that loads them to expand. The compiler has checked the names.
+*/
+const namedMcpEntries = (root, names) => {
+	if (names.length === 0) return {
+		ok: true,
+		value: {}
+	};
+	const servers = serversIn(root);
+	if (!servers.ok) return servers;
+	const mcpServers = {};
+	for (const name of names) {
+		const server = Object.hasOwn(servers.value, name) ? servers.value[name] : void 0;
+		if (!isRecord(server)) return {
+			ok: false,
+			error: `no MCP server \`${name}\` in ${MCP_FILE}`
+		};
+		mcpServers[name] = server;
+	}
+	return {
+		ok: true,
+		value: { mcpServers }
+	};
+};
+/** Each variable a server reads, and whether it has a default. */
+const readsOf = (server) => {
+	return (server.kind === "stdio" ? [
+		server.command,
+		...server.args,
+		...Object.values(server.env)
+	] : [server.url, ...Object.values(server.headers)]).flatMap((text) => [...text.matchAll(VARIABLE)].map((match) => ({
+		name: String(match[1]),
+		fallback: match[2] !== void 0
+	})));
+};
+/**
+* The server with its variables filled in, and the values to mask: all it read
+* but those `plain` names, which aren't secret.
+*/
+const expandServer = (server, environ, plain = []) => {
+	const unset = readsOf(server).find(({ name, fallback }) => !fallback && readEnv(environ, name) === void 0);
+	if (unset !== void 0) return {
+		ok: false,
+		error: `${MCP_FILE} reads ${unset.name}, which is not set`
+	};
+	const values = [];
+	const fill = (text) => text.replaceAll(VARIABLE, (_all, name, fallback) => {
+		const value = readEnv(environ, name);
+		if (value !== void 0 && !plain.includes(name)) values.push(value);
+		return value ?? fallback ?? "";
+	});
+	const fillAll = (record) => Object.fromEntries(Object.entries(record).map(([key, text]) => [key, fill(text)]));
+	return {
+		ok: true,
+		value: {
+			server: server.kind === "stdio" ? {
+				kind: "stdio",
+				command: fill(server.command),
+				args: server.args.map((arg) => fill(arg)),
+				env: fillAll(server.env)
+			} : {
+				kind: "http",
+				url: fill(server.url),
+				headers: fillAll(server.headers)
+			},
+			values
+		}
+	};
+};
+/** What a workflow's MCP servers read of the user's, unless called not secret. */
+const mcpVariablesOf = (workflow, root) => Object.values(workflow.nodes).flatMap((node) => {
+	if (node.type !== "mcp.call") return [];
+	const read = readMcpServer(root, node.server);
+	return read.ok ? readsOf(read.value).map(({ name }) => name).filter((name) => node.plainEnv?.includes(name) !== true) : [];
+});
+/** A stdio server's program, when its name can be known before it is filled in. */
+const programOf = (server) => server.kind === "stdio" && !server.command.includes("$") ? server.command : void 0;
+/**
+* What stops a workflow's `mcp.call` nodes, found before a run spends anything:
+* a server that isn't there or can't be called, a program that isn't installed,
+* or a variable that is not set.
+*/
+const mcpProblems = (workflow, root, environ = process.env, finished = /* @__PURE__ */ new Set(), installed = () => true) => Object.entries(workflow.nodes).flatMap(([id, node]) => {
+	if (node.type !== "mcp.call" || finished.has(id)) return [];
+	const read = readMcpServer(root, node.server);
+	if (!read.ok) return [`${id}: ${read.error}`];
+	const given = new Set(Object.keys(node.env ?? {}));
+	const unset = readsOf(read.value).flatMap(({ name, fallback }) => fallback || given.has(name) || readEnv(environ, name) !== void 0 ? [] : [`${id}: ${MCP_FILE} reads ${name}, which is not set`]);
+	const program = programOf(read.value);
+	return program === void 0 || installed(program) ? unset : [`\`${id}\`: MCP server \`${node.server}\` runs \`${program}\`, which is not installed`].concat(unset);
+});
 /** The only built-in tools a fork has: it reads, and reports. */
 const FORK_TOOLS = [
 	"Read",
@@ -277,25 +453,39 @@ const askFork = async (context, owner, question, deps) => {
 /** What the person sees of a question its asker's owner passed on. */
 const passedOnContext = (context, owner, note) => [...context === void 0 ? [] : [context, ""], note === void 0 ? `${owner} passed this on.` : `${owner} passed this on: ${note}`].join("\n");
 /**
+* The node's channel to the person: what it asked is withdrawn when it stops,
+* so a stopped node leaves no decision open.
+*/
+const withdrawnOnStop = (context) => {
+	const { human } = context;
+	const signalOf = (asked) => asked === void 0 ? context.signal : AbortSignal.any([asked, context.signal]);
+	return {
+		permit: (request) => human.permit({
+			...request,
+			signal: signalOf(request.signal)
+		}),
+		ask: (question) => human.ask({
+			...question,
+			signal: signalOf(question.signal)
+		}),
+		...human.settled === void 0 ? {} : { settled: human.settled }
+	};
+};
+/**
 * The child's channel when its owner takes its questions first: a question goes
 * to a fork of the owner's session, then to the person if the fork passes it on
 * or can't answer. Permission prompts go to the person as before.
 */
 const ownerFirst = (context, owner, deps) => {
-	const { human } = context;
+	const human = withdrawnOnStop(context);
 	return {
 		permit: (request) => human.permit(request),
 		ask: async (question) => {
 			const answered = await askFork(context, owner, question, deps);
 			if (context.signal.aborted) throw new Error(`${context.id} was stopped`);
-			const signal = question.signal === void 0 ? context.signal : AbortSignal.any([question.signal, context.signal]);
-			if (answered === null) return human.ask({
-				...question,
-				signal
-			});
+			if (answered === null) return human.ask(question);
 			if (answered.choice === passOnId(question.options)) return human.ask({
 				...question,
-				signal,
 				owner: owner.id,
 				context: passedOnContext(question.context, owner.id, answered.note)
 			});
@@ -379,6 +569,20 @@ const budgetNow = (context) => {
 	return known.length === 0 ? void 0 : Math.min(...known);
 };
 /**
+* What a node's first session may spend, set aside from the run's budget in the
+* same step that reads it (ADR-077), so a node starting beside it is never
+* offered the same part: the least of what is left and the node's own
+* `budgetUsd`. With nothing left, it waits for a worker running beside it to
+* finish, as long as one may.
+*/
+const budgetToStart = async (context) => {
+	const left = budgetNow(context);
+	if (left !== void 0 && left <= 0) return await context.budgetFreed?.(context.signal) === true ? budgetToStart(context) : left;
+	const own = isClaudeNode(context.node) ? context.node.budgetUsd ?? context.workflow.defaults?.budgetUsd : void 0;
+	context.reserveBudget?.(own === void 0 || left === void 0 ? left : Math.min(own, left));
+	return left;
+};
+/**
 * Whether a limit across runs, rather than the node's work, ended a node: a
 * session whose cap was a quota's and that ran into it, or one its plan refused
 * and that gave no report. A node that still succeeded is left alone.
@@ -660,163 +864,6 @@ const tokenize = (command) => {
 		args
 	};
 };
-// ../nodes/src/environ.ts
-/** A variable of the user's. */
-const readEnv = (environ, name) => Object.hasOwn(environ, name) ? environ[name] : void 0;
-// ../nodes/src/mcp-servers.ts
-/**
-* @file Reading an MCP server's definition from the project's `.mcp.json`, the
-*   file Claude Code reads too, so a server is defined in one place (RFC-006).
-*   `${VAR}` and `${VAR:-default}` read the user's environment, which is where
-*   secrets stay: Ork stores none, and a run masks each value read this way. A
-*   server that needs an OAuth sign-in holds Claude Code's tokens, not Ork's,
-*   so it is refused.
-*/
-const MCP_FILE = ".mcp.json";
-const VARIABLE = /\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}/gu;
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** The file's `mcpServers`; `{}` when there is no file. */
-const serversIn = (root) => {
-	const file = path.join(root, MCP_FILE);
-	if (!existsSync(file)) return {
-		ok: true,
-		value: {}
-	};
-	try {
-		const parsed = JSON.parse(readFileSync(file, "utf8"));
-		const servers = isRecord(parsed) ? parsed["mcpServers"] : void 0;
-		return {
-			ok: true,
-			value: isRecord(servers) ? servers : {}
-		};
-	} catch (error) {
-		const reason = error instanceof SyntaxError ? "it is not valid JSON" : error instanceof Error ? error.message : String(error);
-		return {
-			ok: false,
-			error: `${MCP_FILE} can't be read: ${reason}`
-		};
-	}
-};
-const stringsOf = (value) => isRecord(value) ? Object.fromEntries(Object.entries(value).flatMap(([key, item]) => typeof item === "string" ? [[key, item]] : [])) : {};
-const listOf = (value) => Array.isArray(value) ? value.flatMap((item) => typeof item === "string" ? [item] : []) : [];
-/** A server's field that holds something other than text: it would be dropped. */
-const notTextIn = (server) => [
-	"args",
-	"env",
-	"headers"
-].find((field) => {
-	const value = server[field];
-	return (Array.isArray(value) ? value : isRecord(value) ? Object.values(value) : []).some((item) => typeof item !== "string");
-});
-/** The server as written, or why Ork can't call it. */
-const readMcpServer = (root, name) => {
-	const servers = serversIn(root);
-	if (!servers.ok) return servers;
-	const known = Object.keys(servers.value);
-	const server = Object.hasOwn(servers.value, name) ? servers.value[name] : void 0;
-	if (!isRecord(server)) return {
-		ok: false,
-		error: `no MCP server \`${name}\` in ${MCP_FILE}${known.length === 0 ? "" : `, which has ${known.join(", ")}`}`
-	};
-	if ("oauth" in server) return {
-		ok: false,
-		error: `MCP server \`${name}\` signs in with OAuth, whose tokens are Claude Code's: give it a token through headers and \`env:\`, or call it from a session`
-	};
-	const notText = notTextIn(server);
-	if (notText !== void 0) return {
-		ok: false,
-		error: `MCP server \`${name}\` has a value in ${notText} that isn't a string: write it in quotes`
-	};
-	const { type, url, command } = server;
-	if (type === "http" && typeof url === "string") return {
-		ok: true,
-		value: {
-			kind: "http",
-			url,
-			headers: stringsOf(server["headers"])
-		}
-	};
-	if ((type === void 0 || type === "stdio") && typeof command === "string") return {
-		ok: true,
-		value: {
-			kind: "stdio",
-			command,
-			args: listOf(server["args"]),
-			env: stringsOf(server["env"])
-		}
-	};
-	return {
-		ok: false,
-		error: `MCP server \`${name}\` is not one Ork can call: it takes stdio and http servers`
-	};
-};
-/** Each variable a server reads, and whether it has a default. */
-const readsOf = (server) => {
-	return (server.kind === "stdio" ? [
-		server.command,
-		...server.args,
-		...Object.values(server.env)
-	] : [server.url, ...Object.values(server.headers)]).flatMap((text) => [...text.matchAll(VARIABLE)].map((match) => ({
-		name: String(match[1]),
-		fallback: match[2] !== void 0
-	})));
-};
-/**
-* The server with its variables filled in, and the values to mask: all it read
-* but those `plain` names, which aren't secret.
-*/
-const expandServer = (server, environ, plain = []) => {
-	const unset = readsOf(server).find(({ name, fallback }) => !fallback && readEnv(environ, name) === void 0);
-	if (unset !== void 0) return {
-		ok: false,
-		error: `${MCP_FILE} reads ${unset.name}, which is not set`
-	};
-	const values = [];
-	const fill = (text) => text.replaceAll(VARIABLE, (_all, name, fallback) => {
-		const value = readEnv(environ, name);
-		if (value !== void 0 && !plain.includes(name)) values.push(value);
-		return value ?? fallback ?? "";
-	});
-	const fillAll = (record) => Object.fromEntries(Object.entries(record).map(([key, text]) => [key, fill(text)]));
-	return {
-		ok: true,
-		value: {
-			server: server.kind === "stdio" ? {
-				kind: "stdio",
-				command: fill(server.command),
-				args: server.args.map((arg) => fill(arg)),
-				env: fillAll(server.env)
-			} : {
-				kind: "http",
-				url: fill(server.url),
-				headers: fillAll(server.headers)
-			},
-			values
-		}
-	};
-};
-/** What a workflow's MCP servers read of the user's, unless called not secret. */
-const mcpVariablesOf = (workflow, root) => Object.values(workflow.nodes).flatMap((node) => {
-	if (node.type !== "mcp.call") return [];
-	const read = readMcpServer(root, node.server);
-	return read.ok ? readsOf(read.value).map(({ name }) => name).filter((name) => node.plainEnv?.includes(name) !== true) : [];
-});
-/** A stdio server's program, when its name can be known before it is filled in. */
-const programOf = (server) => server.kind === "stdio" && !server.command.includes("$") ? server.command : void 0;
-/**
-* What stops a workflow's `mcp.call` nodes, found before a run spends anything:
-* a server that isn't there or can't be called, a program that isn't installed,
-* or a variable that is not set.
-*/
-const mcpProblems = (workflow, root, environ = process.env, finished = /* @__PURE__ */ new Set(), installed = () => true) => Object.entries(workflow.nodes).flatMap(([id, node]) => {
-	if (node.type !== "mcp.call" || finished.has(id)) return [];
-	const read = readMcpServer(root, node.server);
-	if (!read.ok) return [`${id}: ${read.error}`];
-	const given = new Set(Object.keys(node.env ?? {}));
-	const unset = readsOf(read.value).flatMap(({ name, fallback }) => fallback || given.has(name) || readEnv(environ, name) !== void 0 ? [] : [`${id}: ${MCP_FILE} reads ${name}, which is not set`]);
-	const program = programOf(read.value);
-	return program === void 0 || installed(program) ? unset : [`\`${id}\`: MCP server \`${node.server}\` runs \`${program}\`, which is not installed`].concat(unset);
-});
 // ../nodes/src/tool-scrub.ts
 /**
 * @file Masking a secret in what a program prints. A plain search, so a value
@@ -998,7 +1045,9 @@ const IDENTITY_KEYS = /* @__PURE__ */ new Set([
 	"ORK_WORKFLOW",
 	"ORK_BIN",
 	OUTPUT_ENV,
-	STATE_ENV
+	STATE_ENV,
+	"ORK_ITEM",
+	"ORK_INDEX"
 ]);
 /**
 * `env` without Ork's identity variables. A run started by a program in another
@@ -1026,7 +1075,11 @@ const identityOf = (context, orkBin) => ({
 	ORK_RUN_DIR: context.runDir,
 	ORK_PROJECT: context.projectRoot,
 	ORK_WORKFLOW: context.workflow.name,
-	...orkBin === void 0 ? {} : { ORK_BIN: orkBin }
+	...orkBin === void 0 ? {} : { ORK_BIN: orkBin },
+	...context.item === void 0 ? {} : {
+		ORK_ITEM: typeof context.item.value === "string" ? context.item.value : JSON.stringify(context.item.value),
+		ORK_INDEX: String(context.item.index)
+	}
 });
 /** The variables a workflow's nodes read that no `plainEnv` excuses. */
 const secretNamesOf = (workflow) => Object.values(workflow.nodes).flatMap((node) => programsRunBy(node, workflow.defaults)).flatMap(({ program }) => {
@@ -1068,7 +1121,7 @@ const secretsOf = (workflow, environ, also = []) => valuesOf(namesToMask(workflo
 const renderEnv = (node, context, environ) => {
 	const values = {};
 	const scope = {
-		...runScope(context.inputs, context.outputs, context.runId),
+		...runScope(context.inputs, context.outputs, context.runId, context.item),
 		output: { env: environ }
 	};
 	for (const [key, text] of Object.entries(node.env ?? {})) {
@@ -1158,7 +1211,7 @@ const render = (text, context) => {
 	};
 	return {
 		ok: true,
-		value: renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId))
+		value: renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId, context.item))
 	};
 };
 /** The program and arguments a tool node runs, before the allow check. */
@@ -1515,11 +1568,19 @@ const checkedResult = (result, { check, resumes }) => {
 *   (ADR-019).
 */
 const MAX_INPUT = 8192;
-/** On a loop re-entry, the brief carries what the workflow sent back. */
+const inputJson = (input) => JSON.stringify(input ?? {}, void 0, 2);
+/** What a sent-back input is whole, for `read_input`, when its note cuts it. */
+const wholeInput = (input) => {
+	const json = inputJson(input);
+	return json.length > MAX_INPUT ? json : void 0;
+};
+/** A re-entry's note of what was sent back; `read_input` has a cut rest. */
 const reentryNote = (round, input) => {
-	const json = JSON.stringify(input ?? {}, void 0, 2);
-	const body = json.length > MAX_INPUT ? `${json.slice(0, MAX_INPUT)}\n…` : json;
-	return `\n\n## Round ${String(round)}\n\nThe workflow sent this task back to you with:\n\n\`\`\`json\n${body}\n\`\`\``;
+	const json = inputJson(input);
+	const cut = json.length > MAX_INPUT;
+	const body = cut ? `${json.slice(0, MAX_INPUT)}\n…` : json;
+	const rest = cut ? `\n\nThat is the first ${String(MAX_INPUT)} of its ${String(json.length)} characters. Call read_input for all of it before you act on it.` : "";
+	return `\n\n## Round ${String(round)}\n\nThe workflow sent this task back to you with:\n\n\`\`\`json\n${body}\n\`\`\`${rest}`;
 };
 /**
 * What a resumed leader is told: it already has its brief and its earlier work,
@@ -1545,22 +1606,7 @@ const specFor = (spec, context) => {
 };
 /** Runs a `claude.leader` or `claude.worker` as one session. */
 const claudeExecutor = (options) => async (context) => {
-	const planOptions = {
-		cwd: context.cwd,
-		inputs: context.inputs,
-		outputs: context.outputs,
-		inPlace: options.inPlace,
-		workflowDir: context.workflowDir,
-		projectRoot: context.projectRoot,
-		...context.orkDir === void 0 ? {} : { orkDir: context.orkDir },
-		pluginDir: path.join(context.runDir, "plugins", context.id)
-	};
-	if (context.checkout !== void 0) planOptions.checkout = context.checkout;
-	if (context.brief !== void 0) planOptions.brief = context.brief;
-	if (context.template !== void 0) planOptions.template = context.template;
-	if (context.ownership !== void 0) planOptions.ownership = context.ownership;
-	if (context.mailbox !== void 0) planOptions.mailbox = context.mailbox;
-	if (context.claims !== void 0) planOptions.claims = context.claims;
+	const planOptions = planOptionsOf(context, options.inPlace);
 	const before = beforeOf(context.node, context.workflow.defaults);
 	if (before !== void 0) {
 		const ran = await runStep(options.steps ?? noSteps, context, before, {
@@ -1577,7 +1623,7 @@ const claudeExecutor = (options) => async (context) => {
 	}
 	const blocked = context.quota?.().blocked;
 	if (blocked !== void 0) return notStarted(blocked, blocked);
-	const budget = budgetNow(context);
+	const budget = await budgetToStart(context);
 	if (budget !== void 0 && budget <= 0) return notStarted("nothing is left of the run's budget");
 	if (budget !== void 0) planOptions.budgetLeftUsd = budget;
 	const plan = planNodeSession(context.workflow, context.id, planOptions);
@@ -1589,16 +1635,21 @@ const claudeExecutor = (options) => async (context) => {
 		},
 		error: plan.error
 	};
-	const spec = specFor(plan.spec, context);
+	const servers = namedMcpEntries(context.projectRoot, plan.mcp);
+	if (!servers.ok) return notStarted(servers.error);
+	const spec = {
+		...specFor(plan.spec, context),
+		...servers.value
+	};
 	if (options.machineClaude === true) spec.machineClaude = true;
 	const driver = sessionDriver({
 		override: options.driver,
 		named: plan.driver,
 		ready: options.readyDriver
 	});
-	if (driver === void 0) return notStarted("no Claude driver is ready; see `ork doctor`");
+	if (driver === void 0) return notStarted("no agent driver is ready; see `ork doctor`");
 	const runtime = await options.runtimeFor(driver);
-	const ports = { human: context.owner === void 0 ? context.human : ownerFirst(context, context.owner, {
+	const ports = { human: context.owner === void 0 ? withdrawnOnStop(context) : ownerFirst(context, context.owner, {
 		runtimeFor: options.runtimeFor,
 		driver: options.driver,
 		readyDriver: options.readyDriver,
@@ -1609,9 +1660,12 @@ const claudeExecutor = (options) => async (context) => {
 	if (context.mailbox !== void 0) ports.mailbox = context.mailbox;
 	if (context.claims !== void 0) ports.claims = context.claims;
 	if (context.feedback !== void 0) ports.feedback = context.feedback;
+	const whole = context.round > 1 ? wholeInput(context.input) : void 0;
+	if (whole !== void 0) ports.input = whole;
 	const watch = limitWatch(context);
 	const run = async (asked) => {
 		const watching = watch.session(asked);
+		context.reserveBudget?.(asked.budgetUsd);
 		const session = runtime.start(asked, ports);
 		const stop = () => {
 			session.interrupt();
@@ -1629,6 +1683,7 @@ const claudeExecutor = (options) => async (context) => {
 				context.emit(event);
 			}
 		} finally {
+			context.reserveBudget?.(0);
 			disconnect?.();
 			context.signal.removeEventListener("abort", stop);
 		}
@@ -1691,10 +1746,11 @@ const claudeExecutor = (options) => async (context) => {
 };
 // ../nodes/src/gate.ts
 /**
-* @file The `human.gate` node type: asks the human the rendered question,
-*   outputs their choice with the note they gave, and answers with the
-*   `default` when the `timeout` passes. The timeout counts only while the run
-*   and the gate are not paused (ADR-041).
+* @file The `human.gate` node type: asks the human the rendered question, with
+*   its document if it has one, both in readable text (no raw JSON), outputs
+*   their choice with the note they gave, and answers with the `default` when
+*   the `timeout` passes. The timeout counts only while the run and the gate
+*   are not paused (ADR-041).
 */
 /** A promise that never settles: the losing side of a race. */
 const NEVER = new Promise(() => {});
@@ -1716,8 +1772,13 @@ const gateExecutor = async (context) => {
 		output: {},
 		error: `${context.id} is not a gate`
 	};
-	const template = parseTemplate(node.question);
-	const question = template.ok ? renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId)) : node.question;
+	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const render = (text) => {
+		const template = parseTemplate(text);
+		return template.ok ? renderTemplate(template.parts, scope, { readable: true }) : text;
+	};
+	const question = render(node.question);
+	const document = render(node.document ?? "");
 	const options = node.options.map((o) => choiceOf(o));
 	const withdraw = new AbortController();
 	context.signal.addEventListener("abort", () => {
@@ -1734,6 +1795,7 @@ const gateExecutor = async (context) => {
 		}
 	};
 	if (node.recommended !== void 0) asked.recommended = node.recommended;
+	if (document.trim() !== "") asked.document = document;
 	const answer = context.human.ask(asked).then((choice) => ({
 		choice,
 		answeredBy: "user",
@@ -1848,7 +1910,7 @@ const mcpCallExecutor = (options = {}) => async (context) => {
 	}, node.plainEnv);
 	if (!expanded.ok) return failed(expanded.error);
 	const scrub = scrubberOf([...secretsOf(context.workflow, environ, options.maskedNames), ...expanded.value.values]);
-	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const scope = runScope(context.inputs, context.outputs, context.runId, context.item);
 	const args = Object.fromEntries(Object.entries(node.arguments ?? {}).map(([key, value]) => [key, renderValue(value, scope)]));
 	const name = `${node.server}.${node.tool}`;
 	context.emit({
@@ -2130,4 +2192,4 @@ const missingPrograms = (workflow, installed = (program) => onPath(program)) =>
 	}
 	return [...missing.values()];
 };
-export { resultOf as _, builtinExecutors as a, toolExecutor as c, maskedEnv as d, maskedNamesOfRun as f, clearOutputFiles as g, sessionEnv as h, onPath as i, clearStateFiles as l, runScrubber as m, missingProgramMessage as n, spawnTool as o, runMarkerIn as p, missingPrograms as r, mcpCallExecutor as s, envProblems as t, inheritedScrubber as u };
+export { namedMcpEntries as _, builtinExecutors as a, toolExecutor as c, maskedEnv as d, maskedNamesOfRun as f, clearOutputFiles as g, sessionEnv as h, onPath as i, clearStateFiles as l, runScrubber as m, missingProgramMessage as n, spawnTool as o, runMarkerIn as p, missingPrograms as r, mcpCallExecutor as s, envProblems as t, inheritedScrubber as u, resultOf as v };