pi-ptc-subagents 0.1.0

package/dist/index.js

@@ -0,0 +1,3127 @@
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, defineTool, formatSize, formatSkillsForPrompt, getAgentDir, truncateTail } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { validateToolArguments } from "@earendil-works/pi-ai";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { MessageChannel, MessagePort, Worker } from "node:worker_threads";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+//#region src/runtime/dispatch.ts
+/**
+* pi.dispatch: a parallel binding that spawns a fresh pi subprocess per call.
+*
+* ADR-0016 (2026-09-23) is the contract. This file is the type surface and the spawn
+* skeleton; the actual subprocess plumbing (agent-md resolution, JSON-line parser,
+* usage accumulator, signal propagation across worker_threads / child_process) is a
+* follow-up. The stubs here are typed against the contract so call sites can land
+* before the spawn path is finalised, and so a wrong shape is a compile error rather
+* than a runtime one.
+*
+* Behaviourally compatible with pi's examples/extensions/subagent/index.ts reference
+* (--mode json, -p, --no-session, --append-system-prompt <tmpfile>), but not cooperative:
+* does not require the user to install pi's subagent extension. See ADR-0016 section 2.
+*/
+/**
+* The CLI command used to invoke a fresh pi subprocess for one dispatch.
+*
+* Always `"pi"` — pi-ptc is a library, not a CLI, and `dispatch` must spawn the
+* separate `pi` binary regardless of how the host process was launched. An
+* earlier copy of this function mirrored pi's own subagent extension and tried
+* to reuse `process.execPath + process.argv[1]`, which works only when the host
+* is `pi` itself; in any other host (test scripts, the dispatcher host process,
+* etc.) the function would spawn the host script in place of `pi`, producing
+* infinite recursion and a stdout pipe that never drains (so `proc.on('close')`
+* never fires). The caller surfaces a missing-binary condition via the child's
+* `error` event — `spawn` itself does not throw synchronously on ENOENT, the
+* async `error` listener does.
+*/
+const PI_COMMAND = "pi";
+/**
+* Compose the system prompt handed to the child subprocess.
+*
+* The agent's own markdown body is the user-supplied content; pi-ptc appends a
+* `<pi-ptc-context depth="N" max-depth="M">...</pi-ptc-context>` hint so the child
+* agent can see how much recursion room it has. The shape mirrors DSH's existing
+* subagent-context injection so the field recognises it.
+*/
+function appendDepthHint(systemPrompt, depth, maxDepth) {
+	const hint = [
+		"<pi-ptc-context depth=\"" + depth + "\" max-depth=\"" + maxDepth + "\">",
+		"You are a PTC run at depth " + depth + " (root is depth 0). You may write PTC programs and you may",
+		"call pi.dispatch(...) to spawn further children, but each level costs a fresh pi subprocess.",
+		"The remaining depth budget is " + maxDepth + " - " + depth + ". Beyond it, pi.dispatch rejects with",
+		"{ status: \"rejected\", errorMessage: \"dispatch depth limit reached\" }.",
+		"</pi-ptc-context>"
+	].join("\n");
+	return systemPrompt.length === 0 ? hint : systemPrompt + "\n\n" + hint;
+}
+/** Default error returned when the depth limit is exceeded. */
+function dispatchDepthLimitReached(currentDepth) {
+	return {
+		text: "",
+		status: "rejected",
+		agentName: "unknown",
+		durationMs: 0,
+		exitCode: -1,
+		errorMessage: "dispatch depth limit reached (current depth " + currentDepth + ", max-depth exceeded)"
+	};
+}
+/**
+* Decide the outcome of one `dispatch(...)` based on the child's `close` event.
+*
+* Cancellation has priority over every other branch: when the host's signal
+* aborted the run, the child exited because we asked it to, and the contract
+* (ADR-0016 §4) is to surface "dispatch cancelled" rather than leave the
+* caller guessing why an aborted run came back `rejected`.
+*
+* Non-cancellation cases follow the original close-handler ladder:
+*   - exit 0 with final text → fulfilled
+*   - exit 0 without final text → rejected (the model never answered)
+*   - any other exit code → rejected, no errorMessage (spawn-error path labels
+*     its own failures with `failed to spawn pi: ...`)
+*/
+function decideCloseOutcome(input) {
+	if (input.aborted) return {
+		status: "rejected",
+		errorMessage: "dispatch cancelled"
+	};
+	if (input.exitCode === 0 && input.finalText.length > 0) return { status: "fulfilled" };
+	if (input.exitCode === 0) return {
+		status: "rejected",
+		errorMessage: "dispatch produced no final text"
+	};
+	return { status: "rejected" };
+}
+/**
+* Send `signal` to `proc` iff the process is still attached, swallowing
+* "process already gone" throws. Returns whether a kill was actually issued.
+*
+* `proc.pid === undefined` happens for processes spawned without a usable
+* pid (rare, but TS-strict demands the guard); `proc.kill` throwing happens
+* for processes that exited between the guard and the syscall (the OS hands
+* back ESRCH). Both are "no-op successfully" for our purposes.
+*/
+function safeKill(proc, signal) {
+	if (proc.pid === void 0) return false;
+	try {
+		proc.kill(signal);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Minimal YAML frontmatter scalar parser. Returns the trimmed value, with surrounding
+* double or single quotes stripped when both are present.
+*/
+function extractYamlString(yaml, key) {
+	const m = yaml.match(new RegExp("^" + key + ":\\s*(.+)$", "m"));
+	if (!m) return void 0;
+	let v = (m[1] ?? "").trim();
+	if (v.length >= 2) {
+		const first = v[0];
+		const last = v[v.length - 1];
+		if (first === "\"" && last === "\"" || first === "'" && last === "'") v = v.slice(1, -1);
+	}
+	return v.length === 0 ? void 0 : v;
+}
+/**
+* Minimal YAML list parser: accepts inline `[a, b, c]` and bare `a, b, c`.
+*/
+function extractYamlList(yaml, key) {
+	const m = yaml.match(new RegExp("^" + key + ":\\s*(.+)$", "m"));
+	if (!m) return void 0;
+	let inner = (m[1] ?? "").trim();
+	if (inner.startsWith("[") && inner.endsWith("]")) inner = inner.slice(1, -1);
+	const parts = inner.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	return parts.length === 0 ? void 0 : parts;
+}
+/**
+* Parse an agent markdown file: YAML frontmatter (name / description / model / tools)
+* plus the body, returned as the system prompt. Tolerates a missing or partial
+* frontmatter; the caller falls back to defaults when this returns null.
+*/
+function parseAgentMarkdown(content) {
+	const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!fmMatch) return null;
+	const frontmatter = fmMatch[1] ?? "";
+	const body = fmMatch[2] ?? "";
+	const name = extractYamlString(frontmatter, "name");
+	if (!name) return null;
+	const description = extractYamlString(frontmatter, "description") ?? "";
+	const model = extractYamlString(frontmatter, "model") ?? "";
+	const tools = extractYamlList(frontmatter, "tools");
+	const out = {
+		name,
+		systemPrompt: body.trim()
+	};
+	if (description !== void 0) out.description = description;
+	if (model !== void 0) out.model = model;
+	if (tools !== void 0) out.tools = tools;
+	return out;
+}
+/**
+* Discover an agent by name. Mirrors pi's subagent extension agentScope behaviour:
+* user-level (`~/.pi/agent/agents/`) is loaded by default; project-level
+* (`<cwd>/.pi/agents/`) is loaded only when agentScope includes it.
+*/
+function discoverAgent(name, cwd, agentScope) {
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const projectDir = path.join(cwd, ".pi", "agents");
+	const candidates = [];
+	if (agentScope === "user" || agentScope === "both") candidates.push({
+		path: path.join(userDir, name + ".md"),
+		source: "user"
+	});
+	if (agentScope === "project" || agentScope === "both") candidates.push({
+		path: path.join(projectDir, name + ".md"),
+		source: "project"
+	});
+	for (const c of candidates) {
+		let raw;
+		try {
+			raw = fs.readFileSync(c.path, "utf-8");
+		} catch {
+			continue;
+		}
+		const parsed = parseAgentMarkdown(raw);
+		if (parsed && parsed.name === name) {
+			const out = {
+				name: parsed.name,
+				source: c.source,
+				systemPrompt: parsed.systemPrompt
+			};
+			if (parsed.model !== void 0) out.model = parsed.model;
+			if (parsed.tools !== void 0) out.tools = parsed.tools;
+			return out;
+		}
+	}
+	return null;
+}
+/**
+* Build the argv handed to the child pi subprocess. Model / thinking / tools / agentScope
+* precedence: dispatch input (call site) > agent markdown frontmatter > nothing.
+* The agent's system prompt (with the depth hint appended) is materialised to a tmpfile
+* and passed via --append-system-prompt, exactly as the subagent extension does.
+*/
+function buildArgv(input, agent, promptFilePath) {
+	const args = [
+		"--mode",
+		"json",
+		"-p",
+		"--no-session"
+	];
+	const model = input.model ?? agent.model;
+	if (model) args.push("--model", model);
+	const thinking = input.thinkingLevel ?? "off";
+	args.push("--thinking", thinking);
+	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+	args.push("--append-system-prompt", promptFilePath);
+	args.push("Task: " + input.task);
+	return args;
+}
+function parseAgentEvent(line) {
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+}
+/**
+* Write the system prompt (with depth hint appended) to a tmpfile. The caller is
+* responsible for cleanup; we use mkdtemp + 0o600 to keep the prompt private, then
+* best-effort cleanup in the dispatch() Promise.
+*/
+async function writePromptToTempFile(agentName, prompt) {
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-dispatch-"));
+	const safeName = agentName.replace(/[^\w.-]+/g, "_");
+	const filePath = path.join(tmpDir, "prompt-" + safeName + ".md");
+	await fs.promises.writeFile(filePath, prompt, {
+		encoding: "utf-8",
+		mode: 384
+	});
+	return {
+		dir: tmpDir,
+		filePath
+	};
+}
+/**
+* Best-effort cleanup of the tmpfile + dir used for the system prompt. Errors are
+* deliberately swallowed: leaving a tmpfile around is preferable to crashing the run.
+*/
+function cleanupTmp(tmp) {
+	try {
+		fs.unlinkSync(tmp.filePath);
+	} catch {}
+	try {
+		fs.rmdirSync(tmp.dir);
+	} catch {}
+}
+/**
+* Spawn one pi subprocess for one dispatch and resolve with a DispatchResult.
+*
+* Behavioural contract (ADR-0016 sections 1, 3, 4):
+*   - Resolves with status: fulfilled when the child exits 0 and emits at least one
+*     assistant message whose text is non-empty.
+*   - Resolves with status: rejected on non-zero exit, signal kill, spawn failure,
+*     unknown agent, or no usable final text.
+*   - Never rejects. The caller can pattern-match on outcome.status the same way
+*     it would pattern-match a Promise.allSettled record.
+*   - Honours signal with SIGTERM, then SIGKILL after a 5s grace window.
+*/
+async function dispatch(input, ctx) {
+	const childDepth = ctx.depth + 1;
+	if (childDepth > ctx.maxDepth) return dispatchDepthLimitReached(ctx.depth);
+	const cwd = input.cwd ?? ctx.cwd;
+	const agentScope = input.agentScope ?? "user";
+	const start = Date.now();
+	const agent = discoverAgent(input.agent, cwd, agentScope);
+	if (!agent) return {
+		text: "",
+		status: "rejected",
+		agentName: input.agent,
+		durationMs: Date.now() - start,
+		exitCode: 1,
+		errorMessage: "unknown agent: " + input.agent + " (agentScope=" + agentScope + ", cwd=" + cwd + ")"
+	};
+	const fullPrompt = appendDepthHint(agent.systemPrompt, childDepth, ctx.maxDepth);
+	const tmp = await writePromptToTempFile(agent.name, fullPrompt);
+	const argv = buildArgv(input, agent, tmp.filePath);
+	return await new Promise((resolve) => {
+		let stdoutBuffer = "";
+		let stderrBuf = "";
+		let finalText = "";
+		let usage;
+		let exitCode = -1;
+		let resolved = false;
+		let killTimer;
+		let proc;
+		let aborted = false;
+		const finalize = (status, errorMessage) => {
+			if (resolved) return;
+			resolved = true;
+			if (killTimer) clearTimeout(killTimer);
+			if (ctx.signal) ctx.signal.removeEventListener("abort", onAbort);
+			cleanupTmp(tmp);
+			const out = {
+				text: finalText,
+				status,
+				agentName: agent.name,
+				durationMs: Date.now() - start,
+				exitCode
+			};
+			if (usage) out.usage = usage;
+			if (stderrBuf.length > 0) out.stderr = stderrBuf;
+			if (errorMessage) out.errorMessage = errorMessage;
+			resolve(out);
+		};
+		const onAbort = () => {
+			if (!proc || proc.killed || resolved) return;
+			aborted = true;
+			safeKill(proc, "SIGTERM");
+			killTimer = setTimeout(() => {
+				if (proc && !proc.killed) safeKill(proc, "SIGKILL");
+			}, 5e3);
+		};
+		try {
+			proc = spawn(PI_COMMAND, argv, {
+				cwd,
+				shell: false,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			finalize("rejected", "failed to spawn pi: " + (err instanceof Error ? err.message : String(err)));
+			return;
+		}
+		if (ctx.signal) {
+			if (ctx.signal.aborted) onAbort();
+			else ctx.signal.addEventListener("abort", onAbort, { once: true });
+		}
+		const stdout = proc.stdout;
+		if (!stdout) return;
+		stdout.on("data", (data) => {
+			stdoutBuffer += data.toString("utf-8");
+			let nl = stdoutBuffer.indexOf("\n");
+			while (nl >= 0) {
+				const line = stdoutBuffer.slice(0, nl);
+				stdoutBuffer = stdoutBuffer.slice(nl + 1);
+				const ev = parseAgentEvent(line);
+				if (!ev) {
+					nl = stdoutBuffer.indexOf("\n");
+					continue;
+				}
+				if (ev.type === "message_end" && ev.message && ev.message.role === "assistant") {
+					const m = ev.message;
+					if (m.usage) {
+						const cur = usage ?? {
+							input: 0,
+							output: 0,
+							cacheRead: 0,
+							cacheWrite: 0,
+							cost: 0,
+							turns: 0
+						};
+						cur.input += m.usage.input ?? 0;
+						cur.output += m.usage.output ?? 0;
+						cur.cacheRead += m.usage.cacheRead ?? 0;
+						cur.cacheWrite += m.usage.cacheWrite ?? 0;
+						cur.cost += m.usage.cost?.total ?? 0;
+						cur.turns += 1;
+						usage = cur;
+					}
+					if (Array.isArray(m.content)) {
+						for (const part of m.content) if (part && part.type === "text" && typeof part.text === "string") finalText = part.text;
+					}
+				}
+				nl = stdoutBuffer.indexOf("\n");
+			}
+		});
+		const stderrStream = proc.stderr;
+		if (!stderrStream) return;
+		stderrStream.on("data", (data) => {
+			stderrBuf += data.toString("utf-8");
+		});
+		proc.on("close", (code) => {
+			exitCode = code ?? -1;
+			const { status, errorMessage } = decideCloseOutcome({
+				exitCode,
+				finalText,
+				aborted
+			});
+			finalize(status, errorMessage);
+		});
+		proc.on("error", (err) => {
+			stderrBuf += "[spawn-error] " + err.message + "\n";
+			finalize("rejected", "failed to spawn pi: " + err.message);
+		});
+	});
+}
+//#endregion
+//#region src/runtime/bindings.ts
+/**
+* Bindings: the pi tools a PTC program may call as `tools.<name>(args)`.
+*
+* R5 found that pi's extension API exposes no tool-dispatch surface — `pi.on('tool_call')`
+* only fires from the agent loop, `extensionsResult.runtime` is state plumbing, and
+* `pi.exec` has no `execArgv`/`resourceLimits`/`stdio`. So a binding builds the tool with
+* pi's own SDK factory and calls `execute()` on it directly. That keeps the tool
+* implementation identical to the native one, but it also means worker-driven calls are
+* **not** seen by pi's tool-call pipeline: `tool_call` guards, `protected-paths`-style
+* extensions, permission gates and sandbox overrides never run for them. This is the
+* inherited risk ADR-0005 accepts and records — it must not be described as resolved, and
+* nothing here may pretend to route through `pi.on('tool_call')`.
+*
+* Arguments are validated with pi's own `validateToolArguments`, the same helper the agent
+* loop uses, so a bad call fails with the same message (and the same coercion) it would
+* get from the native pipeline.
+*/
+/** pi's built-in tools that can be exposed as bindings, in native order. */
+const BUILTIN_BINDING_NAMES = [
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls"
+];
+/**
+* Bindings exposed when the caller does not pass an explicit name list.
+*
+* `bash` is included on purpose: DSH's PTC preset still mounts `tool-bash`/`tool-pwsh`
+* (R1 §2 — PTC mode hides the tools from the wire list and re-exposes the same registry
+* as bindings), so a PTC program written against DSH may run shell commands. Leaving it
+* out would silently shrink the surface relative to DSH. Callers that want a read-only
+* PTC surface pass an explicit subset.
+*/
+/** Parallel binding name (ADR-0016). Always bound alongside the builtin set;
+* opt-out is the callers responsibility via an explicit subset to
+* createBuiltinBindings (today the subset is restricted to builtin names,
+* so opt-out is effectively use a future flag). */
+const DISPATCH_BINDING_NAME = "pi.dispatch";
+const DEFAULT_BINDING_NAMES = BUILTIN_BINDING_NAMES;
+const BUILTIN_TOOL_FACTORIES = {
+	read: createReadTool,
+	bash: createBashTool,
+	edit: createEditTool,
+	write: createWriteTool,
+	grep: createGrepTool,
+	find: createFindTool,
+	ls: createLsTool
+};
+/**
+* Build the binding table for one run.
+*
+* Tools are created once per table and reused across calls, matching pi's own extension
+* examples (`createXxxTool(cwd)` caches nothing internally, so one instance per run is
+* the intended granularity).
+*/
+function createBuiltinBindings(options) {
+	const names = options.names ?? DEFAULT_BINDING_NAMES;
+	const table = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const factory = BUILTIN_TOOL_FACTORIES[name];
+		if (!factory) throw new TypeError(`unknown PTC binding "${name}"; known bindings: ${BUILTIN_BINDING_NAMES.join(", ")}`);
+		const tool = factory(options.cwd);
+		table.set(name, {
+			name,
+			execute: async (args, context) => {
+				const toolCallId = `ptc:${context.callId}`;
+				const toolCall = {
+					type: "toolCall",
+					id: toolCallId,
+					name: tool.name,
+					arguments: args
+				};
+				const validated = validateToolArguments(tool, toolCall);
+				const result = await tool.execute(toolCallId, validated, context.signal, void 0);
+				return {
+					content: result.content,
+					details: result.details === void 0 ? null : result.details
+				};
+			}
+		});
+	}
+	if (names === DEFAULT_BINDING_NAMES) table.set(DISPATCH_BINDING_NAME, {
+		name: DISPATCH_BINDING_NAME,
+		execute: async (args, context) => {
+			return dispatch(args, {
+				signal: context.signal,
+				callId: context.callId,
+				cwd: options.cwd,
+				depth: context.depth,
+				maxDepth: context.maxDispatchDepth
+			});
+		}
+	});
+	return table;
+}
+//#endregion
+//#region src/runtime/limits.ts
+const DEFAULT_CONFIG = Object.freeze({
+	timeoutMs: 12e4,
+	maxTimeoutMs: 6e5,
+	maxOutputBytes: 67108864,
+	maxMessageBytes: 134217728,
+	maxPendingCalls: 128,
+	maxParallelSubCalls: 10,
+	dispatchConcurrency: 8,
+	maxDispatchDepth: 3,
+	maxItemsPerCall: 4096,
+	graceMs: 3e3,
+	maxOldGenerationSizeMb: 512,
+	maxYoungGenerationSizeMb: 64
+});
+/**
+* F1 — the only environment variables a PTC worker may inherit.
+*
+* These are what a shell needs to resolve binaries on each platform; everything
+* else the host has (tokens, API keys, proxies, home paths) stays out of the worker.
+*/
+const WORKER_ENV_ALLOW_LIST = Object.freeze([
+	"PATH",
+	"PATHEXT",
+	"SYSTEMROOT",
+	"WINDIR",
+	"TEMP",
+	"TMP"
+]);
+/**
+* Build the per-run environment snapshot: the allow-list entries that actually exist.
+*
+* Unset or empty entries are dropped rather than passed through as empty strings, so
+* `Object.keys(workerEnv)` is exactly what the worker sees in `process.env`.
+*/
+function createWorkerEnv(source = process.env) {
+	const env = {};
+	for (const name of WORKER_ENV_ALLOW_LIST) {
+		const value = source[name];
+		if (typeof value === "string" && value.length > 0) env[name] = value;
+	}
+	return env;
+}
+/**
+* Merge per-run overrides onto `DEFAULT_CONFIG`.
+*
+* Overrides are validated rather than coerced: a negative or non-numeric limit is a
+* caller bug, and silently substituting a default would hide it.
+*/
+function resolveConfig(overrides = {}) {
+	const resolved = { ...DEFAULT_CONFIG };
+	for (const key of Object.keys(DEFAULT_CONFIG)) {
+		const override = overrides[key];
+		if (override === void 0) continue;
+		if (typeof override !== "number" || !Number.isFinite(override) || override <= 0) throw new TypeError(`invalid PTC config override for ${key}: ${String(override)}`);
+		resolved[key] = override;
+	}
+	return resolved;
+}
+/**
+* Resolve the effective deadline for one run.
+*
+* DSH semantics (R1 §3): `0` does not disable the deadline, it falls back to the
+* default; anything larger is clamped to `maxTimeoutMs`.
+*/
+function effectiveTimeoutMs(requested, config = DEFAULT_CONFIG) {
+	if (requested === void 0 || !Number.isFinite(requested) || requested <= 0) return config.timeoutMs;
+	return Math.min(requested, config.maxTimeoutMs);
+}
+const HOST_FRAME_KIND = Object.freeze({
+	connect: "connect",
+	init: "init",
+	callResult: "call-result",
+	cancel: "cancel"
+});
+const WORKER_FRAME_KIND = Object.freeze({
+	ready: "ready",
+	call: "call",
+	log: "log",
+	narration: "narration",
+	phase: "phase",
+	result: "result",
+	error: "error"
+});
+const PTC_LOG_LEVEL = Object.freeze({
+	log: "log",
+	info: "info",
+	warn: "warn",
+	error: "error",
+	debug: "debug"
+});
+const PTC_ERROR_KIND = Object.freeze({
+	/** Program parse error or thrown exception (includes `ReferenceError` from a helper that does not exist on this surface). */
+	exception: "exception",
+	/** Elapsed deadline expiry. */
+	timeout: "timeout",
+	/** Caller cancellation. */
+	abort: "abort",
+	/** Malformed or excessive control traffic. */
+	protocol: "protocol",
+	/** Early worker exit or a worker-level crash. */
+	workerExit: "worker-exit",
+	/** Completion value could not be materialized as lossless JSON. */
+	invalidOutput: "invalid-output",
+	/** Oversized outer result; collected logs are retained. */
+	outputLimit: "output-limit"
+});
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPtcLogLevel(value) {
+	return typeof value === "string" && Object.values(PTC_LOG_LEVEL).some((level) => level === value);
+}
+function isPtcErrorKind(value) {
+	return typeof value === "string" && Object.values(PTC_ERROR_KIND).some((kind) => kind === value);
+}
+function isPtcCancelReason(value) {
+	return value === "timeout" || value === "abort";
+}
+function isPtcConnectFrame(value) {
+	return isRecord(value) && value.kind === HOST_FRAME_KIND.connect && value.port instanceof MessagePort;
+}
+function isPtcInitFrame(value) {
+	return isRecord(value) && value.kind === HOST_FRAME_KIND.init && typeof value.runId === "string" && (value.surface === "run_code" || value.surface === "workflow") && typeof value.code === "string" && Array.isArray(value.bindings) && value.bindings.every((name) => typeof name === "string") && Array.isArray(value.bindingCandidates) && value.bindingCandidates.every((name) => typeof name === "string") && typeof value.maxItemsPerCall === "number" && Number.isFinite(value.maxItemsPerCall) && typeof value.maxPendingCalls === "number" && Number.isFinite(value.maxPendingCalls);
+}
+function isPtcCallResultFrame(value) {
+	if (!isRecord(value) || value.kind !== HOST_FRAME_KIND.callResult) return false;
+	if (!Number.isInteger(value.callId) || typeof value.tool !== "string") return false;
+	if (value.ok === true) return "value" in value;
+	return value.ok === false && typeof value.message === "string";
+}
+function isPtcCancelFrame(value) {
+	return isRecord(value) && value.kind === HOST_FRAME_KIND.cancel && isPtcCancelReason(value.reason);
+}
+function isPtcHostFrame(value) {
+	return isPtcConnectFrame(value) || isPtcInitFrame(value) || isPtcCallResultFrame(value) || isPtcCancelFrame(value);
+}
+function isPtcReadyFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.ready;
+}
+function isPtcCallFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.call && Number.isInteger(value.callId) && typeof value.tool === "string" && value.tool.length > 0 && "args" in value;
+}
+function isPtcLogFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.log && isPtcLogLevel(value.level) && typeof value.text === "string";
+}
+function isPtcNarrationFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.narration && typeof value.message === "string";
+}
+function isPtcPhaseFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.phase && typeof value.title === "string";
+}
+function isPtcResultFrame(value) {
+	return isRecord(value) && value.kind === WORKER_FRAME_KIND.result;
+}
+function isPtcErrorFrame(value) {
+	if (!isRecord(value) || value.kind !== WORKER_FRAME_KIND.error) return false;
+	const error = value.error;
+	return isRecord(error) && isPtcErrorKind(error.kind) && typeof error.message === "string" && (error.stack === void 0 || typeof error.stack === "string");
+}
+function isPtcWorkerFrame(value) {
+	return isPtcReadyFrame(value) || isPtcCallFrame(value) || isPtcLogFrame(value) || isPtcNarrationFrame(value) || isPtcPhaseFrame(value) || isPtcResultFrame(value) || isPtcErrorFrame(value);
+}
+function workerProtocolSpec() {
+	return {
+		hostFrame: HOST_FRAME_KIND,
+		workerFrame: WORKER_FRAME_KIND,
+		logLevel: PTC_LOG_LEVEL,
+		errorKind: PTC_ERROR_KIND
+	};
+}
+//#endregion
+//#region src/runtime/worker-main.ts
+function workerMain(deps) {
+	const hostFrame = deps.protocol.hostFrame;
+	const workerFrame = deps.protocol.workerFrame;
+	const logLevel = deps.protocol.logLevel;
+	const errorKind = deps.protocol.errorKind;
+	/** Wrapper name used to compile a program body (`return …` is legal inside it). */
+	const programName = "__ptcProgram";
+	let control;
+	let started = false;
+	let cancelled;
+	let nextCallId = 1;
+	/** Call frames posted and not yet answered; capped by `maxPendingCalls` (ADR-0004). */
+	let inFlightCalls = 0;
+	let maxPendingCalls = Number.POSITIVE_INFINITY;
+	const admissionWaiters = [];
+	const pending = /* @__PURE__ */ new Map();
+	const globals = () => globalThis;
+	class ToolCallError extends Error {
+		toolName;
+		constructor(toolName, message) {
+			super(message);
+			this.name = "ToolCallError";
+			this.toolName = toolName;
+		}
+	}
+	const messageOf = (error) => error instanceof Error ? error.message : String(error);
+	/**
+	* Trim a stack down to what a reader can act on.
+	*
+	* Frames inside the worker bootstrap point at the `data:` URL the worker was spawned
+	* from, which is tens of kilobytes of encoded source; dropping those lines and capping
+	* the depth keeps the model-facing stack (and the output budget) sane.
+	*/
+	const stackOf = (error) => {
+		if (!(error instanceof Error) || typeof error.stack !== "string") return void 0;
+		const lines = error.stack.split("\n");
+		const kept = [lines[0] ?? ""];
+		for (const line of lines.slice(1)) {
+			if (line.includes("data:text/javascript")) continue;
+			kept.push(line);
+			if (kept.length >= 6) break;
+		}
+		return kept.join("\n");
+	};
+	const describeValue = (value) => {
+		if (value === null) return "null";
+		if (Array.isArray(value)) return "an array";
+		return `a ${typeof value}`;
+	};
+	const post = (frame) => {
+		if (!control) return false;
+		try {
+			control.postMessage(frame);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const postLog = (level, text) => {
+		post({
+			kind: workerFrame.log,
+			level,
+			text
+		});
+	};
+	const postError = (kind, message, stack) => {
+		post(stack === void 0 ? {
+			kind: workerFrame.error,
+			error: {
+				kind,
+				message
+			}
+		} : {
+			kind: workerFrame.error,
+			error: {
+				kind,
+				message,
+				stack
+			}
+		});
+	};
+	const abortError = (reason) => {
+		const error = /* @__PURE__ */ new Error(reason === "timeout" ? "PTC run timed out" : "PTC run was cancelled");
+		error.name = "AbortError";
+		return error;
+	};
+	const closedError = () => {
+		const error = /* @__PURE__ */ new Error("the PTC control channel closed before the call completed");
+		error.name = "AbortError";
+		return error;
+	};
+	/**
+	* Admission control for host binding calls.
+	*
+	* "Maximum simultaneous host binding calls" is the worker's invariant to keep: a call
+	* frame is only posted once fewer than `maxPendingCalls` are outstanding, so a wide
+	* `Promise.all` / `parallel()` burst queues here rather than arriving at the host in one
+	* tick. The host still counts arrivals as a backstop, but it must never see this budget
+	* exceeded by a well-behaved program.
+	*
+	* Waiting for a slot is cancel-aware: `cancel` and a closed control port reject waiters
+	* immediately, so an oversized burst unwinds at once instead of waiting out the grace
+	* window before the host terminates the worker.
+	*/
+	const acquireCallSlot = async () => {
+		if (inFlightCalls < maxPendingCalls) {
+			inFlightCalls += 1;
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			admissionWaiters.push({
+				resolve,
+				reject
+			});
+		});
+	};
+	const releaseCallSlot = () => {
+		const next = admissionWaiters.shift();
+		if (next) {
+			next.resolve();
+			return;
+		}
+		inFlightCalls -= 1;
+	};
+	const rejectAdmissionWaiters = (error) => {
+		while (admissionWaiters.length > 0) {
+			const waiter = admissionWaiters.shift();
+			if (waiter) waiter.reject(error);
+		}
+	};
+	/** Settle every outstanding call and every admission wait, so nothing can hang. */
+	const flushPendingCalls = (error) => {
+		rejectAdmissionWaiters(error);
+		for (const [callId, entry] of pending) {
+			pending.delete(callId);
+			entry.reject(error);
+		}
+	};
+	/**
+	* F3 — reinstall the frozen per-run environment carried in `workerData`.
+	*
+	* The spawn already passes the same snapshot as the worker's `env` option; rebuilding
+	* `process.env` from `workerData` here is what makes the snapshot the authority: the
+	* program's environment is the frozen record, never whatever `process.env` happened
+	* to hold when a binding call crossed the wire.
+	*/
+	const installFrozenEnv = () => {
+		const data = deps.workerData;
+		if (typeof data !== "object" || data === null) return;
+		const snapshot = data.env;
+		if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) return;
+		const env = snapshot;
+		for (const key of Object.keys(process.env)) if (!(key in env)) delete process.env[key];
+		for (const key of Object.keys(env)) {
+			const value = env[key];
+			if (typeof value === "string") process.env[key] = value;
+		}
+	};
+	/**
+	* Lossless-JSON materialization of the program's return value (R1 §3 `invalid-output`).
+	*
+	* Plain JSON only: class instances, `Date`/`Map`/`Set`, functions, symbols, bigints,
+	* non-finite numbers and cycles are rejected with a path-qualified reason instead of
+	* being silently lossy through the transport. `undefined` follows `JSON.stringify`:
+	* object properties are dropped, array slots become `null`.
+	*/
+	const toJsonValue = (value) => {
+		const seen = /* @__PURE__ */ new Set();
+		const walk = (candidate, path) => {
+			if (candidate === null) return {
+				ok: true,
+				value: null
+			};
+			if (typeof candidate === "string" || typeof candidate === "boolean") return {
+				ok: true,
+				value: candidate
+			};
+			if (typeof candidate === "undefined") return {
+				ok: true,
+				value: void 0
+			};
+			if (typeof candidate === "number") {
+				if (!Number.isFinite(candidate)) return {
+					ok: false,
+					reason: `${path} is ${String(candidate)}, which is not representable as JSON`
+				};
+				return {
+					ok: true,
+					value: candidate
+				};
+			}
+			if (typeof candidate !== "object") return {
+				ok: false,
+				reason: `${path} is ${describeValue(candidate)}; results must be lossless JSON`
+			};
+			if (Array.isArray(candidate)) {
+				if (seen.has(candidate)) return {
+					ok: false,
+					reason: `${path} is a circular reference`
+				};
+				seen.add(candidate);
+				const items = [];
+				for (let index = 0; index < candidate.length; index += 1) {
+					const item = walk(candidate[index], `${path}[${index}]`);
+					if (!item.ok) return item;
+					items.push(item.value === void 0 ? null : item.value);
+				}
+				seen.delete(candidate);
+				return {
+					ok: true,
+					value: items
+				};
+			}
+			const prototype = Object.getPrototypeOf(candidate);
+			if (prototype !== Object.prototype && prototype !== null) {
+				const ctor = candidate.constructor;
+				return {
+					ok: false,
+					reason: `${path} is a ${ctor && typeof ctor.name === "string" && ctor.name.length > 0 ? ctor.name : "an object"}; results must be plain JSON objects`
+				};
+			}
+			if (seen.has(candidate)) return {
+				ok: false,
+				reason: `${path} is a circular reference`
+			};
+			seen.add(candidate);
+			const entries = {};
+			for (const key of Object.keys(candidate)) {
+				const item = walk(candidate[key], `${path}.${key}`);
+				if (!item.ok) return item;
+				if (item.value !== void 0) entries[key] = item.value;
+			}
+			seen.delete(candidate);
+			return {
+				ok: true,
+				value: entries
+			};
+		};
+		return walk(value, "result");
+	};
+	const formatArgs = (args) => args.map((arg) => typeof arg === "string" ? arg : deps.inspect(arg, {
+		depth: 4,
+		breakLength: Infinity,
+		colors: false
+	})).join(" ");
+	/**
+	* Capture `console` instead of letting worker stdio reach the host terminal.
+	*
+	* Only the printing methods exist on this surface; everything routes to `log` frames
+	* so the model (not the terminal) sees the program's output.
+	*/
+	const installConsole = () => {
+		const write = (level) => {
+			return (...args) => {
+				postLog(level, formatArgs(args));
+			};
+		};
+		globals().console = {
+			log: write(logLevel.log),
+			info: write(logLevel.info),
+			warn: write(logLevel.warn),
+			error: write(logLevel.error),
+			debug: write(logLevel.debug)
+		};
+	};
+	/**
+	* Route `process.emitWarning` output through `log` frames.
+	*
+	* Node's default warning printer writes to stderr, which is piped to the host terminal.
+	* `ExperimentalWarning`s are dropped rather than forwarded: the PTC runtime itself uses
+	* experimental Node APIs (type stripping, for one) and those warnings are about the
+	* harness, not about the program — forwarding them would put Node-internals noise into
+	* every run's logs.
+	*/
+	const installWarningCapture = () => {
+		if (typeof process.removeAllListeners !== "function" || typeof process.on !== "function") return;
+		process.removeAllListeners("warning");
+		process.on("warning", (warning) => {
+			const record = typeof warning === "object" && warning !== null ? warning : void 0;
+			const name = record && typeof record.name === "string" ? record.name : "Warning";
+			if (name === "ExperimentalWarning") return;
+			const detail = record && typeof record.message === "string" ? record.message : String(warning);
+			postLog(logLevel.warn, `${name}: ${detail}`);
+		});
+	};
+	/**
+	* Compile a program body into a callable.
+	*
+	* The body is wrapped in an async function so `return` and `await` work at the top
+	* level, then run through `stripTypeScriptTypes` so the same body may carry type
+	* annotations (DSH's "type annotations are advisory, the code runs type-stripped").
+	* JavaScript the TypeScript parser rejects falls back to the unstripped source; a
+	* genuine syntax error then surfaces from the `Function` constructor instead.
+	*/
+	const compileProgram = (code) => {
+		const wrapped = `async function ${programName}() {\n${code}\n}`;
+		let source = wrapped;
+		try {
+			source = deps.stripTypes(wrapped, { mode: "strip" });
+		} catch {
+			source = wrapped;
+		}
+		return new Function(`${source}\nreturn ${programName}();`);
+	};
+	const runProgram = async (code) => {
+		let program;
+		try {
+			program = compileProgram(code);
+		} catch (error) {
+			postError(errorKind.exception, `program failed to compile: ${messageOf(error)}`, stackOf(error));
+			return;
+		}
+		try {
+			const value = await program();
+			const normalized = toJsonValue(value);
+			if (!normalized.ok) {
+				postError(errorKind.invalidOutput, normalized.reason);
+				return;
+			}
+			post(normalized.value === void 0 ? { kind: workerFrame.result } : {
+				kind: workerFrame.result,
+				value: normalized.value
+			});
+		} catch (error) {
+			postError(cancelled ?? errorKind.exception, messageOf(error), stackOf(error));
+		}
+	};
+	/**
+	* `tools.<name>(args)` — acquire an admission slot, post a call frame, and await the
+	* matching `call-result`.
+	*
+	* The slot is released on every exit path (settled, admission refused by `post`, cancel),
+	* which is what keeps a burst draining instead of deadlocking.
+	*/
+	const makeBinding = (name) => {
+		return async (args) => {
+			if (cancelled) throw abortError(cancelled);
+			await acquireCallSlot();
+			try {
+				if (cancelled) throw abortError(cancelled);
+				const callId = nextCallId;
+				nextCallId += 1;
+				const promise = new Promise((resolve, reject) => {
+					pending.set(callId, {
+						resolve,
+						reject
+					});
+				});
+				if (!post({
+					kind: workerFrame.call,
+					callId,
+					tool: name,
+					args
+				})) {
+					pending.delete(callId);
+					throw new ToolCallError(name, `${name}() could not be called: the arguments are not transferable or the run has ended`);
+				}
+				return await promise;
+			} finally {
+				releaseCallSlot();
+			}
+		};
+	};
+	const settleCall = (frame) => {
+		const callId = frame.callId;
+		if (typeof callId !== "number") return;
+		const entry = pending.get(callId);
+		if (!entry) return;
+		pending.delete(callId);
+		if (frame.ok === true) {
+			entry.resolve(frame.value);
+			return;
+		}
+		entry.reject(new ToolCallError(typeof frame.tool === "string" ? frame.tool : "unknown", typeof frame.message === "string" ? frame.message : "binding call failed"));
+	};
+	const cancelPending = (reason) => {
+		cancelled = reason;
+		flushPendingCalls(abortError(reason));
+	};
+	const assertItemCount = (helper, count, maxItemsPerCall) => {
+		if (count > maxItemsPerCall) throw new RangeError(`${helper}() received ${count} items, exceeding maxItemsPerCall (${maxItemsPerCall})`);
+	};
+	const installWorkflowHelpers = (args, maxItemsPerCall) => {
+		const target = globals();
+		target.args = args === void 0 ? null : args;
+		target.log = (message) => {
+			if (typeof message !== "string") throw new TypeError(`log(message) expects a string, received ${describeValue(message)}`);
+			post({
+				kind: workerFrame.narration,
+				message
+			});
+		};
+		target.phase = (title) => {
+			if (typeof title !== "string") throw new TypeError(`phase(title) expects a string, received ${describeValue(title)}`);
+			post({
+				kind: workerFrame.phase,
+				title
+			});
+		};
+		target.parallel = async (thunks) => {
+			if (!Array.isArray(thunks)) throw new TypeError(`parallel(thunks) expects an array of functions, received ${describeValue(thunks)}`);
+			assertItemCount("parallel", thunks.length, maxItemsPerCall);
+			for (let index = 0; index < thunks.length; index += 1) if (typeof thunks[index] !== "function") throw new TypeError(`parallel(thunks) expects functions; item ${index} is ${describeValue(thunks[index])}`);
+			return await Promise.all(thunks.map(async (thunk) => {
+				try {
+					return await thunk();
+				} catch {
+					return null;
+				}
+			}));
+		};
+		target.pipeline = async (items, ...stages) => {
+			if (!Array.isArray(items)) throw new TypeError(`pipeline(items, ...stages) expects an array of items, received ${describeValue(items)}`);
+			assertItemCount("pipeline", items.length, maxItemsPerCall);
+			if (stages.length === 0) throw new TypeError("pipeline(items, ...stages) requires at least one stage function");
+			for (let index = 0; index < stages.length; index += 1) if (typeof stages[index] !== "function") throw new TypeError(`pipeline(items, ...stages) expects stage functions; stage ${index} is ${describeValue(stages[index])}`);
+			const stageFunctions = stages;
+			return await Promise.all(items.map(async (item, index) => {
+				try {
+					let current = item;
+					for (const stage of stageFunctions) current = await stage(current, item, index);
+					return current;
+				} catch {
+					return null;
+				}
+			}));
+		};
+	};
+	const startRun = (frame) => {
+		installFrozenEnv();
+		installConsole();
+		maxPendingCalls = typeof frame.maxPendingCalls === "number" && Number.isFinite(frame.maxPendingCalls) && frame.maxPendingCalls > 0 ? frame.maxPendingCalls : Number.POSITIVE_INFINITY;
+		const tools = {};
+		const bindingNames = Array.isArray(frame.bindings) ? frame.bindings.filter((name) => typeof name === "string") : [];
+		for (const name of bindingNames) tools[name] = makeBinding(name);
+		const available = bindingNames.join(", ") || "(none)";
+		const candidates = Array.isArray(frame.bindingCandidates) ? frame.bindingCandidates : [];
+		for (const name of candidates) {
+			if (typeof name !== "string" || tools[name]) continue;
+			tools[name] = async () => {
+				throw new ToolCallError(name, `no binding named "${name}" in this run; available bindings: ${available}`);
+			};
+		}
+		globals().tools = tools;
+		if (frame.surface === "workflow") {
+			const maxItemsPerCall = typeof frame.maxItemsPerCall === "number" ? frame.maxItemsPerCall : 0;
+			installWorkflowHelpers(frame.args, maxItemsPerCall);
+		}
+		runProgram(typeof frame.code === "string" ? frame.code : "");
+	};
+	const handleHostFrame = (raw) => {
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return;
+		const frame = raw;
+		if (frame.kind === hostFrame.init) {
+			if (started) return;
+			started = true;
+			startRun(frame);
+			return;
+		}
+		if (frame.kind === hostFrame.callResult) {
+			settleCall(frame);
+			return;
+		}
+		if (frame.kind === hostFrame.cancel) cancelPending(frame.reason === "timeout" ? "timeout" : "abort");
+	};
+	deps.parentPort.on("message", (value) => {
+		if (typeof value !== "object" || value === null) return;
+		const frame = value;
+		if (frame.kind !== hostFrame.connect) return;
+		const port = frame.port;
+		if (typeof port !== "object" || port === null || typeof port.on !== "function") return;
+		control = port;
+		control.on("message", handleHostFrame);
+		control.on("close", () => {
+			flushPendingCalls(closedError());
+		});
+		installWarningCapture();
+		post({ kind: workerFrame.ready });
+	});
+}
+//#endregion
+//#region src/runtime/worker-source.ts
+/** Build the worker module source for one spawn. */
+function buildWorkerSource(protocol) {
+	return [
+		`import { parentPort, workerData } from "node:worker_threads";`,
+		`import { inspect } from "node:util";`,
+		`import { stripTypeScriptTypes } from "node:module";`,
+		`const ptcDeps = ${JSON.stringify({ protocol })};`,
+		`(${workerMain.toString()})({ ...ptcDeps, parentPort, workerData, inspect, stripTypes: stripTypeScriptTypes });`
+	].join("\n");
+}
+/** The worker entry as a `data:` module URL, ready for `new Worker(url, options)`. */
+function buildWorkerUrl(protocol) {
+	return new URL(`data:text/javascript,${encodeURIComponent(buildWorkerSource(protocol))}`);
+}
+//#endregion
+//#region src/runtime/dispatcher.ts
+/**
+* Host-side dispatcher: one `runPtcProgram()` call = one worker = one program.
+*
+* Responsibilities:
+* - spawn a hardened worker (F1 env scrub, F2 V8 caps, F3 frozen per-run env in
+*   `workerData`, F4 `cwd` carried in the run config and handed to the bindings),
+* - complete the `MessageChannel` handshake and send the `init` frame,
+* - route `tools.*` calls to the binding table — concurrently, with DSH's
+*   `maxParallelSubCalls` forwarding cap and `maxPendingCalls` admission control,
+* - collect logs / narration / phases and enforce the joint output budget,
+* - enforce the deadline, honour caller cancellation, and always tear the worker down.
+*
+* Everything the worker can influence is treated as untrusted input: every frame goes
+* through the protocol guards, is size-checked, and can only ever end the run.
+*/
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** Serialized byte size of a frame, the unit both the output and message budgets use. */
+function serializedBytes(value) {
+	try {
+		return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+	} catch {
+		return Number.POSITIVE_INFINITY;
+	}
+}
+/**
+* Run one PTC program in a fresh worker and resolve with its outcome.
+*
+* Never rejects for program/ limit / cancellation failures — those are reported as
+* `outcome.error` so callers have one place to render from. It only throws on caller bugs
+* (invalid config overrides).
+*/
+async function runPtcProgram(options) {
+	const config = resolveConfig(options.config);
+	const protocol = workerProtocolSpec();
+	const env = createWorkerEnv();
+	const runId = options.runId ?? randomUUID();
+	const timeoutMs = effectiveTimeoutMs(options.timeoutMs, config);
+	const logs = [];
+	const narrations = [];
+	const phases = [];
+	if (options.signal?.aborted) return {
+		logs,
+		narrations,
+		phases,
+		error: {
+			kind: PTC_ERROR_KIND.abort,
+			message: "run cancelled before start"
+		}
+	};
+	return await new Promise((resolve) => {
+		const worker = new Worker(buildWorkerUrl(protocol), {
+			name: `ptc-${options.surface}`,
+			env,
+			workerData: {
+				runId,
+				env
+			},
+			resourceLimits: {
+				maxOldGenerationSizeMb: config.maxOldGenerationSizeMb,
+				maxYoungGenerationSizeMb: config.maxYoungGenerationSizeMb
+			}
+		});
+		const channel = new MessageChannel();
+		const control = channel.port1;
+		const workerPort = channel.port2;
+		const bindingAbort = new AbortController();
+		let settled = false;
+		let cancelling;
+		let pendingCalls = 0;
+		let outputBytes = 0;
+		let activeDispatches = 0;
+		const dispatchWaiters = [];
+		const runDepth = 0;
+		let runTimer;
+		let graceTimer;
+		const images = [];
+		/**
+		* Hoist the images out of one successful binding result.
+		*
+		* DSH does this in its scheduler's commit step: a subtool result whose content carries an image
+		* block has that content attached to the caller's context after the run, so the picture reaches
+		* the model without travelling through the program's lossless-JSON return value (`dsh-tools`:
+		* `exec.deferContext(createUserMessage(...))`). The host sees every binding result before it is
+		* posted to the worker, so this is the same seam.
+		*
+		* Everything is hoisted: no count cap, no byte cap, no dedupe. How much context a run spends on
+		* images is the program's call, and hiding a cap behind a warning would make this layer a
+		* gatekeeper DSH does not have. pi's per-model resize (`inputLimits.images.resize`) still bounds
+		* what a single attachment costs at the provider.
+		*/
+		const hoistImages = (value) => {
+			const content = value?.content;
+			if (!Array.isArray(content)) return;
+			for (const block of content) {
+				if (block === null || typeof block !== "object") continue;
+				const candidate = block;
+				if (candidate.type !== "image") continue;
+				const data = typeof candidate.data === "string" ? candidate.data : "";
+				if (data.length === 0) continue;
+				images.push({
+					data,
+					mimeType: typeof candidate.mimeType === "string" ? candidate.mimeType : "application/octet-stream"
+				});
+			}
+		};
+		const cancelMessage = (reason) => reason === "timeout" ? `run timed out after ${timeoutMs} ms` : "run cancelled";
+		const finish = (outcome) => {
+			if (settled) return;
+			settled = true;
+			if (runTimer) clearTimeout(runTimer);
+			if (graceTimer) clearTimeout(graceTimer);
+			options.signal?.removeEventListener("abort", onAbortSignal);
+			bindingAbort.abort();
+			control.close();
+			worker.terminate();
+			resolve(outcome);
+		};
+		const fail = (kind, message, stack) => {
+			finish({
+				logs,
+				narrations,
+				phases,
+				error: stack === void 0 ? {
+					kind,
+					message
+				} : {
+					kind,
+					message,
+					stack
+				}
+			});
+		};
+		const sendControl = (frame) => {
+			if (settled) return;
+			if (!isPtcHostFrame(frame)) {
+				fail(PTC_ERROR_KIND.protocol, "internal error: malformed host frame");
+				return;
+			}
+			control.postMessage(frame);
+		};
+		const sendInit = () => {
+			const frame = {
+				kind: HOST_FRAME_KIND.init,
+				runId,
+				surface: options.surface,
+				code: options.code,
+				bindings: [...options.bindings.keys()],
+				bindingCandidates: [...BUILTIN_BINDING_NAMES],
+				maxItemsPerCall: config.maxItemsPerCall,
+				maxPendingCalls: config.maxPendingCalls,
+				...options.args === void 0 ? {} : { args: options.args }
+			};
+			if (!isPtcHostFrame(frame)) {
+				fail(PTC_ERROR_KIND.protocol, "internal error: malformed init frame");
+				return;
+			}
+			const bytes = serializedBytes(frame);
+			if (bytes > config.maxMessageBytes) {
+				fail(PTC_ERROR_KIND.protocol, `init frame of ${bytes} bytes exceeds maxMessageBytes (${config.maxMessageBytes})`);
+				return;
+			}
+			sendControl(frame);
+		};
+		const accountOutput = (bytes, source) => {
+			outputBytes += bytes;
+			if (outputBytes <= config.maxOutputBytes) return true;
+			fail(PTC_ERROR_KIND.outputLimit, `${source} exceeded the output budget: logs + result reached ${outputBytes} bytes (maxOutputBytes=${config.maxOutputBytes}); ${logs.length} log line(s) retained`);
+			return false;
+		};
+		const acquireDispatchSlot = async () => {
+			if (activeDispatches < config.maxParallelSubCalls) {
+				activeDispatches += 1;
+				return;
+			}
+			await new Promise((slot) => {
+				dispatchWaiters.push(slot);
+			});
+		};
+		const releaseDispatchSlot = () => {
+			const next = dispatchWaiters.shift();
+			if (next) {
+				next();
+				return;
+			}
+			activeDispatches -= 1;
+		};
+		const handleCall = (frame) => {
+			pendingCalls += 1;
+			if (pendingCalls > config.maxPendingCalls) {
+				fail(PTC_ERROR_KIND.protocol, `more than maxPendingCalls (${config.maxPendingCalls}) binding calls in flight`);
+				return;
+			}
+			dispatchCall(frame).finally(() => {
+				pendingCalls -= 1;
+			});
+		};
+		const dispatchCall = async (frame) => {
+			const binding = options.bindings.get(frame.tool);
+			if (!binding) {
+				postCallResult({
+					kind: HOST_FRAME_KIND.callResult,
+					callId: frame.callId,
+					tool: frame.tool,
+					ok: false,
+					message: `no binding named "${frame.tool}" in this run; available bindings: ` + ([...options.bindings.keys()].join(", ") || "(none)")
+				});
+				return;
+			}
+			await acquireDispatchSlot();
+			if (settled) {
+				releaseDispatchSlot();
+				return;
+			}
+			try {
+				const value = await binding.execute(frame.args, {
+					signal: bindingAbort.signal,
+					callId: frame.callId,
+					depth: runDepth,
+					maxDispatchDepth: config.maxDispatchDepth
+				});
+				if (postCallResult({
+					kind: HOST_FRAME_KIND.callResult,
+					callId: frame.callId,
+					tool: frame.tool,
+					ok: true,
+					value
+				})) hoistImages(value);
+			} catch (error) {
+				postCallResult({
+					kind: HOST_FRAME_KIND.callResult,
+					callId: frame.callId,
+					tool: frame.tool,
+					ok: false,
+					message: messageOf(error)
+				});
+			} finally {
+				releaseDispatchSlot();
+			}
+		};
+		/** `true` when the worker actually received the result (see the hoist at the call site). */
+		const postCallResult = (frame) => {
+			if (settled) return false;
+			try {
+				control.postMessage(frame);
+				return true;
+			} catch (error) {
+				try {
+					control.postMessage({
+						kind: HOST_FRAME_KIND.callResult,
+						callId: frame.callId,
+						tool: frame.tool,
+						ok: false,
+						message: `binding result could not be transferred: ${messageOf(error)}`
+					});
+				} catch {
+					fail(PTC_ERROR_KIND.protocol, "binding result is not transferable");
+				}
+				return false;
+			}
+		};
+		const settleTerminal = (outcome) => {
+			if (!cancelling) return outcome;
+			return {
+				logs,
+				narrations,
+				phases,
+				error: {
+					kind: cancelling === "timeout" ? PTC_ERROR_KIND.timeout : PTC_ERROR_KIND.abort,
+					message: cancelMessage(cancelling)
+				}
+			};
+		};
+		const handleFrame = (frame) => {
+			if (settled) return;
+			if (!isPtcWorkerFrame(frame)) {
+				fail(PTC_ERROR_KIND.protocol, "malformed worker frame");
+				return;
+			}
+			const bytes = frame.kind === WORKER_FRAME_KIND.ready ? 0 : serializedBytes(frame);
+			if (!Number.isFinite(bytes)) {
+				fail(PTC_ERROR_KIND.protocol, "worker frame could not be serialized for accounting");
+				return;
+			}
+			if (bytes > config.maxMessageBytes) {
+				fail(PTC_ERROR_KIND.protocol, `control frame of ${bytes} bytes exceeds maxMessageBytes (${config.maxMessageBytes})`);
+				return;
+			}
+			switch (frame.kind) {
+				case WORKER_FRAME_KIND.ready:
+					sendInit();
+					return;
+				case WORKER_FRAME_KIND.call:
+					handleCall(frame);
+					return;
+				case WORKER_FRAME_KIND.log:
+					if (accountOutput(bytes, "console output")) logs.push(frame.text);
+					return;
+				case WORKER_FRAME_KIND.narration:
+					if (accountOutput(bytes, "workflow narration")) narrations.push(frame.message);
+					return;
+				case WORKER_FRAME_KIND.phase:
+					if (accountOutput(bytes, "workflow phase")) phases.push(frame.title);
+					return;
+				case WORKER_FRAME_KIND.result: {
+					if (!accountOutput(bytes, "completion value")) return;
+					const base = {
+						logs,
+						narrations,
+						phases,
+						...images.length > 0 ? { images } : {}
+					};
+					finish(settleTerminal(frame.value === void 0 ? base : {
+						...base,
+						value: frame.value
+					}));
+					return;
+				}
+				case WORKER_FRAME_KIND.error:
+					finish(settleTerminal({
+						logs,
+						narrations,
+						phases,
+						error: frame.error
+					}));
+					return;
+				default: fail(PTC_ERROR_KIND.protocol, "unknown worker frame");
+			}
+		};
+		function onAbortSignal() {
+			beginCancel("abort");
+		}
+		function beginCancel(reason) {
+			if (settled || cancelling) return;
+			cancelling = reason;
+			if (runTimer) {
+				clearTimeout(runTimer);
+				runTimer = void 0;
+			}
+			bindingAbort.abort();
+			sendControl({
+				kind: HOST_FRAME_KIND.cancel,
+				reason
+			});
+			graceTimer = setTimeout(() => {
+				fail(reason === "timeout" ? PTC_ERROR_KIND.timeout : PTC_ERROR_KIND.abort, cancelMessage(reason));
+			}, config.graceMs);
+		}
+		worker.on("error", (error) => {
+			fail(PTC_ERROR_KIND.workerExit, `worker failed: ${messageOf(error)}`);
+		});
+		worker.on("exit", (code) => {
+			fail(PTC_ERROR_KIND.workerExit, `worker exited with code ${code} before the run completed`);
+		});
+		control.on("message", handleFrame);
+		control.on("messageerror", () => {
+			fail(PTC_ERROR_KIND.protocol, "worker sent a frame that could not be deserialized");
+		});
+		options.signal?.addEventListener("abort", onAbortSignal, { once: true });
+		runTimer = setTimeout(() => {
+			beginCancel("timeout");
+		}, timeoutMs);
+		const connectFrame = {
+			kind: HOST_FRAME_KIND.connect,
+			port: workerPort
+		};
+		if (!isPtcHostFrame(connectFrame)) fail(PTC_ERROR_KIND.protocol, "internal error: malformed connect frame");
+		else worker.postMessage(connectFrame, [workerPort]);
+	});
+}
+//#endregion
+//#region src/tools/text.ts
+/** Hard cap for one rendered line; longer lines are truncated with `…`. */
+const MAX_LINE_CHARS = 200;
+/** A value stays on one line while its inline form fits this; otherwise it renders as a block. */
+const INLINE_MAX_CHARS = 100;
+/** Indent applied per nesting level in block form. */
+const INDENT = "  ";
+/**
+* ANSI escapes, in the two shapes that matter: OSC (\`ESC ] …\` to BEL, \`ESC \\\\` or C1 ST) and
+* CSI plus friends (introducer, optional intermediates, optional params, final byte).
+*
+* Built through the \`RegExp\` constructor from an escaped source so no control character appears
+* literally — the repo lints via oxlint, whose \`no-control-regex\` rule rejects that.
+*/
+const ANSI_PATTERN = new RegExp(["(?:\\u001B\\][\\s\\S]*?(?:\\u0007|\\u001B\\u005C|\\u009C))", "[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]"].join("|"), "g");
+/** Drop ANSI escape sequences (colours, cursor moves, OSC hyperlinks). */
+function stripAnsi(value) {
+	if (!value.includes(String.fromCharCode(27)) && !value.includes(String.fromCharCode(155))) return value;
+	return value.replace(ANSI_PATTERN, "");
+}
+/**
+* Make arbitrary program output safe to hand the model.
+*
+* Same three steps as pi's built-ins: strip ANSI, remove `\r` (a progress bar's carriage
+* return is not a line break), then drop control characters other than `\n`/`\t` and the
+* Unicode format characters that break width math. Lone surrogates fall out of code-point
+* iteration for free.
+*/
+function sanitizeText(value) {
+	const stripped = stripAnsi(value).replace(/\r/g, "");
+	if (stripped.length === 0) return stripped;
+	let out = "";
+	for (const char of stripped) {
+		const code = char.codePointAt(0);
+		if (code === void 0) continue;
+		if (code === 10 || code === 9) {
+			out += char;
+			continue;
+		}
+		if (code <= 31) continue;
+		if (code >= 65529 && code <= 65531) continue;
+		out += char;
+	}
+	return out;
+}
+/** Object keys that read as identifiers in the summary style are left unquoted. */
+const BARE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function keyText(key) {
+	return BARE_KEY.test(key) ? key : JSON.stringify(key);
+}
+/**
+* The inline form of a value, or `undefined` when it cannot be inlined.
+*
+* A string with a real newline is never inlined: keeping its line structure is the whole point
+* (see ADR-0012), and quoting it would turn one readable block back into `\n` escapes.
+*/
+function inlineForm(value) {
+	if (value === null) return "null";
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "string") {
+		const sanitized = sanitizeText(value);
+		return sanitized.includes("\n") ? void 0 : JSON.stringify(sanitized);
+	}
+	if (Array.isArray(value)) {
+		const items = [];
+		for (const item of value) {
+			const rendered = inlineForm(item);
+			if (rendered === void 0) return void 0;
+			items.push(rendered);
+		}
+		return `[${items.join(", ")}]`;
+	}
+	const keys = Object.keys(value);
+	if (keys.length === 0) return "{}";
+	const parts = [];
+	for (const key of keys) {
+		const rendered = inlineForm(value[key] ?? null);
+		if (rendered === void 0) return void 0;
+		parts.push(`${keyText(key)}: ${rendered}`);
+	}
+	return `{${parts.join(", ")}}`;
+}
+/** Inline rendering, but only while it stays short enough to read on one line. */
+function tryInline(value) {
+	const rendered = inlineForm(value);
+	if (rendered === void 0) return void 0;
+	return rendered.length <= INLINE_MAX_CHARS ? rendered : void 0;
+}
+/** A non-container value on its own line (block form only meets these defensively). */
+function scalarText(value) {
+	if (value === null) return "null";
+	return typeof value === "string" ? sanitizeText(value) : String(value);
+}
+/** One key per line, braces kept, string values raw (real newlines preserved, indented). */
+function blockLines(value, indent) {
+	if (value === null || typeof value !== "object") return [`${indent}${scalarText(value)}`];
+	if (Array.isArray(value)) {
+		if (value.length === 0) return [`${indent}[]`];
+		const lines = [`${indent}[`];
+		for (const item of value) {
+			const inline = tryInline(item);
+			if (inline !== void 0) {
+				lines.push(`${indent}${INDENT}${inline}`);
+				continue;
+			}
+			lines.push(...valueLines(item, indent + INDENT));
+		}
+		lines.push(`${indent}]`);
+		return lines;
+	}
+	const keys = Object.keys(value);
+	if (keys.length === 0) return [`${indent}{}`];
+	const lines = [`${indent}{`];
+	const inner = indent + INDENT;
+	for (const key of keys) {
+		const child = value[key] ?? null;
+		const inline = tryInline(child);
+		if (inline !== void 0) {
+			lines.push(`${inner}${keyText(key)}: ${inline}`);
+			continue;
+		}
+		if (typeof child === "string") {
+			lines.push(`${inner}${keyText(key)}:`);
+			for (const line of sanitizeText(child).split("\n")) lines.push(line.length === 0 ? "" : `${inner}${INDENT}${line}`);
+			continue;
+		}
+		const nested = blockLines(child, inner);
+		lines.push(`${inner}${keyText(key)}: ${(nested[0] ?? "").trimStart()}`.trimEnd(), ...nested.slice(1));
+	}
+	lines.push(`${indent}}`);
+	return lines;
+}
+function valueLines(value, indent) {
+	if (typeof value === "string") return sanitizeText(value).split("\n");
+	if (value === null || typeof value !== "object") return [String(value)];
+	return blockLines(value, indent);
+}
+/** Truncate every line that exceeds {@link MAX_LINE_CHARS}. */
+function capLines(text) {
+	return text.split("\n").map((line) => line.length > 200 ? `${line.slice(0, 199)}…` : line).join("\n");
+}
+/**
+* Render a completion value for the model: strings verbatim, everything else as a compact
+* `{key: value}` summary or an indented block — never `JSON.stringify` on the whole value, whose
+* escaping destroys exactly the content a reader needs (newlines, quotes, non-ASCII spacing).
+*/
+function renderModelValue(value) {
+	if (typeof value === "string") return capLines(sanitizeText(value));
+	if (value === null || typeof value !== "object") return String(value);
+	const inline = tryInline(value);
+	return capLines((inline !== void 0 ? [inline] : valueLines(value, "")).join("\n"));
+}
+//#endregion
+//#region src/tools/common.ts
+/**
+* Shared plumbing for the two model-facing PTC tools (`ptc_run_code`, `ptc_workflow`).
+*
+* Both tools are thin. They resolve the run's working directory, hand the program to
+* `runPtcProgram()` (T3), and turn the dispatcher's outcome into one of pi's two tool-result
+* shapes:
+*
+* - **success** — `content` carries one text block (logs, workflow narration, phases, then the
+*   completion value) and `details` carries the same facts structurally for rendering and logs;
+* - **failure** — the tool *throws* (pi's convention: `AgentTool.execute` — "Throw on failure
+*   instead of encoding errors in `content`"), with R1 §3's message shape
+*   `code run failed (<kind>): <message>` plus a `Captured output:` block.
+*
+* The dispatcher never rejects for program failures — it reports them as `outcome.error` — so
+* "did the run fail" is one check in one place, shared by both tools.
+*
+* The text block is the model's copy, so it is cleaned and laid out for reading (`./text.ts`:
+* ANSI stripped, control characters dropped, strings with real newlines kept multi-line) while
+* `details` stays raw for the TUI. See ADR-0012.
+*/
+/**
+* Binding names for one run: the built-ins this session actually has enabled (T7, #21).
+*
+* A PTC program must never reach further than the session it runs in — a session started
+* with `--tools read` or `--no-builtin-tools` must not be escapable through `tools.<name>`
+* calls. Names outside the built-in factory set are ignored: only tools this package can
+* build adapters for can be bound.
+*/
+function resolveBindingNames(activeToolNames) {
+	if (activeToolNames === void 0) return BUILTIN_BINDING_NAMES;
+	const active = new Set(activeToolNames);
+	return BUILTIN_BINDING_NAMES.filter((name) => active.has(name));
+}
+/**
+* One-line entry for the system prompt's "Available tools" section.
+*
+* Custom tools are omitted from that section unless they set this, which matters most in PTC mode:
+* there the two PTC surfaces are the *only* callable tools, so a prompt that lists no usable tool
+* would contradict the tool declarations. `promptGuidelines` cannot substitute for it — those
+* bullets land in the flat `Guidelines` section, which does not tell the model what it can call.
+*/
+const PTC_RUN_CODE_SNIPPET = "Run a TypeScript program that composes pi's tools in one shot (tools.<name>(args)); only its return value and console.log come back";
+const PTC_WORKFLOW_SNIPPET = "Run a structured TypeScript workflow with named phases, narration (log/phase) and structured concurrency (parallel/pipeline)";
+/**
+* Guidelines are appended flat to the `Guidelines` section with no tool-name prefix, so each bullet
+* must name its tool explicitly (pi's docs call this out; "Use this tool when…" is ambiguous).
+* These are the normal-mode hints — in PTC mode the injected briefing supersedes them.
+*/
+const PTC_TOOL_GUIDELINES = [
+	"Image-bearing tool results inside a program (a `tools.read` on a PNG, say) are attached to you after the run — never return image data as the completion value.",
+	"Use ptc_run_code when a task needs several tool calls whose intermediate output you do not need to see — gather it inside the program and return only the final value.",
+	"Use ptc_workflow instead of ptc_run_code when the work has named phases and the user benefits from seeing progress narration."
+];
+/** Tool name per worker surface — the names the model calls and reads in failure messages. */
+const SURFACE_TOOL_NAME = {
+	run_code: "ptc_run_code",
+	workflow: "ptc_workflow"
+};
+/**
+* Resolve the run's working directory from pi's tool execution context.
+*
+* Investigated against `@earendil-works/pi-coding-agent@0.86.1`: `execute`'s fifth parameter is
+* `ExtensionContext`, and the type *does* expose `cwd: string` — documented there as "Current
+* working directory" (`dist/core/extensions/types.d.ts`), the same value pi's own built-in tools
+* resolve relative paths against (`ToolRenderContext.cwd`, and the extension guide's
+* `resolve(ctx.cwd, params.path)` pattern). So the session cwd comes from pi, and this package
+* never has to guess from `process.cwd()`.
+*
+* The `process.cwd()` fallback stays for hand-built contexts (tests, or a future caller passing a
+* partial object); pi always supplies the field.
+*/
+function resolveToolCwd(ctx) {
+	const cwd = ctx?.cwd;
+	return typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+}
+/**
+* The captured-output lines R1 §3 appends when a run fails.
+*
+* Phases and narrations are prefixed because they are workflow bookkeeping rather than console
+* output; `ptc_run_code` has neither, so its block is exactly the `logs` join R1 describes.
+*/
+function capturedOutputLines(outcome) {
+	return [
+		...outcome.phases.map((title) => `[phase] ${sanitizeText(title)}`),
+		...outcome.narrations.map((message) => `[log] ${sanitizeText(message)}`),
+		...outcome.logs.map((line) => sanitizeText(line))
+	];
+}
+/**
+* Build the error a failed run is surfaced with (R1 §3's `CodeRunFailedError` message).
+*
+* The model must be able to fix its program from this message alone: the error kind and message
+* explain what broke, and the captured output shows how far the program got before it did. There
+* is no `sandbox` text and no escalation guidance — ADR-0007 ships no OS sandbox, so the only
+* failure classes are the protocol ones.
+*/
+function codeRunFailedError(outcome) {
+	const error = outcome.error;
+	if (error === void 0) return /* @__PURE__ */ new Error("internal error: a successful PTC run was rendered as a failure");
+	const captured = capturedOutputLines(outcome);
+	const block = captured.length === 0 ? "" : `\nCaptured output:\n${captured.join("\n")}`;
+	const failure = new Error(sanitizeText(`code run failed (${error.kind}): ${error.message}${block}`));
+	failure.name = "CodeRunFailedError";
+	return failure;
+}
+/**
+* Write the untruncated text block to a temp file and return its path.
+*
+* Mirrors what pi's own `bash` does with a long output (its `fullOutputPath`): the run is the only
+* place the text ever existed, so a file under the OS temp dir is the difference between "the rest is
+* gone" and "the rest is one `tools.read` away".
+*/
+function writeFullOutput(text) {
+	const filePath = join(tmpdir(), `pi-ptc-output-${randomUUID()}.txt`);
+	writeFileSync(filePath, text, "utf8");
+	return filePath;
+}
+/**
+* The `[Showing … Full output: path]` footer pi's built-ins use, worded for the same numbers.
+*
+* `truncatedBy` decides the wording: a line cut reports the line range, a byte cut also names the
+* ceiling, and a single oversized last line reports its own size — exactly what `bash` prints.
+*/
+function truncationFooter(truncation, fullOutputPath) {
+	const startLine = truncation.totalLines - truncation.outputLines + 1;
+	const endLine = truncation.totalLines;
+	if (truncation.lastLinePartial) return `[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine}. Full output: ${fullOutputPath}]`;
+	if (truncation.truncatedBy === "lines") return `[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${fullOutputPath}]`;
+	return `[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${fullOutputPath}]`;
+}
+/**
+* Render one successful outcome as pi's tool result.
+*
+* `content` is ordered the way a reader reconstructs the run: the phase roll-up, then workflow
+* narration, then console output, then the completion value, then warnings. Empty runs get R1's
+* placeholder (`(run_code completed with no output)`) so the model always sees a non-empty text
+* block — a tool result with nothing in it looks like a harness failure.
+*
+* `details` is deliberately the *uncleaned* copy: logs keep their ANSI so the TUI can still
+* colour them, and `result` stays structured for `render.ts`.
+*/
+function renderToolResult(input) {
+	const { outcome, surface } = input;
+	const warnings = [...input.warnings ?? []];
+	const images = outcome.images ?? [];
+	const parts = [];
+	if (outcome.phases.length > 0) parts.push(`Phases: ${outcome.phases.map((title) => sanitizeText(title)).join(" → ")}`);
+	if (outcome.narrations.length > 0) parts.push(outcome.narrations.map((message) => sanitizeText(message)).join("\n"));
+	if (outcome.logs.length > 0) parts.push(outcome.logs.map((line) => sanitizeText(line)).join("\n"));
+	if (outcome.value !== void 0) parts.push(renderModelValue(outcome.value));
+	for (const warning of warnings) parts.push(`Warning: ${sanitizeText(warning)}`);
+	const built = parts.length > 0 ? parts.join("\n") : `(${SURFACE_TOOL_NAME[surface]} completed with no output)`;
+	const truncation = truncateTail(built, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: DEFAULT_MAX_BYTES
+	});
+	let fullOutputPath;
+	let text = truncation.content;
+	if (truncation.truncated) {
+		fullOutputPath = writeFullOutput(built);
+		text += `\n\n${truncationFooter(truncation, fullOutputPath)}`;
+	}
+	return {
+		content: [{
+			type: "text",
+			text
+		}, ...images.map((image) => ({
+			type: "image",
+			data: image.data,
+			mimeType: image.mimeType
+		}))],
+		details: {
+			surface,
+			logs: [...outcome.logs],
+			narrations: [...outcome.narrations],
+			phases: [...outcome.phases],
+			warnings,
+			...outcome.value === void 0 ? {} : { result: outcome.value },
+			durationMs: input.durationMs,
+			imageCount: images.length,
+			...fullOutputPath === void 0 ? {} : { fullOutputPath }
+		}
+	};
+}
+//#endregion
+//#region src/tools/render.ts
+/** Call-row label per surface; `ptc_workflow` gets its own so the two rows stay tellable apart. */
+const TOOL_TITLE = {
+	run_code: "PTC",
+	workflow: "PTC workflow"
+};
+/**
+* Tree-connector layout. The call row owns column 0–2 (`└─ `); everything below it sits at column 3.
+* Children are siblings of the call's content (the summary line `→ {hint}`), so a child row needs a
+* connector to distinguish itself from the summary — and a continuation prefix to distinguish its
+* own wrapped lines from the child's first line.
+*
+*  - Root call row:         `└─ PTC  …`
+*  - Root continuation:     `   → {hint}` or `   failed: …`    (summary; same column as children)
+*  - First / middle child:  `   ├─ code    …`
+*  - First / middle cont.:  `   │          …`
+*  - Last child:            `   └─ image   …`
+*  - Last cont.:            `      …`         (no connector — same shape as a wrapped value line)
+*
+* `TREE_INDENT` (3 spaces) is the column children and root continuations share.
+*/
+const TREE_ROOT = "└─ ";
+const TREE_ROOT_CONT = "   ";
+const TREE_INDENT = "   ";
+const TREE_FIRST = "├─ ";
+const TREE_LAST = "└─ ";
+const TREE_CONT_FIRST = "│  ";
+const TREE_CONT_LAST = "   ";
+/**
+* Gutter width for child labels. `code` / `out` / `value` / `warn` / `image` are 3–5 chars; `phases`
+* is 6 — pad to 8 so the longest label gets two trailing spaces before its content.
+*/
+const LABEL_WIDTH = 8;
+const MAX_CODE_LINES_EXPANDED = 3;
+const MAX_CODE_LINE_CHARS = 120;
+const MAX_LOG_LINES_EXPANDED = 12;
+const MAX_PHASES_EXPANDED = 8;
+const MAX_WARNINGS_EXPANDED = 4;
+const MAX_RESULT_HINT_CHARS = 60;
+const MAX_ERROR_CHARS = 120;
+/**
+* A `Component` that right-aligns one meta segment per line.
+*
+* Stateless: it holds already-styled strings and pads them at render time, so pi can re-render at a
+* new width (terminal resize) without any invalidation bookkeeping.
+*/
+var PtcRow = class {
+	lines;
+	constructor(lines) {
+		this.lines = lines;
+	}
+	/** Part of the `Component` contract; nothing is cached, so nothing has to be dropped. */
+	invalidate() {}
+	render(width) {
+		const safeWidth = Math.max(1, Math.floor(width));
+		return this.lines.map((line) => alignRow(line, safeWidth));
+	}
+};
+/**
+* Lay out one row inside `width` columns.
+*
+* With no meta segment the line is simply truncated. With one, the meta is what must survive — a
+* count that has been cut in half (`• 19 outpu…`) tells the reader nothing — so the left side gives
+* up room first, and only a meta wider than the whole viewport is truncated itself.
+*/
+function alignRow(line, width) {
+	const { left, right } = line;
+	if (right === void 0) return truncateToWidth(left, width, "…");
+	const rightWidth = visibleWidth(right);
+	if (rightWidth >= width) return truncateToWidth(right, width, "…");
+	const leftText = truncateToWidth(left, Math.max(0, width - rightWidth - 1), "…");
+	const pad = Math.max(1, width - rightWidth - visibleWidth(leftText));
+	return leftText + " ".repeat(pad) + right;
+}
+/** Truncate `s` to `n` chars, appending `…` when the input was longer. */
+function truncateChars(s, n) {
+	return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+/** First non-blank line of a block of text, sanitized and capped. */
+function firstLine(value) {
+	return truncateChars((sanitizeText(value).split("\n").find((candidate) => candidate.trim().length > 0) ?? "").trim(), MAX_ERROR_CHARS);
+}
+/** `n` rendered as `1.2s` / `850ms` (so users can tell short from long at a glance). */
+function formatDuration(ms) {
+	if (ms < 1e3) return `${ms}ms`;
+	return `${(ms / 1e3).toFixed(2).replace(/\.?0+$/, "")}s`;
+}
+/** `3 phases` / `1 phase` — singular and plural are both reachable from a real run. */
+function plural(count, noun) {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+/**
+* Pull the first line of code that is actually doing something — not a leading comment, blank
+* line, or import. Used as the call row's fallback when the model sent no description.
+*/
+function firstMeaningfulCodeLine(code) {
+	for (const raw of code.split("\n")) {
+		const line = raw.trim();
+		if (line.length === 0) continue;
+		if (line.startsWith("//")) continue;
+		if (line.startsWith("/*")) continue;
+		if (line.startsWith("*")) continue;
+		return truncateChars(line.replace(/\s*\/\/.*$/, ""), MAX_CODE_LINE_CHARS);
+	}
+}
+/**
+* The completion value as a single line a human can read: the value itself while it stays short
+* and single-line, otherwise its shape (`{version, node}`, `Array(3)`).
+*
+* A multi-line string contributes its first non-blank line plus a `+N lines` tail, which is the
+* whole difference between one readable row and the escaped wall this replaces.
+*/
+function resultHint(value) {
+	if (value === void 0) return void 0;
+	if (typeof value === "string") {
+		const lines = sanitizeText(value).split("\n");
+		const first = lines.find((line) => line.trim().length > 0)?.trim() ?? "";
+		const extra = lines.length > 1 ? ` (+${lines.length - 1} lines)` : "";
+		if (first.length === 0 && extra.length === 0) return `""`;
+		return truncateChars(first, MAX_RESULT_HINT_CHARS) + extra;
+	}
+	if (value === null || typeof value !== "object") return String(value);
+	const inline = renderModelValue(value);
+	if (!inline.includes("\n") && inline.length <= MAX_RESULT_HINT_CHARS) return inline;
+	if (Array.isArray(value)) return `Array(${value.length})`;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return "{}";
+	return `{${keys.slice(0, 4).join(", ")}${keys.length > 4 ? `, +${keys.length - 4}` : ""}}`;
+}
+/**
+* Right-aligned meta: the run's countable facts, in the order a reader asks for them — how much
+* output, how long it took, how many phases (workflow), and anything that went wrong.
+*/
+function metaText(details, theme) {
+	if (details === void 0) return void 0;
+	const segments = [];
+	const outputLines = details.logs.length + details.narrations.length;
+	if (outputLines > 0) segments.push(theme.fg("dim", plural(outputLines, "output line")));
+	if (details.imageCount > 0) segments.push(theme.fg("toolOutput", plural(details.imageCount, "image")));
+	if (details.surface === "workflow" && details.phases.length > 0) segments.push(theme.fg("dim", plural(details.phases.length, "phase")));
+	if (details.warnings.length > 0) segments.push(theme.fg("warning", plural(details.warnings.length, "warning")));
+	if (details.fullOutputPath !== void 0) segments.push(theme.fg("warning", "truncated"));
+	segments.push(theme.fg("dim", formatDuration(details.durationMs)));
+	return `${theme.fg("dim", "•")} ${segments.join(theme.fg("dim", " · "))}`;
+}
+/** Render one child block as `RowLine[]`, with `├─` / `│` / `└─` connectors decided by position. */
+function renderChildBlock(child, isLast, theme) {
+	const firstPrefix = TREE_INDENT + (isLast ? TREE_LAST : TREE_FIRST);
+	const contPrefix = TREE_INDENT + (isLast ? TREE_CONT_LAST : TREE_CONT_FIRST);
+	const gutter = " ".repeat(LABEL_WIDTH);
+	const rows = [];
+	const first = child.lines[0] ?? "";
+	rows.push({ left: `${firstPrefix}${child.label.padEnd(LABEL_WIDTH)}${theme.fg("dim", first)}` });
+	for (let i = 1; i < child.lines.length; i++) rows.push({ left: `${contPrefix}${gutter}${theme.fg("dim", child.lines[i] ?? "")}` });
+	if (child.more !== void 0 && child.more > 0) rows.push({ left: `${contPrefix}${gutter}…+${child.more} more lines` });
+	return rows;
+}
+/** A JSON value is "expandable" when it is a non-empty object or array. */
+function isExpandableContainer(value) {
+	if (value === null || typeof value !== "object") return false;
+	if (Array.isArray(value)) return value.length > 0;
+	return Object.keys(value).length > 0;
+}
+/** Object keys that read as identifiers are left unquoted; the rest get JSON quoting. */
+const TREE_BARE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function treeFormatKey(key) {
+	return TREE_BARE_KEY.test(key) ? key : JSON.stringify(key);
+}
+/** A scalar JSON value as a single readable token; strings are JSON-quoted, newlines folded. */
+function treeScalarPreview(value, maxChars) {
+	if (value === null) return "null";
+	if (typeof value === "boolean" || typeof value === "number") return String(value);
+	if (typeof value === "string") {
+		const sanitized = sanitizeText(value);
+		if (sanitized.length === 0) return "\"\"";
+		if (sanitized.includes("\n")) {
+			const head = truncateChars(sanitized.replace(/\n/g, " "), Math.max(2, maxChars - 5));
+			return JSON.stringify(head) + "…";
+		}
+		if (sanitized.length + 2 <= maxChars) return JSON.stringify(sanitized);
+		return JSON.stringify(truncateChars(sanitized, Math.max(2, maxChars - 5))) + "…";
+	}
+	return "?";
+}
+function treeIsScalarJson(value) {
+	return value === null || typeof value !== "object";
+}
+/** Try to render a container as a one-liner bracket form ({k: v} / [v, v]); undefined when it does not fit or children are deep. */
+function treeInlinePreview(value, maxChars) {
+	if (maxChars < 8) return void 0;
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		if (value.length > 5 || !value.every(treeIsScalarJson)) return void 0;
+		const inline = "[" + value.map((item) => treeScalarPreview(item, Math.max(2, Math.floor(maxChars / 4)))).join(", ") + "]";
+		return inline.length <= maxChars ? inline : void 0;
+	}
+	if (value === null || typeof value !== "object") return void 0;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return "{}";
+	if (keys.length > 5 || !Object.values(value).every(treeIsScalarJson)) return void 0;
+	const inline = "{" + keys.map((key) => {
+		const child = value[key] ?? null;
+		return treeFormatKey(key) + ": " + treeScalarPreview(child, Math.max(2, Math.floor(maxChars / 4)));
+	}).join(", ") + "}";
+	return inline.length <= maxChars ? inline : void 0;
+}
+/**
+* Append one pre-prefixed tree row to out, recursing for containers. Each level passes the
+* continuation indent its children should use; the connector itself encodes "more siblings".
+*/
+function treeAppendNode(value, label, parentPrefix, isLast, maxDepth, maxChildren, maxLineChars, depth, out) {
+	const ownPrefix = parentPrefix + (isLast ? "└─ " : "├─ ");
+	const continuation = parentPrefix + (isLast ? "   " : "│  ");
+	if (depth >= maxDepth) {
+		out.push(treeTruncateIndent(ownPrefix + label + "…", maxLineChars));
+		return;
+	}
+	if (Array.isArray(value) && value.length === 0) {
+		out.push(treeTruncateIndent(ownPrefix + label + "[]", maxLineChars));
+		return;
+	}
+	if (!Array.isArray(value) && value !== null && typeof value === "object" && Object.keys(value).length === 0) {
+		out.push(treeTruncateIndent(ownPrefix + label + "{}", maxLineChars));
+		return;
+	}
+	if (value === null || typeof value !== "object") {
+		const budget = Math.max(0, maxLineChars - visibleWidth(ownPrefix) - label.length);
+		out.push(treeTruncateIndent(ownPrefix + label + treeScalarPreview(value, budget), maxLineChars));
+		return;
+	}
+	const inline = treeInlinePreview(value, Math.max(0, maxLineChars - visibleWidth(ownPrefix) - label.length));
+	if (inline !== void 0) {
+		out.push(treeTruncateIndent(ownPrefix + label + inline, maxLineChars));
+		return;
+	}
+	const listLike = Array.isArray(value);
+	const childCount = listLike ? value.length : Object.keys(value).length;
+	let header;
+	if (listLike) header = "Array(" + childCount + ")";
+	else header = childCount > maxChildren ? "{" + maxChildren + " of " + childCount + "}" : "{" + childCount + " keys}";
+	out.push(treeTruncateIndent(ownPrefix + label + header, maxLineChars));
+	const limit = Math.min(maxChildren, childCount);
+	if (listLike) for (let index = 0; index < limit; index += 1) {
+		const isChildLast = index === limit - 1 && childCount <= limit;
+		treeAppendNode(value[index] ?? null, "[" + index + "] ", continuation, isChildLast, maxDepth, maxChildren, maxLineChars, depth + 1, out);
+	}
+	else {
+		const keys = Object.keys(value);
+		for (let index = 0; index < limit; index += 1) {
+			const isChildLast = index === limit - 1 && childCount <= limit;
+			const key = keys[index];
+			treeAppendNode(value[key] ?? null, treeFormatKey(key) + ": ", continuation, isChildLast, maxDepth, maxChildren, maxLineChars, depth + 1, out);
+		}
+	}
+	if (childCount > limit) {
+		const tail = listLike ? "items" : "keys";
+		out.push(treeTruncateIndent(continuation + "└─ …+" + (childCount - limit) + " more " + tail, maxLineChars));
+	}
+}
+/** Truncate a rendered row, preserving the leading tree-prefix indent (│/├/└ etc.). */
+function treeTruncateIndent(line, maxLineChars) {
+	if (visibleWidth(line) <= maxLineChars) return line;
+	const match = line.match(/^([\s│├└─]*)/);
+	const indent = match && match[1] ? match[1] : "";
+	const indentWidth = visibleWidth(indent);
+	const budget = Math.max(0, maxLineChars - indentWidth - 1);
+	let body = "";
+	let used = 0;
+	for (const ch of line.slice(indent.length)) {
+		const w = visibleWidth(ch);
+		if (used + w > budget) break;
+		body += ch;
+		used += w;
+	}
+	return indent + body + "…";
+}
+/**
+* Render a JSON value as an array of indented tree rows.
+*
+* Each row is a complete prefixed line ready to live under the call row's "   " indent
+* (TREE_ROOT_CONT): root children start at "├─ " / "└─ ", deeper levels add their own
+* connectors on top of the continuation bar. Caller supplies the row's TREE_ROOT_CONT — a
+* row that starts with "├─ " lands at column 3, exactly where other call-row children sit.
+*
+* Empty / scalar values return a one-row preview; non-empty containers recurse.
+*/
+function renderValueTree(value, options = {}) {
+	const maxDepth = options.maxDepth ?? 4;
+	const maxChildren = options.maxChildren ?? 6;
+	const maxLineChars = options.maxLineChars ?? 120;
+	const moreAfter = options.moreAfter === true;
+	if (!isExpandableContainer(value)) {
+		if (value !== null && typeof value === "object") return [Array.isArray(value) ? "[]" : "{}"];
+		return [treeScalarPreview(value, maxLineChars)];
+	}
+	const out = [];
+	if (Array.isArray(value)) {
+		const total = value.length;
+		const limit = Math.min(maxChildren, total);
+		for (let index = 0; index < limit; index += 1) {
+			const isLast = !moreAfter && index === limit - 1 && total <= limit;
+			treeAppendNode(value[index] ?? null, "[" + index + "] ", "", isLast, maxDepth, maxChildren, maxLineChars, 0, out);
+		}
+		if (total > limit) out.push((moreAfter ? "├─ " : "└─ ") + "…+" + (total - limit) + " more items");
+		return out;
+	}
+	const keys = Object.keys(value);
+	const total = keys.length;
+	const limit = Math.min(maxChildren, total);
+	for (let index = 0; index < limit; index += 1) {
+		const isLast = !moreAfter && index === limit - 1 && total <= limit;
+		const key = keys[index];
+		treeAppendNode(value[key] ?? null, treeFormatKey(key) + ": ", "", isLast, maxDepth, maxChildren, maxLineChars, 0, out);
+	}
+	if (total > limit) out.push((moreAfter ? "├─ " : "└─ ") + "…+" + (total - limit) + " more keys");
+	return out;
+}
+/**
+* One-line tool-call header: the tree root, then the tool label, then the model's own description.
+*
+* The description is the only detail that gets to sit next to the label — the previous renderer
+* appended the first code line as well, which is what made the call row read as a paragraph rather
+* than a heading. The code is one `ctrl+e` away in the expanded view.
+*/
+function renderPtcToolCall(args, theme, surface = "run_code") {
+	const description = (typeof args.description === "string" && args.description.trim().length > 0 ? args.description.trim() : args.meta?.name) ?? "";
+	const fallback = firstMeaningfulCodeLine(args.code ?? args.script ?? "");
+	const detail = description.length > 0 ? description : fallback ?? "(no description)";
+	const left = `${theme.fg("toolTitle", theme.bold(TOOL_TITLE[surface]))} ${theme.fg("accent", detail)}`;
+	return new PtcRow([{ left: `${TREE_ROOT}${left}` }]);
+}
+/** Text body of a failed run — pi surfaces the thrown error in the first text block. */
+function errorText(result) {
+	const text = result.content?.find((block) => block.type === "text" && (block.text ?? "").length > 0);
+	return firstLine(text?.text ?? "") || "failed";
+}
+/**
+* The result area under the call row.
+*
+* One of four shapes, all hanging at column 3 so a column of PTC rows stays scannable:
+* - error:                    one line with the failure reason in the error colour.
+* - no completion value:      one line, "done".
+* - scalar / empty container: one line, `→ <hint>` (or "done" for null).
+* - non-empty container:      a tree of rows (recursive `├─/└─/│` connectors from
+*                             `renderValueTree`), with the right-aligned meta pinned to
+*                             the tree's first row. ADR-0013 §5.
+*
+* Each row returns its left-side text WITHOUT the `TREE_ROOT_CONT` prefix being in scope;
+* we prepend it here so the same output works for both surfaces.
+*/
+function resultArea(result, isError, theme, moreAfter = false) {
+	const right = metaText(result.details, theme);
+	const attachRight = (row) => right === void 0 ? row : {
+		...row,
+		right
+	};
+	if (isError) return [attachRight({ left: `${TREE_ROOT_CONT}${theme.fg("error", `failed: ${errorText(result)}`)}` })];
+	const value = result.details?.result;
+	if (value === void 0) return [attachRight({ left: `${TREE_ROOT_CONT}${theme.fg("muted", "done")}` })];
+	if (isExpandableContainer(value)) return renderValueTree(value, {
+		maxDepth: 4,
+		maxChildren: 6,
+		maxLineChars: 120,
+		moreAfter
+	}).map((line, index) => {
+		const row = { left: `${TREE_ROOT_CONT}${line}` };
+		return index === 0 && right !== void 0 ? {
+			...row,
+			right
+		} : row;
+	});
+	const hint = resultHint(value);
+	if (hint === void 0) return [attachRight({ left: `${TREE_ROOT_CONT}${theme.fg("muted", "done")}` })];
+	return [attachRight({ left: `${TREE_ROOT_CONT}${theme.fg("dim", `→ ${hint}`)}` })];
+}
+/**
+* Collapsed result: the result area only.
+*
+* A scalar row fits on one line; a container value expands into a tree (1+ lines). Right-aligned
+* meta (output lines / phases / warnings / duration) is pinned to the first row of the area.
+*/
+function renderPtcToolResultCollapsed(result, isError, theme) {
+	return new PtcRow(resultArea(result, isError, theme));
+}
+/**
+* Expanded view: the result area, then the run's children as labelled blocks.
+*
+* Each child block opens with a fixed-width gutter (`code`, `phases`, `log`, `out`, `warn`,
+* `image`); the `value` block is gone — for a scalar value the result area already shows the
+* hint, and for a container value the area shows the full tree (ADR-0013 §5). Children that
+* overflow cap themselves and report `+N more lines`; the view stays bounded.
+*/
+function renderPtcToolResultExpanded(result, args, isError, theme) {
+	if (isError) {
+		const lines = resultArea(result, true, theme);
+		const text = sanitizeText(result.content?.find((block) => block.type === "text")?.text ?? errorText(result));
+		for (const line of text.split("\n").slice(0, MAX_LOG_LINES_EXPANDED)) lines.push({ left: `${TREE_ROOT_CONT}${theme.fg("error", line)}` });
+		return new PtcRow(lines);
+	}
+	const details = result.details;
+	const children = [];
+	const code = args.code ?? args.script ?? "";
+	if (code.length > 0) {
+		const codeLines = code.split("\n").map((line) => truncateChars(line, MAX_CODE_LINE_CHARS));
+		const shown = codeLines.slice(0, MAX_CODE_LINES_EXPANDED);
+		children.push({
+			label: "code",
+			lines: shown,
+			...codeLines.length > shown.length ? { more: codeLines.length - shown.length } : {}
+		});
+	}
+	if (details !== void 0 && details.surface === "workflow" && details.phases.length > 0) {
+		const shown = details.phases.slice(0, MAX_PHASES_EXPANDED);
+		const tail = details.phases.length > shown.length ? " …" : "";
+		children.push({
+			label: "phases",
+			lines: [`${shown.join(" → ")}${tail}`]
+		});
+	}
+	if (details !== void 0 && details.narrations.length > 0) {
+		const shown = details.narrations.slice(0, MAX_LOG_LINES_EXPANDED);
+		children.push({
+			label: "log",
+			lines: shown.map((message) => sanitizeText(message)),
+			...details.narrations.length > shown.length ? { more: details.narrations.length - shown.length } : {}
+		});
+	}
+	if (details !== void 0 && details.logs.length > 0) {
+		const shown = details.logs.slice(0, MAX_LOG_LINES_EXPANDED);
+		children.push({
+			label: "out",
+			lines: shown.map((line) => sanitizeText(line)),
+			...details.logs.length > shown.length ? { more: details.logs.length - shown.length } : {}
+		});
+	}
+	if (details !== void 0 && details.warnings.length > 0) {
+		const shown = details.warnings.slice(0, MAX_WARNINGS_EXPANDED);
+		children.push({
+			label: "warn",
+			lines: shown.map((warning) => sanitizeText(warning)),
+			...details.warnings.length > shown.length ? { more: details.warnings.length - shown.length } : {}
+		});
+	}
+	if (details !== void 0 && details.imageCount > 0) {
+		const desc = details.imageCount === 1 ? "1 image attached" : `${details.imageCount} images attached`;
+		children.push({
+			label: "image",
+			lines: [desc]
+		});
+	}
+	const lines = resultArea(result, false, theme, children.length > 0);
+	for (let index = 0; index < children.length; index += 1) {
+		const isLast = index === children.length - 1;
+		lines.push(...renderChildBlock(children[index] ?? {
+			label: "",
+			lines: []
+		}, isLast, theme));
+	}
+	return new PtcRow(lines);
+}
+//#endregion
+//#region src/tools/run-code.ts
+/**
+* `ptc_run_code` — the unstructured PTC surface.
+*
+* The model writes the body of an async function; inside it, pi's built-in tools are reachable as
+* `tools.<name>(args)` (all seven: read, bash, edit, write, grep, find, ls — ADR-0005's set), and
+* the program's return value plus `console.log` output are what come back. There are no helpers
+* on this surface: `log` / `phase` / `parallel` / `pipeline` belong to `ptc_workflow` (G1 #13 →
+* decision B; a call to a helper that does not exist is a plain `ReferenceError` through the
+* normal code-run error path).
+*
+* Scope notes, so this stays a faithful subset of DSH's `run_code`:
+* - DSH's `sandbox_permissions` / `justification` are deliberately absent — they exist to request
+*   a wider sandbox from an approval pipeline this package does not have (ADR-0007 ships no OS
+*   sandbox, and the map decision on #8 dropped the approval path).
+* - `timeoutMs: 0` does not disable the deadline; it falls back to `DEFAULT_CONFIG.timeoutMs`,
+*   exactly as DSH's resolver does (R1 §3). The description names the default and the ceiling.
+*/
+const DESCRIPTION$1 = [
+	"Run a TypeScript program that composes pi's tools in one shot. Required arguments: `code` —",
+	"the body of an async function (top-level `return` and `await` work; type annotations are",
+	"advisory, the code runs type-stripped) — and `description`, a 5-10 word summary of what the",
+	"program does.",
+	"",
+	"Inside the program, call this session's enabled built-in tools as `tools.<name>(args)` — e.g.",
+	"`await tools.read({ path: \"src/index.ts\" })` or `await tools.bash({ command: \"npm test\" })`.",
+	"The bound names mirror the session's active tools (a default session has `read`, `bash`, `edit`,",
+	"`write`); calling a name that is not bound rejects with an error the program can catch, and",
+	"independent calls may overlap under `Promise.all`.",
+	"",
+	"Only the program's return value and its `console.log` output come back. This surface has no",
+	"helpers: `log` / `phase` / `parallel` / `pipeline` exist only in `ptc_workflow`.",
+	"",
+	"Image-bearing tool results inside the program (a `tools.read` on a PNG, say) are attached to you",
+	"after the run, so never return image data as the completion value — that only spends your context",
+	"on base64."
+].join("\n");
+const PARAMETERS$1 = Type.Object({
+	code: Type.String({ description: "The program: the body of an async TypeScript function." }),
+	description: Type.String({ description: "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI)." }),
+	timeoutMs: Type.Optional(Type.Number({ description: `Elapsed deadline in milliseconds for the whole run, including tool calls. Omit it (or pass 0) for the default of ${DEFAULT_CONFIG.timeoutMs / 1e3} s; anything above ${DEFAULT_CONFIG.maxTimeoutMs / 1e3} s is capped.` }))
+});
+/**
+* Build the `ptc_run_code` tool definition.
+*
+* Called once by the extension factory. Every run gets a fresh worker and a fresh binding table
+* built against the run's own cwd, so two concurrent calls cannot share state.
+*/
+function createPtcRunCodeTool(options = {}) {
+	return defineTool({
+		name: "ptc_run_code",
+		label: "PTC Run Code",
+		description: DESCRIPTION$1,
+		promptSnippet: PTC_RUN_CODE_SNIPPET,
+		promptGuidelines: [...PTC_TOOL_GUIDELINES],
+		parameters: PARAMETERS$1,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const cwd = resolveToolCwd(ctx);
+			const names = resolveBindingNames(options.getBindingSourceNames?.());
+			const startedAt = Date.now();
+			const outcome = await runPtcProgram({
+				code: params.code,
+				surface: "run_code",
+				cwd,
+				bindings: createBuiltinBindings({
+					cwd,
+					names
+				}),
+				...params.timeoutMs === void 0 ? {} : { timeoutMs: params.timeoutMs },
+				...signal === void 0 ? {} : { signal },
+				...options.config === void 0 ? {} : { config: options.config }
+			});
+			if (outcome.error !== void 0) throw codeRunFailedError(outcome);
+			return renderToolResult({
+				outcome,
+				surface: "run_code",
+				durationMs: Date.now() - startedAt
+			});
+		},
+		renderCall(args, theme) {
+			return renderPtcToolCall(args, theme, "run_code");
+		},
+		renderResult(result, options, theme, context) {
+			if (options.expanded) return renderPtcToolResultExpanded(result, context.args, context.isError, theme);
+			return renderPtcToolResultCollapsed(result, context.isError, theme);
+		}
+	});
+}
+//#endregion
+//#region src/tools/workflow.ts
+/**
+* `ptc_workflow` — the structured PTC surface.
+*
+* Same worker, same bindings, same Node surface as `ptc_run_code`; what it adds is a plan
+* (`meta` with an ordered phase list), plain-JSON input (`args`, bound as the program's `args`
+* global) and the four workflow helpers: `log` / `phase` / `parallel` / `pipeline` (G1 #13 →
+* decision B — there is no `agent()`, not even a stub).
+*
+* Three decisions recorded here rather than re-litigated per call:
+* - **Language**: the same type-stripping pipeline as `ptc_run_code`. The worker compiles both
+*   surfaces through one `compileProgram`, and the pipeline is type-*strip* only — it adds no
+*   runtime semantics that a workflow could not tolerate. There is no JS-only mode because there
+*   is no concrete reason for one (the old pi-ptc "JS-only" idea is explicitly not inherited).
+* - **Phase strictness**: warning, not error. A `phase(title)` outside `meta.phases` is a plan
+*   drift — usually a typo or a forgotten declaration — but the run has already happened by the
+*   time the titles are known, and failing then would discard a completed result over a cosmetic
+*   mismatch. Each distinct unlisted title is reported once, as a `Warning:` line in `content`
+*   and in `details.warnings`. When `meta.phases` is absent there is no declared plan to drift
+*   from, so nothing is reported.
+* - **`args`**: validated as plain JSON before dispatch (see `validateWorkflowArgs`), because a
+*   function/symbol/`undefined`/cycle would otherwise be silently dropped or mangled by the
+*   structured clone on its way to the worker.
+*/
+const DESCRIPTION = [
+	"Run a structured TypeScript workflow: a named plan that reports phases and narration as it",
+	"goes. `script` is the body of an async function, `meta` names it (`{ name, description, phases? }`,",
+	"where `phases` is the ordered plan), and optional `args` is plain-JSON input bound to the",
+	"program's `args` global.",
+	"",
+	"Helpers inside the script: `log(message)` narrates progress; `phase(title)` frames the workflow",
+	"(titles outside `meta.phases` are reported as warnings); `parallel(thunks)` runs thunks",
+	"concurrently, a failed item becoming `null`; `pipeline(items, ...stages)` chains stages per item",
+	"with the same per-item `null` on failure. There is no `agent()` helper.",
+	"",
+	"Tools are reachable as `tools.<name>(args)` exactly as in `ptc_run_code`, and the bound names",
+	"mirror the session's enabled tools. What comes back is the script's return value, its",
+	"`log`/`phase` narration and its `console.log` output.",
+	"",
+	"Image-bearing tool results inside the script are attached to you after the run — never return",
+	"image data as the script's value."
+].join("\n");
+const PARAMETERS = Type.Object({
+	meta: Type.Object({
+		name: Type.String({ description: "Short workflow name, shown in the UI." }),
+		description: Type.String({ description: "What this workflow does, in active voice." }),
+		phases: Type.Optional(Type.Array(Type.Object({ name: Type.String({ description: "Phase title, matched against phase(title) calls." }) }), { description: "Ordered plan of the workflow's phases. phase() titles outside this list are reported as warnings." }))
+	}, { description: "Workflow metadata: what this run is and which phases it declares." }),
+	script: Type.String({ description: "The program: the body of an async TypeScript function." }),
+	args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Plain-JSON input bound to the program's `args` global. No functions, symbols, undefined values or cycles." }))
+});
+function describeValue(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return `a ${typeof value}`;
+}
+/**
+* Reject anything that is not plain JSON, with a path-qualified reason.
+*
+* The rule is the worker's own result rule (`toJsonValue`) applied one direction earlier, so both
+* ends agree on what "plain JSON" means: objects with `Object.prototype` (or null), arrays,
+* strings, finite numbers, booleans and null. Class instances, functions, symbols, bigints,
+* non-finite numbers, circular references and `undefined` values are all rejected — `undefined`
+* because the ticket calls it out and because a structured clone would drop it silently, leaving
+* the script reading a key that is not there.
+*/
+function validateWorkflowArgs(args) {
+	if (args === void 0) return;
+	if (typeof args !== "object" || args === null || Array.isArray(args)) throw new TypeError(`ptc_workflow args must be a plain JSON object, received ${describeValue(args)}`);
+	for (const key of Object.keys(args)) {
+		const problem = findJsonProblem(args[key], `args.${key}`, /* @__PURE__ */ new Set());
+		if (problem !== void 0) throw new TypeError(`ptc_workflow args must be plain JSON: ${problem}`);
+	}
+}
+/** Path-qualified reason a value cannot cross the wire as plain JSON, or `undefined` when it can. */
+function findJsonProblem(value, path, seen) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return void 0;
+	if (typeof value === "undefined") return `${path} is undefined`;
+	if (typeof value === "number") return Number.isFinite(value) ? void 0 : `${path} is ${String(value)}, which is not representable as JSON`;
+	if (typeof value !== "object") return `${path} is ${describeValue(value)}`;
+	const container = value;
+	if (seen.has(container)) return `${path} is a circular reference`;
+	seen.add(container);
+	try {
+		if (Array.isArray(container)) {
+			for (let index = 0; index < container.length; index += 1) {
+				const problem = findJsonProblem(container[index], `${path}[${index}]`, seen);
+				if (problem !== void 0) return problem;
+			}
+			return;
+		}
+		const prototype = Object.getPrototypeOf(container);
+		if (prototype !== Object.prototype && prototype !== null) {
+			const name = container.constructor?.name;
+			return `${path} is a ${typeof name === "string" && name.length > 0 ? name : "non-plain object"}, not plain JSON`;
+		}
+		for (const key of Object.keys(container)) {
+			const problem = findJsonProblem(container[key], `${path}.${key}`, seen);
+			if (problem !== void 0) return problem;
+		}
+		return;
+	} finally {
+		seen.delete(container);
+	}
+}
+/**
+* Collect the plan-drift warnings for one workflow run: distinct `phase()` titles the declared
+* `meta.phases` list does not mention, in first-seen order.
+*/
+function unlistedPhaseWarnings(outcome, declared) {
+	if (declared === void 0 || declared.length === 0) return [];
+	const known = new Set(declared);
+	const reported = /* @__PURE__ */ new Set();
+	const warnings = [];
+	for (const title of outcome.phases) {
+		if (known.has(title) || reported.has(title)) continue;
+		reported.add(title);
+		warnings.push(`phase "${title}" is not listed in meta.phases (declared: ${[...known].join(", ")})`);
+	}
+	return warnings;
+}
+/**
+* Build the `ptc_workflow` tool definition.
+*
+* `args` is validated before `runPtcProgram` is called, so a malformed payload never spawns a
+* worker. Everything after dispatch is identical to `ptc_run_code`, plus the phase roll-up.
+*/
+function createPtcWorkflowTool(options = {}) {
+	return defineTool({
+		name: "ptc_workflow",
+		label: "PTC Workflow",
+		description: DESCRIPTION,
+		promptSnippet: PTC_WORKFLOW_SNIPPET,
+		promptGuidelines: [...PTC_TOOL_GUIDELINES],
+		parameters: PARAMETERS,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			validateWorkflowArgs(params.args);
+			const cwd = resolveToolCwd(ctx);
+			const names = resolveBindingNames(options.getBindingSourceNames?.());
+			const startedAt = Date.now();
+			const outcome = await runPtcProgram({
+				code: params.script,
+				surface: "workflow",
+				cwd,
+				bindings: createBuiltinBindings({
+					cwd,
+					names
+				}),
+				...params.args === void 0 ? {} : { args: params.args },
+				...signal === void 0 ? {} : { signal },
+				...options.config === void 0 ? {} : { config: options.config }
+			});
+			if (outcome.error !== void 0) throw codeRunFailedError(outcome);
+			const declared = params.meta.phases?.map((phase) => phase.name);
+			return renderToolResult({
+				outcome,
+				surface: "workflow",
+				warnings: unlistedPhaseWarnings(outcome, declared),
+				durationMs: Date.now() - startedAt
+			});
+		},
+		renderCall(args, theme) {
+			return renderPtcToolCall(args, theme, "workflow");
+		},
+		renderResult(result, options, theme, context) {
+			if (options.expanded) return renderPtcToolResultExpanded(result, context.args, context.isError, theme);
+			return renderPtcToolResultCollapsed(result, context.isError, theme);
+		}
+	});
+}
+//#endregion
+//#region src/mode/ptc-mode.ts
+/**
+* PTC default mode — the session-level tool-restriction state machine.
+*
+* ## What "mode" means here
+*
+* While enabled, the session's visible tool loadout is narrowed so the model reaches
+* `read` / `bash` / `edit` / `write` / `grep` / `find` / `ls` only from *inside* a program
+* (`tools.<name>(args)`). That is DSH's PTC-preset shape, and it is what makes the mode visible
+* in the TUI: the transcript stops showing file-operation rows and shows PTC rows instead.
+*
+* The mode is decided per session (`session_start`), announced once, and always reversible.
+*
+* ## Why bindings need a base snapshot (the trap this module exists to avoid)
+*
+* `resolveBindingNames()` computes bindings as `BUILTIN_BINDING_NAMES ∩ pi.getActiveTools()`
+* (T7, ADR-0005 addendum). But `pi.getActiveTools()` reads the *live* loadout — the very set this
+* mode narrows. Hiding the built-ins therefore empties the binding table, and every
+* `tools.read(...)` fails with "not bound": the extension would neuter itself.
+*
+* The fix is a **base snapshot**. `base` is captured *before* the mode hides anything, and
+* bindings derive from `base` rather than the live loadout while the mode is on. T7's invariant
+* survives, because `base` is itself read from `pi.getActiveTools()`: a session launched with
+* `--tools read` has `base = ["read"]`, so bindings stay `["read"]`. The mode never widens access
+* beyond what the session was launched with — it only makes its **own** narrowing transparent to
+* the binding table.
+*
+* ## Fail-safe on external loadout changes
+*
+* Another extension can call `setActiveTools()` (pi's own `preset.ts` and `tools.ts` examples do).
+* `ourLoadout` records the exact array this mode wrote, so a mismatch means someone else owns the
+* loadout now. The mode then exits and restores `base` instead of fighting over it.
+*
+* ## Where the mode never runs
+*
+* Print / JSON / RPC sessions (`ctx.mode !== "tui"`) are left alone: forcing the shape on CI
+* scripts buys nothing and breaks them. A session that was *launched* with an explicit tool
+* restriction is left alone too — see `decideModeEntry`.
+*/
+/** The two surfaces this package exposes. `/ptc on` needs at least one of them active. */
+const PTC_MODE_TOOL_NAMES = ["ptc_run_code", "ptc_workflow"];
+/**
+* Tools that must all be present for the **automatic** entry path to proceed.
+*
+* These four are pi's default session surface (`agent-session.js`: "["read", "bash", "edit",
+* "write"]"), so "all four present" means "this session was not narrowed". Comparing against
+* `BUILTIN_BINDING_NAMES` instead would be wrong: that list is the set of names that *can* be
+* bound, not what a default session has (`grep` / `find` / `ls` are bindable but off by default),
+* so requiring all seven would misread every ordinary session as restricted and never turn on.
+*/
+const MODE_REQUIRED_TOOL_NAMES = [
+	"read",
+	"bash",
+	"edit",
+	"write"
+];
+/** `customType` for the persisted mode entry (`pi.appendEntry`). */
+const PTC_MODE_ENTRY_TYPE = "ptc-mode";
+/** Footer status key (`ctx.ui.setStatus`). */
+const PTC_MODE_STATUS_KEY = "ptc-mode";
+/** Config file name, resolved against pi's agent dir (`~/.pi/agent/`). */
+const PTC_MODE_CONFIG_FILE = "ptc.json";
+/**
+* Which tools the mode hides while it is on.
+*
+* - `"builtins-only"` (default) — hide the seven built-in tools; tools contributed by *other*
+*   extensions (`web_search`, `todo`, `subagent`, …) stay visible and directly callable. The
+*   model is forced to program for file and shell work, which is the bulk of a coding session,
+*   without losing capabilities this package cannot re-expose: extension tools have no bindings
+*   (`pi.getAllTools()` returns metadata only — no `execute`), so hiding one makes it
+*   unreachable for the whole session.
+* - `"all-but-ptc"` — hide everything except the two PTC surfaces. Closest to a strict reading of
+*   DSH's preset, at the cost of making other extensions' tools unreachable until `/ptc off`.
+*/
+const DEFAULT_HIDE_STRATEGY = "builtins-only";
+/** Fresh, disabled state. */
+function initialModeState() {
+	return {
+		enabled: false,
+		base: void 0,
+		ourLoadout: void 0
+	};
+}
+/**
+* Read `defaultMode` from the agent-dir config file.
+*
+* Absent file → on (this package is default-on by design; see CONTEXT.md). A present file with a
+* non-boolean `defaultMode`, or unparseable JSON, is reported as `invalid` **and still defaults to
+* on** — the caller should surface the problem rather than silently changing behavior.
+*/
+function readDefaultModeConfig(agentDir) {
+	const path = join(agentDir, PTC_MODE_CONFIG_FILE);
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return {
+			defaultMode: true,
+			source: "default"
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return {
+			defaultMode: true,
+			source: "invalid",
+			error: `${path} is not valid JSON (${error instanceof Error ? error.message : String(error)})`
+		};
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {
+		defaultMode: true,
+		source: "invalid",
+		error: `${path} must contain a JSON object`
+	};
+	const value = parsed.defaultMode;
+	if (value === void 0) return {
+		defaultMode: true,
+		source: "default"
+	};
+	if (typeof value !== "boolean") return {
+		defaultMode: true,
+		source: "invalid",
+		error: `${path}: "defaultMode" must be a boolean, received ${typeof value}`
+	};
+	return {
+		defaultMode: value,
+		source: "file"
+	};
+}
+/** Normalize to a de-duplicated name list, preserving order. */
+function uniqueNames(names) {
+	return [...new Set(names)];
+}
+/** Order- and duplicate-insensitive set equality, for loadout comparison. */
+function sameToolSet(a, b) {
+	if (a.length !== b.length) return false;
+	const left = [...a].sort();
+	const right = [...b].sort();
+	return left.every((name, index) => name === right[index]);
+}
+/**
+* The loadout applied while the mode is on, given the session's current one.
+*
+* Always keeps the PTC surfaces; what else survives depends on the hide strategy (see
+* `DEFAULT_HIDE_STRATEGY`). Order follows `active`, so the visible list reads the way the session
+* was configured.
+*/
+function modeLoadout(active, hide) {
+	const isPtc = (name) => PTC_MODE_TOOL_NAMES.includes(name);
+	if (hide === "all-but-ptc") return uniqueNames(active.filter(isPtc));
+	const builtins = new Set(BUILTIN_BINDING_NAMES);
+	return uniqueNames(active.filter((name) => isPtc(name) || !builtins.has(name)));
+}
+/**
+* Decide whether the mode turns on for this session.
+*
+* The policy, in order:
+* 1. **TUI only** — print / JSON / RPC sessions are never touched.
+* 2. **Config** — `{"defaultMode": false}` opts out; `/ptc on` overrides it.
+* 3. **PTC tools must exist** — if this session has them disabled, there is nothing to run.
+* 4. **Explicit restriction wins** — a session launched with `--tools` / `--exclude-tools` /
+*    `--no-builtin-tools` that is missing any of `MODE_REQUIRED_TOOL_NAMES` (pi's default four)
+*    stays as launched. Narrowing *further* would be the extension overriding a deliberate user
+*    instruction, and the PTC surface would be degraded anyway (bindings = `BUILTIN ∩ base`).
+*    `/ptc on` overrides this: the manual path enters with the restricted loadout as `base`, so
+*    bindings stay inside the user's allowlist.
+*/
+function decideModeEntry(input) {
+	const { mode, defaultMode, active, manual } = input;
+	if (mode !== "tui") return {
+		enter: false,
+		reason: "not-tui"
+	};
+	if (!defaultMode && !manual) return {
+		enter: false,
+		reason: "config-off"
+	};
+	if (!PTC_MODE_TOOL_NAMES.some((name) => active.includes(name))) return {
+		enter: false,
+		reason: "tools-unavailable"
+	};
+	if (!manual) {
+		if (MODE_REQUIRED_TOOL_NAMES.filter((name) => !active.includes(name)).length > 0) return {
+			enter: false,
+			reason: "restricted-session"
+		};
+	}
+	return {
+		enter: true,
+		base: uniqueNames(active),
+		loadout: modeLoadout(active, input.hide ?? "builtins-only")
+	};
+}
+/**
+* Tool names the binding table should be built from.
+*
+* While the mode is on this is the base snapshot (so the built-ins the mode just hid remain
+* callable from inside a program); otherwise it is simply the live loadout, i.e. T7's rule.
+*/
+function bindingSource(state, active) {
+	return state.enabled && state.base !== void 0 ? state.base : active;
+}
+/**
+* Whether the live loadout is no longer the one this mode wrote — i.e. another extension (or the
+* user) took ownership of the tool set. Always false while the mode is off.
+*/
+function detectExternalLoadoutChange(state, active) {
+	if (!state.enabled || state.ourLoadout === void 0) return false;
+	return !sameToolSet(state.ourLoadout, active);
+}
+/**
+* Reconstruct the base loadout on `session_start`.
+*
+* Two shapes are possible:
+* - The session is still narrowed from a previous run of this mode (a `/reload`, or a resumed
+*   session): the live loadout is a subset of the PTC tools and the persisted record says the mode
+*   was on. The persisted `base` is then authoritative — but only to *undo our own hiding*.
+* - Otherwise the live loadout is whatever this pi process was launched with, and it wins. That is
+*   what keeps a new `--tools …` choice from being overridden by an older session's snapshot.
+*/
+function resolveBaseOnStart(persisted, active) {
+	const looksNarrowedByUs = active.length > 0 && active.every((name) => PTC_MODE_TOOL_NAMES.includes(name));
+	if (persisted?.enabled === true && looksNarrowedByUs && persisted.base !== void 0) return {
+		base: persisted.base,
+		restoreFirst: true
+	};
+	return {
+		base: active,
+		restoreFirst: false
+	};
+}
+/**
+* Build the system-visible briefing for the mode.
+*
+* Generated from the *actual* binding list rather than hardcoded, because bindings vary by session
+* (`base` is whatever the session was launched with) and a stale list would have the model calling
+* names that are not bound.
+*/
+function buildModeInstruction(bindings, hide) {
+	const builtinNote = hide === "all-but-ptc" ? "Every built-in tool is hidden from you, and so are other extensions' tools." : "The built-in tools (read, bash, edit, write, grep, find, ls) are hidden from you.";
+	const callable = bindings.map((name) => `tools.${name}(args)`);
+	const examples = bindings.slice(0, 2).map((name) => name === "read" ? "await tools.read({ path: \"src/index.ts\" })" : name === "bash" ? "await tools.bash({ command: \"pnpm test\" })" : `await tools.${name}({ /* … */ })`).join("\n");
+	return [
+		"[PTC MODE ACTIVE]",
+		"This session runs in PTC mode. " + builtinNote,
+		"",
+		"Work by writing one TypeScript program per task and running it:",
+		"  - ptc_run_code for a plain program (its return value and console.log come back to you)",
+		"  - ptc_workflow when the task has named phases and you want narration (log / phase /",
+		"    parallel / pipeline are available there)",
+		"",
+		`The program body is an async function. Available inside it: ${callable.join(", ")}.`,
+		examples.length > 0 ? `Examples:\n${examples}` : "",
+		"",
+		"Batch a task's steps into ONE program instead of issuing many tool calls — gathering",
+		"intermediate output yourself and returning only what matters is the point of this mode.",
+		"Image-bearing tool results inside a program are attached to you after the run — never return",
+		"base64 image data as your program's value.",
+		"If the PTC surfaces cannot express what you need, say so and the user can run /ptc off."
+	].filter((line) => line.length > 0).join("\n");
+}
+//#endregion
+//#region src/mode/skills-section.ts
+/**
+* The system-prompt skills section, restored for PTC mode.
+*
+* pi advertises skills only when the session can actually open one:
+*
+*   const skillFileReadTool = ["read", "bash"].find((tool) => selectedTools.includes(tool));
+*   if (skillFileReadTool && skills.length > 0) promptSections.skills = ...
+*                                      (pi-coding-agent: dist/core/system-prompt.js)
+*
+* PTC mode hides exactly those two tools, so that gate drops the section — and with it the model's
+* only way to learn that skills exist. Measured on real session files: sessions before
+* PTC-mode-by-default carried 43 skills in `SystemMessage.sections.skills`; PTC sessions carried
+* no `skills` section at all. See ADR-0011.
+*
+* The list body stays pi's own — `formatSkillsForPrompt` is a public export and its XML shape is
+* the agentskills.io spec, so re-deriving it here would only create drift. Only the loading
+* sentence changes: "Use the read tool" is false in a session where `read` is hidden, and the way
+* in is `tools.read` from inside a program.
+*/
+/** The two tools pi accepts as "this session can read a skill file". */
+const SKILL_READING_TOOL_NAMES = ["read", "bash"];
+/** pi's sentence, which names a tool PTC mode hides. */
+const PI_LOAD_INSTRUCTION = "Use the read tool to load a skill's file when the task matches its description.";
+/** What replaces it: the same instruction, in the only call form this session has. */
+const PTC_SKILL_LOAD_INSTRUCTION = "Use tools.read({ path }) inside a ptc_run_code program to load a skill's file when the task matches its description.";
+/**
+* Would pi withhold the skills section for this loadout?
+*
+* Mirrors the gate rather than guessing: it is true exactly when neither `read` nor `bash` is
+* directly callable, which is the state the mode deliberately puts an ordinary session in.
+*/
+function skillsSectionDropped(visibleTools) {
+	return !SKILL_READING_TOOL_NAMES.some((name) => visibleTools.includes(name));
+}
+/**
+* Build the `skills` section body (pi wraps it in `<skills>…</skills>` itself).
+*
+* Returns `""` when nothing is advertisable — pi's formatter filters out skills marked
+* `disable-model-invocation`, which is the correct behaviour to inherit: those are
+* `/skill:name`-only by design.
+*
+* `format` is injectable so a test can drive the reworded-header branch without patching pi.
+*/
+function buildPtcSkillsSection(skills, format = formatSkillsForPrompt) {
+	const section = format([...skills], "read").trim();
+	if (section.length === 0) return "";
+	if (section.includes(PI_LOAD_INSTRUCTION)) return section.replace(PI_LOAD_INSTRUCTION, PTC_SKILL_LOAD_INSTRUCTION);
+	return `${PTC_SKILL_LOAD_INSTRUCTION}\n\n${section}`;
+}
+//#endregion
+//#region src/index.ts
+/**
+* pi-ptc-subagents — DSH PTC mode (Programmable Tool Calling) for pi.
+*
+* This module is the extension entrypoint pi loads (`package.json` → `pi.extensions`).
+* The PTC machinery it exposes is complete and tested (T3): wire protocol, dispatcher,
+* bindings and the two worker surfaces. On top of it sit the two model-facing tools:
+*
+*   - `ptc_run_code` — bindings + Node + `console.log`, program's return value is the result
+*   - `ptc_workflow` — the same plus `log` / `phase` / `parallel` / `pipeline` and `args`
+*
+* There is no `agent()` helper on either surface (G1 #13 → decision B): calling it produces
+* a plain `ReferenceError` through the normal code-run error path.
+*/
+/** Footer status label shown while the mode is on. */
+const MODE_STATUS_TEXT = "PTC";
+/**
+* Which tools the mode hides. The shipped extension always uses the default; it is a named
+* constant so a future settings surface (or a test) has one place to change it.
+*/
+const MODE_HIDE_STRATEGY = DEFAULT_HIDE_STRATEGY;
+/**
+* What to tell the user when the mode turns on. Names what became unreachable, because that is the
+* part that surprises people — and the binding list, because that is the part they need in order
+* to know what a program can still do.
+*/
+function describeEntry(base, hide) {
+	return [
+		`PTC mode on — ${hide === "all-but-ptc" ? "all other tools" : "built-in tools (now reachable only as tools.<name> inside a program)"} hidden.`,
+		`Bindings available inside a program: ${resolveBindingNames(base).join(", ") || "(none)"}.`,
+		"Run /ptc off to restore the normal tool set."
+	].join("\n");
+}
+function ptcSubagents(pi) {
+	const mode = initialModeState();
+	let briefingPending = false;
+	/**
+	* Bindings come from the mode's base snapshot while PTC mode is on, and from the live loadout
+	* otherwise (T7, #21). See `src/mode/ptc-mode.ts` for why the snapshot is required: the mode
+	* hides the built-ins, which would otherwise empty the binding table and make every
+	* `tools.<name>(...)` call fail.
+	*/
+	const getBindingSourceNames = () => bindingSource(mode, pi.getActiveTools());
+	pi.registerTool(createPtcRunCodeTool({ getBindingSourceNames }));
+	pi.registerTool(createPtcWorkflowTool({ getBindingSourceNames }));
+	const paintStatus = (ctx) => {
+		ctx.ui.setStatus(PTC_MODE_STATUS_KEY, mode.enabled ? ctx.ui.theme.fg("accent", MODE_STATUS_TEXT) : void 0);
+	};
+	const enterMode = (base, loadout, ctx, announcement) => {
+		mode.enabled = true;
+		mode.base = base;
+		mode.ourLoadout = loadout;
+		pi.setActiveTools([...loadout]);
+		briefingPending = true;
+		pi.appendEntry(PTC_MODE_ENTRY_TYPE, {
+			enabled: true,
+			base: [...base]
+		});
+		paintStatus(ctx);
+		ctx.ui.notify(announcement, "info");
+	};
+	const exitMode = (ctx, opts) => {
+		const base = mode.base;
+		mode.enabled = false;
+		mode.base = void 0;
+		mode.ourLoadout = void 0;
+		briefingPending = false;
+		if (base !== void 0) pi.setActiveTools([...base]);
+		pi.appendEntry(opts.customType, { enabled: false });
+		paintStatus(ctx);
+		if (opts.announce) ctx.ui.notify("PTC mode off — built-in tools are directly callable again.", "info");
+	};
+	/** Restore the persisted mode record, if this session has one. */
+	const readPersistedMode = (ctx) => {
+		const entries = ctx.sessionManager.getEntries();
+		for (let index = entries.length - 1; index >= 0; index -= 1) {
+			const entry = entries[index];
+			if (entry?.type !== "custom" || entry.customType !== "ptc-mode") continue;
+			const data = entry.data;
+			const base = Array.isArray(data?.base) ? data.base.filter((name) => typeof name === "string") : void 0;
+			return {
+				enabled: data?.enabled === true,
+				...base === void 0 ? {} : { base }
+			};
+		}
+	};
+	pi.registerCommand("ptc", {
+		description: "Show or toggle PTC mode (built-in tools reachable only from inside a PTC program)",
+		handler: async (args, ctx) => {
+			const action = args.trim().toLowerCase();
+			if (action === "off") {
+				if (!mode.enabled) {
+					ctx.ui.notify("PTC mode is already off.", "info");
+					return;
+				}
+				exitMode(ctx, {
+					announce: true,
+					customType: PTC_MODE_ENTRY_TYPE
+				});
+				return;
+			}
+			if (action !== "on") {
+				ctx.ui.notify(mode.enabled ? `PTC mode is ON — run /ptc off to restore built-in tools.\nBindings: ${resolveBindingNames(mode.base).join(", ") || "(none)"}` : "PTC mode is OFF — run /ptc on to enter it.", "info");
+				return;
+			}
+			if (mode.enabled) {
+				ctx.ui.notify("PTC mode is already on.", "info");
+				return;
+			}
+			const decision = decideModeEntry({
+				mode: ctx.mode,
+				defaultMode: true,
+				active: pi.getActiveTools(),
+				manual: true,
+				hide: MODE_HIDE_STRATEGY
+			});
+			if (!decision.enter) {
+				ctx.ui.notify(decision.reason === "tools-unavailable" ? "Cannot enter PTC mode: ptc_run_code / ptc_workflow are not active in this session." : "Cannot enter PTC mode in this run mode.", "warning");
+				return;
+			}
+			enterMode(decision.base, decision.loadout, ctx, describeEntry(decision.base, MODE_HIDE_STRATEGY));
+		}
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		const config = readDefaultModeConfig(getAgentDir());
+		if (config.error !== void 0) ctx.ui.notify(`pi-ptc-subagents: ${config.error}`, "warning");
+		const persisted = readPersistedMode(ctx);
+		const { base, restoreFirst } = resolveBaseOnStart(persisted, pi.getActiveTools());
+		if (restoreFirst) pi.setActiveTools([...base]);
+		const decision = decideModeEntry({
+			mode: ctx.mode,
+			defaultMode: config.defaultMode,
+			active: base,
+			manual: false,
+			hide: MODE_HIDE_STRATEGY
+		});
+		const wantMode = persisted?.enabled ?? decision.enter;
+		if (decision.enter && wantMode) {
+			enterMode(base, decision.loadout, ctx, describeEntry(base, MODE_HIDE_STRATEGY));
+			return;
+		}
+		paintStatus(ctx);
+		if (!decision.enter && decision.reason !== "not-tui" && persisted === void 0) {
+			if (decision.reason === "restricted-session") ctx.ui.notify("PTC mode skipped: this session was launched with an explicit tool restriction.", "info");
+		}
+	});
+	/**
+	* Put back the skills section pi withholds while the mode hides `read`/`bash` (ADR-0011).
+	*
+	* pi advertises skills only when the session can open a skill file at all (`read` or `bash`
+	* among the selected tools), so a PTC session silently loses the whole `<available_skills>`
+	* list: the model stops knowing skills exist. Writing `sections.skills` here is the seam pi
+	* leaves open — custom sections are merged after its own, so this one wins.
+	*
+	* The same options object is reused across turns and sessions of a resume, so the injection is
+	* undone the moment the mode stops hiding those tools: a `/ptc off` must not leave PTC-flavoured
+	* loading instructions behind while `read` is directly callable again.
+	*/
+	let skillsSectionInjected = false;
+	const syncSkillsSection = (options, hidden) => {
+		if (options === void 0) return;
+		if (!mode.enabled || !hidden) {
+			if (skillsSectionInjected) {
+				delete options.sections.skills;
+				skillsSectionInjected = false;
+			}
+			return;
+		}
+		const section = buildPtcSkillsSection(options.skills);
+		if (section.length === 0) return;
+		options.sections.skills = section;
+		skillsSectionInjected = true;
+	};
+	pi.on("before_agent_start", async (event, ctx) => {
+		const options = event.systemPromptOptions;
+		syncSkillsSection(options, skillsSectionDropped(pi.getActiveTools()));
+		if (!mode.enabled) return;
+		if (detectExternalLoadoutChange(mode, pi.getActiveTools())) {
+			exitMode(ctx, {
+				announce: false,
+				customType: PTC_MODE_ENTRY_TYPE
+			});
+			syncSkillsSection(options, skillsSectionDropped(pi.getActiveTools()));
+			ctx.ui.notify("PTC mode off — another extension changed the active tool set.", "warning");
+			return;
+		}
+		if (!briefingPending) return;
+		briefingPending = false;
+		return { message: {
+			customType: "ptc-mode-briefing",
+			content: buildModeInstruction(resolveBindingNames(mode.base), MODE_HIDE_STRATEGY),
+			display: false
+		} };
+	});
+}
+//#endregion
+export { BUILTIN_BINDING_NAMES, DEFAULT_BINDING_NAMES, DEFAULT_CONFIG, DEFAULT_HIDE_STRATEGY, HOST_FRAME_KIND, MAX_LINE_CHARS, MODE_REQUIRED_TOOL_NAMES, PTC_ERROR_KIND, PTC_LOG_LEVEL, PTC_MODE_CONFIG_FILE, PTC_MODE_ENTRY_TYPE, PTC_MODE_STATUS_KEY, PTC_MODE_TOOL_NAMES, PTC_SKILL_LOAD_INSTRUCTION, SKILL_READING_TOOL_NAMES, WORKER_ENV_ALLOW_LIST, WORKER_FRAME_KIND, bindingSource, buildModeInstruction, buildPtcSkillsSection, createBuiltinBindings, createWorkerEnv, decideModeEntry, ptcSubagents as default, detectExternalLoadoutChange, effectiveTimeoutMs, initialModeState, modeLoadout, readDefaultModeConfig, renderModelValue, resolveBaseOnStart, resolveConfig, runPtcProgram, sameToolSet, sanitizeText, skillsSectionDropped, stripAnsi };
+
+//# sourceMappingURL=index.js.map