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

package/dist/{src-BxUJPGa5.mjs → src-9iGkjnsy.mjs}

@@ -1,10 +1,11 @@
-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 { $t as endOf, Bt as lowerChild, Cr as TOOL_PREFIX, Ft as failedWith, Ht as envReadsOf, It as stoppedEnd, Lt as calledWorkflows, Mt as runScope, Nt as declaredProblem, Pt as endedWith, Rt as slotClock, Sr as INTEGRATIONS, Vt as startAt, Wt as declaredOutputOf, Xt as mcpNotText, Yt as MCP_FILE, Zt as serversIn, _n as parseTemplate, _r as isToolNode, ar as programsRunBy, at as planReason, bt as heldTimeout, dt as sessionDriver, en as outcomeEnd, gn as evaluate, gr as isClaudeNode, ir as beforeOf, lr as markValue, lt as planNodeSession, pt as reportSchemaFor, rn as endFor, tn as END_DETAIL_LIMIT, vn as renderTemplate, wr as integrationFor, xr as timeoutMs } from "./src-D6_xjm-x.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";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Readable } from "node:stream";
 // ../nodes/src/call.ts
 /**
 * @file The `workflow.call` node type (RFC-004): renders what the node asks for
@@ -18,24 +19,17 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 */
 const limitedCall = (result) => {
 	if (result.ok) return result;
-	return (result.error ?? "").includes("Not started: ") || result.output["runStatus"] === "quota_exhausted" ? {
+	const why = result.end?.detail ?? result.error;
+	return result.end?.kind === "plan_limit" || (why ?? "").includes("Not started: ") || result.output["runStatus"] === "quota_exhausted" ? {
 		...result,
-		limited: result.error ?? "the called run reached a limit"
+		limited: why ?? "the called run reached a limit"
 	} : result;
 };
 const callExecutor = (context) => {
 	const { node, calls } = context;
-	if (node.type !== "workflow.call") return Promise.resolve({
-		ok: false,
-		output: {},
-		error: `${context.id} is not a call`
-	});
-	if (calls === void 0) return Promise.resolve({
-		ok: false,
-		output: { status: "fail" },
-		error: "This run cannot call workflows."
-	});
-	const scope = runScope(context.inputs, context.outputs, context.runId);
+	if (node.type !== "workflow.call") return Promise.resolve(failedWith(endFor("unknown", {}, `${context.id} is not a call`), {}));
+	if (calls === void 0) return Promise.resolve(failedWith(endFor("invalid_node", { reason: "this run cannot call workflows" }), { status: "fail" }));
+	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,33 +55,56 @@ 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
-*   to what the node declares (RFC-010).
+*   to what the node declares (RFC-010), and how it ended is its end kind
+*   (specs/runtime/session-ends.md).
 */
+/** How a session with no report ended; a driver's `done` without one is not. */
+const withoutReport = (outcome) => {
+	const end = outcomeEnd(outcome);
+	return end.kind === "done" || end.kind === "reported_failure" ? endFor("no_report", {}, end.detail) : end;
+};
 /** A finished session as a node result: its report is the node's output. */
 const resultOf = (outcome, declared) => {
-	if (outcome === null) return {
-		ok: false,
-		output: {
-			status: "fail",
-			summary: "the session ended without a result"
-		},
-		error: "the session ended without a result"
-	};
+	if (outcome === null) return failedWith(endFor("driver_crashed", {}, "the session ended without a result"));
 	const { report, usage } = outcome;
 	if (report === null) {
-		const reason = outcome.errors[0] ?? "no valid report";
+		const end = withoutReport(outcome);
 		return {
-			ok: false,
-			output: {
+			...failedWith(end, {
 				status: "fail",
-				summary: reason,
+				summary: end.message,
 				usage
-			},
+			}),
 			usage,
-			error: `ended without a report (${outcome.subtype}): ${reason}`,
 			sessionId: outcome.sessionId
 		};
 	}
@@ -101,7 +118,7 @@ const resultOf = (outcome, declared) => {
 	};
 	if (report.branch !== void 0) output["branch"] = report.branch;
 	const problem = declaredProblem(declared, output);
-	if (problem !== null) return {
+	if (problem !== null) return endedWith({
 		ok: false,
 		output: {
 			status: "fail",
@@ -111,18 +128,166 @@ const resultOf = (outcome, declared) => {
 			...report.branch === void 0 ? {} : { branch: report.branch }
 		},
 		usage,
-		error: problem,
 		...ran
-	};
-	const result = {
-		ok: report.status !== "fail",
+	}, endFor("invalid_report", { reason: problem }));
+	const ok = report.status !== "fail";
+	return endedWith({
+		ok,
 		output,
 		usage,
 		...ran
+	}, endFor(ok ? "done" : "reported_failure"));
+};
+// ../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 }
 	};
-	if (!result.ok) result.error = report.summary;
-	return result;
 };
+/** 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 +442,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)
 			});
@@ -347,13 +526,16 @@ const withUsageOf = (first, later) => {
 */
 const afterLateTurn = (first, later) => {
 	const merged = withUsageOf(first, later);
-	return later.report === null ? {
-		...merged,
+	if (later.report !== null) return merged;
+	const { end: _later, ...rest } = merged;
+	return {
+		...rest,
 		report: first.report,
 		subtype: first.subtype,
+		...first.end === void 0 ? {} : { end: first.end },
 		text: first.text,
 		errors: first.errors
-	} : merged;
+	};
 };
 /**
 * What another turn of a session may use. `spent` and `turns` are this
@@ -379,6 +561,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.
@@ -398,24 +594,38 @@ const limitWatch = (context) => {
 				},
 				ended: (outcome) => {
 					if (refused !== void 0 && (outcome?.report ?? null) === null) why = refused;
-					if (left !== void 0 && asked.budgetUsd !== void 0 && asked.budgetUsd >= left && outcome?.subtype === "error_max_budget_usd") why = context.quota?.().blocked ?? "a session reached what was left of a quota";
+					const capped = left !== void 0 && asked.budgetUsd !== void 0 && asked.budgetUsd >= left;
+					const spent = outcome !== null && outcomeEnd(outcome).kind === "budget_limit";
+					if (capped && spent) why = context.quota?.().blocked ?? "a session reached what was left of a quota";
 				}
 			};
 		},
-		result: (result) => result.ok || why === void 0 ? result : {
-			...result,
-			limited: why
+		result: (result) => {
+			if (result.ok) return result;
+			if (why !== void 0) return {
+				...endedWith(result, endFor("plan_limit", {}, why)),
+				limited: why
+			};
+			const { end } = result;
+			return end?.kind === "plan_limit" ? {
+				...result,
+				limited: end.message
+			} : result;
 		}
 	};
 };
-/** No session started: nothing was left for one. */
-const notStarted = (reason, limited) => ({
-	ok: false,
-	error: `not started: ${reason}`,
-	output: {
+/**
+* No session started: nothing was left for one, or nothing to start it. Its
+* summary keeps Ork's reason, `end.detail` too; the message is the kind's.
+*/
+const notStarted = (kind, reason, limited) => ({
+	...failedWith(endFor(kind, {
+		reason,
+		program: "an agent driver"
+	}, reason), {
 		status: "fail",
 		summary: `not started: ${reason}`
-	},
+	}),
 	...limited === void 0 ? {} : { limited }
 });
 // ../nodes/src/tool-output.ts
@@ -660,163 +870,51 @@ 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
+// ../nodes/src/tool-ends.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.
+* @file How a tool node ended (specs/runtime/session-ends.md): a node that
+*   could not run its command, JSON that broke its declared output, or how a
+*   command that ran exited: done, stopped, never started, signed out, or
+*   failed. Ork's message names the program; its stderr is the detail.
 */
-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}`
-		};
+/** A node that could not run its command: its own definition is wrong. */
+const failed$1 = (error, kind = "invalid_node") => endedWith({
+	ok: false,
+	output: {
+		exitCode: -1,
+		stdout: "",
+		stderr: error
 	}
-};
-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
-	})));
-};
+}, endFor(kind, { reason: error }, error));
+/** JSON that broke what the node declares, or that it could not read. */
+const invalidOutput = (output, reason) => endedWith({
+	ok: false,
+	output
+}, endFor("invalid_output", { reason }));
 /**
-* The server with its variables filled in, and the values to mask: all it read
-* but those `plain` names, which aren't secret.
+* How a command that ran and exited non-zero ended: stopped, never started, a
+* sign-in its program asks for (`signedOut`), or a plain failure.
 */
-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 {
+const exitKind = (run, context, signedOut) => {
+	if (context.signal.aborted) return "interrupted";
+	if (run.exitCode === -1 && /\bENOENT\b/u.test(run.stderr)) return "tool_missing";
+	return signedOut?.(run) === true ? "auth" : "command_failed";
+};
+/** How a command that ran ended, by its exit code; `program` is scrubbed. */
+const exitEnd = (output, run, context, program, signedOut) => {
+	if (run.exitCode === 0) return endedWith({
 		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
-		}
-	};
+		output
+	}, endFor("done"));
+	const end = endFor(exitKind(run, context, signedOut), {
+		program,
+		exitCode: run.exitCode
+	}, run.stderr.trim().slice(-END_DETAIL_LIMIT));
+	return endedWith({
+		ok: false,
+		output
+	}, end);
 };
-/** 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 +1096,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 +1126,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 +1172,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 +1262,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. */
@@ -1212,19 +1316,10 @@ const capped = (text, file) => {
 * what a session is told. All of it is kept in the output's fields and files.
 */
 const clipError = (text) => text.length <= ERROR_LIMIT ? text : `${text.slice(0, ERROR_LIMIT)}…`;
-const failed$1 = (error) => ({
-	ok: false,
-	output: {
-		exitCode: -1,
-		stdout: "",
-		stderr: error
-	},
-	error
-});
 /** Runs a user's CLI through its integration's adapter, with its own login. */
 const toolExecutor = (given, options = {}) => async (context) => {
 	const { node } = context;
-	if (!isToolNode(node)) return failed$1(`${context.id} is not a tool node`);
+	if (!isToolNode(node)) return failed$1(`${context.id} is not a tool`, "unknown");
 	const environ = options.environ ?? process.env;
 	const scrub = scrubberOf(secretsOf(context.workflow, environ, options.maskedNames));
 	const command = commandOf(node, context);
@@ -1251,6 +1346,7 @@ const toolExecutor = (given, options = {}) => async (context) => {
 		...node.watch === void 0 ? {} : { [STATE_ENV]: prepareStateFile(context.runDir, context.id) }
 	};
 	const names = Object.keys(nodeEnv.values);
+	const release = await context.machine?.slot([command.program, ...command.args].join(" "), context.signal);
 	context.emit({
 		type: "tool.called",
 		id: context.id,
@@ -1265,11 +1361,13 @@ const toolExecutor = (given, options = {}) => async (context) => {
 		}
 	});
 	const scriptFile = node.script === void 0 ? void 0 : writeScriptFile(context.runDir, context.id, context.round, node.script);
+	const priority = context.machine?.priority;
 	const raw = await runner(command.program, scriptFile === void 0 ? command.args : [...command.args, scriptFile], {
 		cwd,
 		signal: context.signal,
-		env
-	});
+		env,
+		...priority === void 0 ? {} : { priority }
+	}).finally(() => release?.());
 	if (scriptFile !== void 0) removeOutputFile(scriptFile);
 	const run = {
 		exitCode: raw.exitCode,
@@ -1306,30 +1404,14 @@ const toolExecutor = (given, options = {}) => async (context) => {
 	context.emit({
 		type: "tool.result",
 		id: context.id,
-		isError: run.exitCode !== 0 || json?.ok === false || declared !== null
+		isError: run.exitCode !== 0 || json?.ok === false || declared !== null,
+		...raw.cpu === void 0 ? {} : { cpu: raw.cpu }
 	});
-	if (json?.ok === false) return {
-		ok: false,
-		output,
-		error: `${context.id}: ${json.error}`
-	};
-	if (declared !== null) return {
-		ok: false,
-		output,
-		error: declared
-	};
+	if (json?.ok === false) return invalidOutput(output, json.error);
+	if (declared !== null) return invalidOutput(output, declared);
 	if (json !== null) output["json"] = json.json;
-	if (run.exitCode === 0) return {
-		ok: true,
-		output
-	};
-	const last = run.stderr.trim().split("\n").at(-1) ?? "";
-	return {
-		ok: false,
-		transient: true,
-		output,
-		error: `${scrub(command.program)} exited with ${String(run.exitCode)}${last === "" ? "" : `: ${clipError(last)}`}`
-	};
+	const signedOut = integration?.signedOut;
+	return exitEnd(output, run, context, scrub(command.program), signedOut);
 };
 // ../nodes/src/verify.ts
 /**
@@ -1341,15 +1423,17 @@ const toolExecutor = (given, options = {}) => async (context) => {
 /** A setup that failed: no session started, so nothing was spent on it. */
 const beforeFailed = (ran) => {
 	const error = `its before step failed: ${ran.error ?? "no reason given"}`;
-	return {
+	return endedWith({
 		ok: false,
-		error,
 		output: {
 			status: "fail",
 			summary: error,
 			before: ran.output
 		}
-	};
+	}, endOf({
+		...ran,
+		ok: false
+	}));
 };
 /** With nothing to run a step, a report cannot be accepted. */
 const noSteps = () => Promise.resolve({
@@ -1370,20 +1454,23 @@ const runStep = async (tool, given, { timeout, ...fields }, step) => {
 		type: "tool.shell",
 		...fields
 	};
-	const context = {
-		...given,
-		step
-	};
 	const ms = timeoutMs(timeout);
 	if (ms === void 0) return tool({
-		...context,
+		...given,
+		step,
 		node
 	});
+	const { clock, machine } = slotClock(given.hold, given.machine);
+	const context = {
+		...given,
+		step,
+		...machine === void 0 ? {} : { machine }
+	};
 	const limit = new AbortController();
 	const finished = new AbortController();
 	let expired = false;
 	const watch = async () => {
-		if (await heldTimeout(context.hold, ms, AbortSignal.any([context.signal, finished.signal]))) {
+		if (await heldTimeout(clock, ms, AbortSignal.any([context.signal, finished.signal]))) {
 			expired = true;
 			limit.abort();
 		}
@@ -1494,17 +1581,19 @@ const checkedResult = (result, { check, resumes }) => {
 	};
 	const reason = `its check failed: ${check.error ?? "no reason given"}`;
 	const error = result.ok ? reason : `${reason} (then: ${result.error ?? "no report"})`;
-	return {
+	return endedWith({
 		...result,
 		ok: false,
-		error,
 		output: {
 			...result.output,
 			status: "fail",
 			summary: error,
 			verify
 		}
-	};
+	}, endOf(result.ok ? {
+		...check,
+		ok: false
+	} : result));
 };
 // ../nodes/src/claude.ts
 /**
@@ -1515,11 +1604,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 +1642,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, {
@@ -1569,49 +1651,56 @@ const claudeExecutor = (options) => async (context) => {
 		});
 		if (!ran.ok) return beforeFailed(ran);
 		await context.hold?.wait("start", context.signal);
-		if (context.signal.aborted) return beforeFailed({
-			...ran,
-			error: "the node was stopped"
-		});
+		if (context.signal.aborted) {
+			const end = stoppedEnd(context.signal);
+			return beforeFailed({
+				...ran,
+				ok: false,
+				error: end.message,
+				end
+			});
+		}
 		planOptions.before = ran.output;
 	}
 	const blocked = context.quota?.().blocked;
-	if (blocked !== void 0) return notStarted(blocked, blocked);
-	const budget = budgetNow(context);
-	if (budget !== void 0 && budget <= 0) return notStarted("nothing is left of the run's budget");
+	if (blocked !== void 0) return notStarted("plan_limit", blocked, blocked);
+	const budget = await budgetToStart(context);
+	if (budget !== void 0 && budget <= 0) return notStarted("budget_limit", "nothing is left of the run's budget");
 	if (budget !== void 0) planOptions.budgetLeftUsd = budget;
 	const plan = planNodeSession(context.workflow, context.id, planOptions);
-	if (!plan.ok) return {
-		ok: false,
-		output: {
-			status: "fail",
-			summary: plan.error
-		},
-		error: plan.error
+	if (!plan.ok) return notStarted("invalid_node", plan.error);
+	const servers = namedMcpEntries(context.projectRoot, plan.mcp);
+	if (!servers.ok) return notStarted("invalid_node", servers.error);
+	const spec = {
+		...specFor(plan.spec, context),
+		...servers.value
 	};
-	const spec = specFor(plan.spec, context);
 	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("tool_missing", "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,
 		inPlace: options.inPlace
 	}) };
 	if (context.hold !== void 0) ports.hold = context.hold;
+	if (context.machine !== void 0) ports.machine = context.machine;
 	if (context.ownership !== void 0) ports.ownership = context.ownership;
 	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 +1718,7 @@ const claudeExecutor = (options) => async (context) => {
 				context.emit(event);
 			}
 		} finally {
+			context.reserveBudget?.(0);
 			disconnect?.();
 			context.signal.removeEventListener("abort", stop);
 		}
@@ -1691,10 +1781,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 +1807,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 +1830,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",
@@ -1752,21 +1849,22 @@ const gateExecutor = async (context) => {
 	})];
 	try {
 		const output = await Promise.race([answer, ...expired]);
-		if (!options.some((o) => o.id === output.choice)) return {
-			ok: false,
-			output,
-			error: "no one answered the gate"
-		};
+		if (!options.some((o) => o.id === output.choice)) {
+			const facts = node.timeout === void 0 ? {} : { timeout: node.timeout };
+			return endedWith({
+				ok: false,
+				output
+			}, endFor("timed_out", facts, "no one answered the gate"));
+		}
 		return {
 			ok: true,
 			output
 		};
 	} catch {
-		return {
+		return endedWith({
 			ok: false,
-			output: {},
-			error: "the gate was withdrawn"
-		};
+			output: {}
+		}, endFor("interrupted", {}, "the gate was withdrawn"));
 	} finally {
 		answered.abort();
 	}
@@ -1781,18 +1879,16 @@ const gateExecutor = async (context) => {
 */
 /** A node's `timeout:` is what limits a call; this only lifts the SDK's 60 s. */
 const NO_LIMIT_MS = 864e5;
-const failed = (error, output = {}) => ({
+const failed = (kind, facts, detail, output = {}) => endedWith({
 	ok: false,
-	output,
-	error
-});
-/** A failure another try might not have, so a `watch:` looks again. */
-const missed = (error, output = {}) => ({
-	ok: false,
-	transient: true,
-	output,
-	error
-});
+	output
+}, endFor(kind, facts, detail));
+/** How a call that threw ended: a sign-in, a server that won't start, or else. */
+const thrownKind = (error) => {
+	const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+	if (code === 401 || error?.constructor.name === "UnauthorizedError") return "auth";
+	return code === "ENOENT" ? "tool_missing" : "command_failed";
+};
 /**
 * A string's templates rendered. A string that is one `{{ … }}` and nothing
 * else keeps its value's type, so a tool that asks for a number gets one.
@@ -1836,19 +1932,22 @@ const reasonOf = (error, server) => {
 };
 const mcpCallExecutor = (options = {}) => async (context) => {
 	const { node } = context;
-	if (node.type !== "mcp.call") return failed(`${context.id} is not an MCP call`);
+	if (node.type !== "mcp.call") {
+		const said = `${context.id} is not an MCP call`;
+		return failed("unknown", {}, said);
+	}
 	const environ = options.environ ?? process.env;
 	const declared = readMcpServer(context.projectRoot, node.server);
-	if (!declared.ok) return failed(declared.error);
+	if (!declared.ok) return failed("invalid_node", { reason: declared.error });
 	const nodeEnv = renderEnv(node, context, environ);
-	if (!nodeEnv.ok) return failed(nodeEnv.error);
+	if (!nodeEnv.ok) return failed("invalid_node", { reason: nodeEnv.error });
 	const expanded = expandServer(declared.value, {
 		...environ,
 		...nodeEnv.values
 	}, node.plainEnv);
-	if (!expanded.ok) return failed(expanded.error);
+	if (!expanded.ok) return failed("invalid_node", { reason: 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({
@@ -1889,19 +1988,22 @@ const mcpCallExecutor = (options = {}) => async (context) => {
 			id: context.id,
 			isError: reported || tooLong || problem !== null
 		});
-		if (reported) return missed(`${name} failed: ${clipError(said)}`, output);
-		if (tooLong) return failed(`${name}'s result is over 64 KiB`, output);
-		return problem === null ? {
+		if (reported) return failed("command_failed", { program: name }, said, output);
+		if (tooLong) {
+			const reason = `${name}'s result is over 64 KiB`;
+			return failed("invalid_output", { reason }, void 0, output);
+		}
+		return problem === null ? endedWith({
 			ok: true,
 			output
-		} : failed(problem, output);
+		}, endFor("done")) : failed("invalid_output", { reason: problem }, void 0, output);
 	} catch (error) {
 		context.emit({
 			type: "tool.result",
 			id: context.id,
 			isError: true
 		});
-		return missed(clipError(scrub(reasonOf(error, node.server))));
+		return failed(thrownKind(error), { program: `MCP server \`${node.server}\`` }, clipError(scrub(reasonOf(error, node.server))));
 	} finally {
 		await client.close().catch(() => {});
 	}
@@ -1912,13 +2014,39 @@ const mcpCallExecutor = (options = {}) => async (context) => {
 *   text. A program runs in its own process group, so aborting it reaches
 *   whatever it started: SIGTERM, then SIGKILL for what ignores that. A stop or
 *   a timeout therefore leaves nothing running, and an escaped process that
-*   keeps the output pipes open cannot hold the node.
+*   keeps the output pipes open cannot hold the node. Off Windows it runs under
+*   `sh`, whose `times` says the CPU the program and its children used, and at
+*   the project's priority: `low` starts it below Ork's own (nice, and on macOS
+*   utility QoS).
 */
 /** How long a program may take to end after SIGTERM. */
 const KILL_AFTER_MS = 2e3;
 /** How long to wait for the pipes to close after SIGKILL. */
 const CLOSE_AFTER_MS = 500;
-const spawnTool = (program, args, { cwd, signal, env }) => {
+/**
+* Runs `$0 "$@"`, then writes the shell's `times` to fd 3: its children's user
+* and system time, the program's whole tree that it waited for. A program that
+* isn't there says so on fd 3, as spawn's ENOENT would.
+*/
+const TIMED = String.raw`command -v "$0" >/dev/null 2>&1 || { echo ork-missing >&3; exit 127; }; "$0" "$@" 3>&-; s=$?; times >&3; exit $s`;
+const MISSING = "ork-missing";
+/** The children's line of `times` (`0m1.250s 0m0.300s`), in milliseconds. */
+const cpuOfTimes = (text) => {
+	const [, , user, system] = [...text.matchAll(/(\d+)m([\d.]+)s/gu)].map(([, m = "0", s = "0"]) => Number(m) * 60 + Number(s));
+	return user === void 0 || system === void 0 ? void 0 : {
+		userMs: Math.round(user * 1e3),
+		systemMs: Math.round(system * 1e3)
+	};
+};
+const timed = process.platform !== "win32";
+/** What to start: the program, under `sh` to time it, at the priority. */
+const startOf = (program, args, priority) => timed ? startAt(priority, "sh", [
+	"-c",
+	TIMED,
+	program,
+	...args
+]) : [program, [...args]];
+const spawnTool = (program, args, { cwd, signal, env, priority }) => {
 	if (signal.aborted) return Promise.resolve({
 		exitCode: -1,
 		stdout: "",
@@ -1928,7 +2056,9 @@ const spawnTool = (program, args, { cwd, signal, env }) => {
 		const stdout = [];
 		const stderr = [];
 		const timers = [];
-		const child = spawn(program, args, {
+		const times = [];
+		const [bin, argv] = startOf(program, args, priority);
+		const child = spawn(bin, argv, {
 			cwd,
 			detached: true,
 			env: {
@@ -1938,9 +2068,15 @@ const spawnTool = (program, args, { cwd, signal, env }) => {
 			stdio: [
 				"ignore",
 				"pipe",
+				"pipe",
 				"pipe"
 			]
 		});
+		lowerChild(priority, child.pid);
+		const fd3 = child.stdio[3];
+		if (fd3 instanceof Readable) fd3.setEncoding("utf8").on("data", (chunk) => {
+			times.push(chunk);
+		});
 		const killGroup = (kill) => {
 			if (child.pid === void 0) return;
 			try {
@@ -1952,11 +2088,21 @@ const spawnTool = (program, args, { cwd, signal, env }) => {
 			signal.removeEventListener("abort", abort);
 			resolve(run);
 		};
-		const collected = (exitCode) => ({
-			exitCode,
-			stdout: stdout.join(""),
-			stderr: stderr.join("")
-		});
+		const collected = (exitCode) => {
+			const said = times.join("");
+			if (said.includes(MISSING)) return {
+				exitCode: -1,
+				stdout: stdout.join(""),
+				stderr: `could not run ${program}: spawn ${program} ENOENT`
+			};
+			const cpu = cpuOfTimes(said);
+			return {
+				exitCode,
+				stdout: stdout.join(""),
+				stderr: stderr.join(""),
+				...cpu === void 0 ? {} : { cpu }
+			};
+		};
 		const abort = () => {
 			killGroup("SIGTERM");
 			timers.push(setTimeout(() => {
@@ -1967,10 +2113,10 @@ const spawnTool = (program, args, { cwd, signal, env }) => {
 			}, KILL_AFTER_MS));
 		};
 		signal.addEventListener("abort", abort, { once: true });
-		child.stdout.setEncoding("utf8").on("data", (chunk) => {
+		child.stdout?.setEncoding("utf8").on("data", (chunk) => {
 			stdout.push(chunk);
 		});
-		child.stderr.setEncoding("utf8").on("data", (chunk) => {
+		child.stderr?.setEncoding("utf8").on("data", (chunk) => {
 			stderr.push(chunk);
 		});
 		child.on("error", (error) => {
@@ -2130,4 +2276,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 };