@krapht/ork 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/{format-Creyq4U3.mjs → format-yBEAXZhk.mjs}

@@ -1,6 +1,211 @@
-import { ht as liveStatus } from "./src-BRB5EQyC.mjs";
-import { i as style, n as cost } from "./output-CuivUcDa.mjs";
+import { cn as maskSecrets, ht as liveStatus } from "./src-Do_MhwiV.mjs";
+import { i as style, n as cost } from "./output-BhYkshYq.mjs";
 import { createInterface } from "node:readline/promises";
+// ../core/src/control/queue.ts
+const PERMISSION_OPTIONS = [{
+	id: "allow",
+	label: "Allow"
+}, {
+	id: "deny",
+	label: "Deny"
+}];
+const DENIED = "The user did not allow this tool.";
+/** The deny message a session gets, with the person's words when given. */
+const deniedMessage = (note) => note === void 0 ? DENIED : `${DENIED} They said: ${note}`;
+/** The input fields that say what a tool will do, the first one present. */
+const TOOL_INPUT_KEYS = [
+	"command",
+	"file_path",
+	"path",
+	"url",
+	"pattern"
+];
+/** A tool's input for the decision's context: as written, cut at `max`. */
+const inputContext = (input, max = 4e3) => {
+	const key = TOOL_INPUT_KEYS.find((k) => typeof input[k] === "string");
+	const text = key === void 0 ? JSON.stringify(input, void 0, 2) : String(input[key]);
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+};
+const createDecisionQueue = (options) => {
+	const { store, runId, emit } = options;
+	let count = 0;
+	/** Opens a decision and settles it with the first answer. */
+	const decide = (open, local, withdrawn) => {
+		count += 1;
+		const id = `${runId}-${String(count)}`;
+		const record = store.openDecision({
+			...open,
+			id,
+			runId
+		});
+		const event = {
+			type: "decision.opened",
+			node: record.node,
+			decision: id,
+			kind: record.kind,
+			question: record.question,
+			options: record.options
+		};
+		if (record.recommended !== void 0) event.recommended = record.recommended;
+		if (record.owner !== void 0) event.owner = record.owner;
+		emit(event);
+		const { promise, resolve, reject } = Promise.withResolvers();
+		const settled = new AbortController();
+		/** `note` is the stored one: masked, and absent when blank. */
+		const finish = (answer, by, note) => {
+			if (settled.signal.aborted) return;
+			settled.abort();
+			const answered = {
+				type: "decision.answered",
+				node: open.node,
+				decision: id,
+				answer,
+				by
+			};
+			if (note !== void 0) answered.note = note;
+			emit(answered);
+			resolve(note === void 0 ? {
+				answer,
+				by
+			} : {
+				answer,
+				by,
+				note
+			});
+		};
+		const withdraw = () => {
+			if (settled.signal.aborted) return;
+			settled.abort();
+			store.withdrawDecision(id);
+			emit({
+				type: "decision.withdrawn",
+				node: open.node,
+				decision: id
+			});
+			reject(/* @__PURE__ */ new Error("the question was withdrawn"));
+		};
+		if (withdrawn?.aborted === true) withdraw();
+		withdrawn?.addEventListener("abort", withdraw, { once: true });
+		const fromStore = async () => {
+			try {
+				const closed = await options.waitFor(id, settled.signal);
+				if (closed.status === "answered" && closed.answer !== void 0) finish(closed.answer, closed.answeredBy ?? "decide", closed.note);
+			} catch {}
+		};
+		const fromTerminal = async (ask) => {
+			try {
+				const { answer, note } = await ask(settled.signal);
+				if (store.answerDecision(id, answer, "terminal", note)) finish(answer, "terminal", store.decision(id)?.note);
+			} catch {}
+		};
+		fromStore();
+		if (local !== void 0) fromTerminal(local);
+		return promise;
+	};
+	return {
+		ask: (question) => {
+			const open = {
+				node: question.nodeId,
+				kind: "question",
+				question: question.question,
+				options: question.options
+			};
+			if (question.recommended !== void 0) open.recommended = question.recommended;
+			if (question.context !== void 0) open.context = question.context;
+			if (question.document !== void 0) open.document = question.document;
+			if (question.owner !== void 0) open.owner = question.owner;
+			const { local } = options;
+			return decide(open, local === void 0 ? void 0 : (signal) => {
+				let note;
+				return local.ask({
+					...question,
+					question: maskSecrets(question.question),
+					...question.context === void 0 ? {} : { context: maskSecrets(question.context) },
+					...question.document === void 0 ? {} : { document: maskSecrets(question.document) },
+					signal,
+					onNote: (given) => {
+						note = given;
+					}
+				}).then((answer) => note === void 0 ? { answer } : {
+					answer,
+					note
+				});
+			}, question.signal).then(({ answer, note }) => {
+				if (note !== void 0) question.onNote?.(note);
+				return answer;
+			});
+		},
+		settled: (question) => {
+			count += 1;
+			const id = `${runId}-${String(count)}`;
+			const { owner } = question;
+			const record = store.openDecision({
+				id,
+				runId,
+				node: question.nodeId,
+				kind: "question",
+				question: question.question,
+				options: question.options,
+				owner,
+				...question.recommended === void 0 ? {} : { recommended: question.recommended },
+				...question.context === void 0 ? {} : { context: question.context }
+			});
+			emit({
+				type: "decision.opened",
+				node: record.node,
+				decision: id,
+				kind: "question",
+				question: record.question,
+				options: record.options,
+				owner,
+				...record.recommended === void 0 ? {} : { recommended: record.recommended }
+			});
+			store.answerDecision(id, question.answer, "owner", question.note);
+			const note = store.decision(id)?.note;
+			emit({
+				type: "decision.answered",
+				node: record.node,
+				decision: id,
+				answer: question.answer,
+				by: "owner",
+				owner,
+				...note === void 0 ? {} : { note }
+			});
+		},
+		permit: async (request) => {
+			const { local } = options;
+			let localMessage = DENIED;
+			const { answer, note } = await decide({
+				node: request.nodeId,
+				kind: "permission",
+				question: `Allow ${request.toolName}?`,
+				options: PERMISSION_OPTIONS,
+				context: inputContext(request.input)
+			}, local === void 0 ? void 0 : (signal) => {
+				let said;
+				return local.permit({
+					...request,
+					signal,
+					onNote: (given) => {
+						said = given;
+					}
+				}).then((result) => {
+					if (!result.allow) localMessage = result.message;
+					const choice = result.allow ? "allow" : "deny";
+					return said === void 0 ? { answer: choice } : {
+						answer: choice,
+						note: said
+					};
+				});
+			});
+			if (note !== void 0) request.onNote?.(note);
+			return answer === "allow" ? { allow: true } : {
+				allow: false,
+				message: note === void 0 ? localMessage : deniedMessage(note)
+			};
+		}
+	};
+};
 // src/human.ts
 /**
 * @file The terminal `HumanChannel`: answers `ask_user` questions, gates and
@@ -10,18 +215,14 @@ import { createInterface } from "node:readline/promises";
 *   answerer, racing `ork decide`.
 */
 const PREVIEW = 160;
+/** A document longer than this is offered (`d`) rather than printed. */
+const SHORT_DOCUMENT_LINES = 40;
 const NO_ONE_TO_PERMIT = "No one is at the terminal to approve this tool, so it is not allowed in this run.";
 const NOTE_PROMPT = "  Note for the run (optional, Enter to skip): ";
 const NO_ONE_TO_ASK = "no one (nobody is at the terminal; use your best judgment and say so in your report)";
 /** One line that shows what a tool is about to do. */
 const previewInput = (toolName, input) => {
-	const key = [
-		"command",
-		"file_path",
-		"path",
-		"url",
-		"pattern"
-	].find((k) => typeof input[k] === "string");
+	const key = TOOL_INPUT_KEYS.find((k) => typeof input[k] === "string");
 	const line = (key === void 0 ? JSON.stringify(input) : `${key}: ${String(input[key])}`).replaceAll(/\s+/gu, " ").trim();
 	return line.length > PREVIEW ? `${toolName} ${line.slice(0, 159)}…` : `${toolName} ${line}`;
 };
@@ -63,11 +264,13 @@ const createTerminalHuman = (io) => {
 		const note = (await prompt(NOTE_PROMPT, signal)).trim();
 		if (note !== "") onNote(note);
 	};
-	const choose = async (hint, options, recommended, signal) => {
-		const picked = pickOption(await prompt(`  Choose${hint}: `, signal), options, recommended);
+	const choose = async (hint, options, recommended, signal, document) => {
+		const answer = await prompt(`  Choose${hint}: `, signal);
+		const picked = pickOption(answer, options, recommended);
 		if (picked !== void 0) return picked;
-		say(style("dim", "  Type an option's number or id."));
-		return choose(hint, options, recommended, signal);
+		if (document !== void 0 && answer.trim() === "d") say(document);
+		else say(style("dim", "  Type an option's number or id."));
+		return choose(hint, options, recommended, signal, document);
 	};
 	const oneAtATime = (work) => {
 		const result = turn.then(work);
@@ -93,10 +296,12 @@ const createTerminalHuman = (io) => {
 				message: "The user did not allow this tool."
 			};
 		}),
-		ask: ({ nodeId, question, options, recommended, context, signal, onNote }) => oneAtATime(async () => {
+		ask: ({ nodeId, question, options, recommended, context, document, signal, onNote }) => oneAtATime(async () => {
 			if (signal?.aborted === true) throw new Error("the question was withdrawn");
+			const documentLines = document?.trimEnd().split("\n").length ?? 0;
+			if (document !== void 0 && documentLines <= SHORT_DOCUMENT_LINES) say(document);
 			say(`${style(["yellow", "bold"], "?")} ${style("bold", nodeId)} asks: ${question}`);
-			if (context !== void 0) say(style("dim", `  ${context}`));
+			if (context !== void 0) say(style("dim", `  ${context.replaceAll("\n", "\n  ")}`));
 			for (const [index, option] of options.entries()) say(optionLine(option, index, recommended));
 			if (!io.interactive) {
 				const answer = recommended ?? NO_ONE_TO_ASK;
@@ -105,7 +310,8 @@ const createTerminalHuman = (io) => {
 			}
 			const fallback = options.findIndex((o) => o.id === recommended);
 			const hint = fallback === -1 ? "" : ` [${String(fallback + 1)}]`;
-			const picked = await choose(hint, options, recommended, signal);
+			if (documentLines > SHORT_DOCUMENT_LINES) say(`  Document: ${String(documentLines)} lines. Type d to read it.`);
+			const picked = await choose(hint, options, recommended, signal, document);
 			await takeNote(onNote, signal);
 			return picked;
 		}),
@@ -424,4 +630,4 @@ const formatTree = (roots) => {
 		return `${text.padEnd(label)}  ${style("dim", node.type.padEnd(type))}  ${state}${usage}`;
 	});
 };
-export { formatRunEvent as a, formatEvent as i, formatRuns as n, createTerminalHuman as o, formatTree as r, ago as t };
+export { formatRunEvent as a, formatEvent as i, formatRuns as n, createTerminalHuman as o, formatTree as r, createDecisionQueue as s, ago as t };

package/dist/{in-a-run-CsSBQQ2q.mjs → in-a-run-CKFIeMpU.mjs}

@@ -1,4 +1,4 @@
-import { p as runMarkerIn } from "./src-Bc9yaAiZ.mjs";
+import { p as runMarkerIn } from "./src-HxtJOMRr.mjs";
 // src/commands/in-a-run.ts
 /**
 * @file The commands that act as the user refuse a program or an agent in a run

package/dist/{limits-D_HxH0CK.mjs → limits-CwzPe9wZ.mjs}

@@ -1,4 +1,4 @@
-import { a as limitsNow, i as NOT_STARTED, o as limitsReport, r as capsHere } from "./src-BRB5EQyC.mjs";
+import { a as limitsNow, i as NOT_STARTED, o as limitsReport, r as capsHere } from "./src-Do_MhwiV.mjs";
 // src/run/limits.ts
 /**
 * @file The limits across runs that apply here (RFC-007): the user's settings

package/dist/{list-CzzpVEpM.mjs → list-BE02pCZ9.mjs}

@@ -1,4 +1,4 @@
-import { A as gitOk, j as lines, k as git } from "./src-BRB5EQyC.mjs";
+import { A as gitOk, j as lines, k as git } from "./src-Do_MhwiV.mjs";
 import { existsSync } from "node:fs";
 // ../core/src/worktree/list.ts
 /**

package/dist/{mcp-DYmQt372.mjs → mcp-DMuBbUHU.mjs}

@@ -1,8 +1,8 @@
-import { h as isNewer } from "./src-BRB5EQyC.mjs";
-import { n as ORK_VERSION } from "./__build_info__-1i1IwLg7.mjs";
-import { a as openMcp, c as refused, o as tool, s as answer } from "./src-CsjumY1t.mjs";
-import { p as runMarkerIn } from "./src-Bc9yaAiZ.mjs";
-import { n as explainNode } from "./context-CD5TCD1D.mjs";
+import { h as isNewer } from "./src-Do_MhwiV.mjs";
+import { n as ORK_VERSION } from "./__build_info__-Dl8yTEu-.mjs";
+import { a as openMcp, c as refused, o as tool, s as answer } from "./src-QEycKJWk.mjs";
+import { p as runMarkerIn } from "./src-HxtJOMRr.mjs";
+import { n as explainNode } from "./context-CepHRoj9.mjs";
 import { z } from "zod";
 import { defineCommand } from "citty";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -43,7 +43,7 @@ const orkMcpServer = (options = {}) => {
 		...options.script === void 0 ? {} : { script: options.script }
 	});
 	const all = [...opened.tools, explainTool(opened, options.home)];
-	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.4") ? tooOld(all, options.expects) : all;
+	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.5") ? tooOld(all, options.expects) : all;
 	const server = new McpServer({
 		name: "ork",
 		version: ORK_VERSION

package/dist/{output-CuivUcDa.mjs → output-BhYkshYq.mjs}

@@ -1,4 +1,4 @@
-import { $ as text, $t as maskReplacer, Ht as FEEDBACK_SEVERITIES, Q as inTransaction, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, X as usageQueries, Y as backfillUsage, Z as eventOf, en as maskSecrets, yn as PROJECT_MODES, yt as ownProcessStart } from "./src-BRB5EQyC.mjs";
+import { $ as text, Ht as FEEDBACK_SEVERITIES, Q as inTransaction, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, X as usageQueries, Y as backfillUsage, Z as eventOf, cn as maskSecrets, sn as maskReplacer, yn as PROJECT_MODES, yt as ownProcessStart } from "./src-Do_MhwiV.mjs";
 import path from "node:path";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -70,6 +70,7 @@ const decisionOf = (row) => {
 	const optional = {
 		recommended: text(row, "recommended"),
 		context: text(row, "context"),
+		document: text(row, "document"),
 		answer: text(row, "answer"),
 		answeredAt: text(row, "answered_at"),
 		note: text(row, "note"),
@@ -81,8 +82,8 @@ const decisionOf = (row) => {
 	return record;
 };
 const decisionQueries = (db) => {
-	const insert = db.prepare(`INSERT INTO decisions (id, run_id, node, kind, question, options, recommended, context, owner, opened_at, status)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open')`);
+	const insert = db.prepare(`INSERT INTO decisions (id, run_id, node, kind, question, options, recommended, context, document, owner, opened_at, status)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open')`);
 	const answer = db.prepare(`UPDATE decisions SET status = 'answered', answer = ?, answered_by = ?, answered_at = ?, note = ?
      WHERE id = ? AND status = 'open'`);
 	const withdraw = db.prepare("UPDATE decisions SET status = 'withdrawn', answered_at = ? WHERE id = ? AND status = 'open'");
@@ -102,9 +103,10 @@ const decisionQueries = (db) => {
 			const masked = {
 				...decision,
 				question: maskSecrets(decision.question),
-				...decision.context === void 0 ? {} : { context: maskSecrets(decision.context) }
+				...decision.context === void 0 ? {} : { context: maskSecrets(decision.context) },
+				...decision.document === void 0 ? {} : { document: maskSecrets(decision.document) }
 			};
-			insert.run(masked.id, masked.runId, masked.node, masked.kind, masked.question, JSON.stringify(masked.options), masked.recommended ?? null, masked.context ?? null, masked.owner ?? null, openedAt);
+			insert.run(masked.id, masked.runId, masked.node, masked.kind, masked.question, JSON.stringify(masked.options), masked.recommended ?? null, masked.context ?? null, masked.document ?? null, masked.owner ?? null, openedAt);
 			return {
 				...masked,
 				openedAt,
@@ -731,7 +733,8 @@ const MIGRATIONS = [
 	`ALTER TABLE runs ADD COLUMN skipped INTEGER;
    ALTER TABLE runs ADD COLUMN failures_handled INTEGER;`,
 	`ALTER TABLE decisions ADD COLUMN note TEXT;`,
-	`ALTER TABLE decisions ADD COLUMN owner TEXT;`
+	`ALTER TABLE decisions ADD COLUMN owner TEXT;`,
+	`ALTER TABLE decisions ADD COLUMN document TEXT;`
 ];
 const versionOf = (db) => Number(db.prepare("PRAGMA user_version").get()?.["user_version"] ?? 0);
 /**

package/dist/{pause-W6MzQqg8.mjs → pause-C_Q0W6iX.mjs}

@@ -1,7 +1,7 @@
-import { G as requestContinue, K as requestPause } from "./src-BRB5EQyC.mjs";
-import { t as findRun } from "./find-BgZjVKhv.mjs";
-import { a as write, c as openStore, i as style, o as writeErr } from "./output-CuivUcDa.mjs";
-import { r as continueRefusal } from "./in-a-run-CsSBQQ2q.mjs";
+import { G as requestContinue, K as requestPause } from "./src-Do_MhwiV.mjs";
+import { t as findRun } from "./find-DWiDJ5Lc.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-BhYkshYq.mjs";
+import { r as continueRefusal } from "./in-a-run-CKFIeMpU.mjs";
 import { defineCommand } from "citty";
 // src/commands/pause.ts
 /**

package/dist/{relay-CsdoZUXJ.mjs → relay-COCvG-0I.mjs}

@@ -1,5 +1,5 @@
-import { B as linkNodes, L as addressOf, U as unlinkNodes } from "./src-BRB5EQyC.mjs";
-import { a as write, c as openStore, i as style, o as writeErr } from "./output-CuivUcDa.mjs";
+import { B as linkNodes, L as addressOf, U as unlinkNodes } from "./src-Do_MhwiV.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-BhYkshYq.mjs";
 import { defineCommand } from "citty";
 // src/commands/relay.ts
 /**

package/dist/{remove-DLfDjBdF.mjs → remove-RVcX1KqP.mjs}

@@ -1,6 +1,6 @@
-import { ht as liveStatus, j as lines, k as git } from "./src-BRB5EQyC.mjs";
-import { n as listOrkWorktrees, t as createdWorktrees } from "./list-CzzpVEpM.mjs";
-import { i as keyOf, n as applyStep, r as cleanStep, s as stepPrunes } from "./clean-B1zPxq6A.mjs";
+import { ht as liveStatus, j as lines, k as git } from "./src-Do_MhwiV.mjs";
+import { n as listOrkWorktrees, t as createdWorktrees } from "./list-BE02pCZ9.mjs";
+import { i as keyOf, n as applyStep, r as cleanStep, s as stepPrunes } from "./clean-DYVmLkd4.mjs";
 // ../core/src/worktree/words.ts
 /**
 * @file The plain words for what `ork worktrees` shows, in one place, so the

package/dist/{send-Bw2FI_Sv.mjs → send-OVpRei_5.mjs}

@@ -1,6 +1,6 @@
-import { cn as wakeRun, ht as liveStatus, kt as scriptContactsOf, on as socketPath } from "./src-BRB5EQyC.mjs";
-import { c as openStore, o as writeErr } from "./output-CuivUcDa.mjs";
-import { u as inheritedScrubber } from "./src-Bc9yaAiZ.mjs";
+import { ht as liveStatus, in as socketPath, kt as scriptContactsOf, on as wakeRun } from "./src-Do_MhwiV.mjs";
+import { c as openStore, o as writeErr } from "./output-BhYkshYq.mjs";
+import { u as inheritedScrubber } from "./src-HxtJOMRr.mjs";
 import { defineCommand } from "citty";
 // ../core/src/remote/send.ts
 /**

package/dist/{src-CrYCkU9J.mjs → src-CxZr4Bp2.mjs}

@@ -1,4 +1,4 @@
-import { Ht as FEEDBACK_SEVERITIES, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, pt as parseReport } from "./src-BRB5EQyC.mjs";
+import { Ht as FEEDBACK_SEVERITIES, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, pt as parseReport } from "./src-Do_MhwiV.mjs";
 import { z } from "zod";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createInterface } from "node:readline";

package/dist/{src-BRB5EQyC.mjs → src-Do_MhwiV.mjs}

@@ -661,6 +661,7 @@ const HumanGateNodeSchema = z.strictObject({
 	...base,
 	...notifyFields,
 	question: z.string(),
+	document: z.string().optional(),
 	options: z.array(DecisionOptionSchema).min(2),
 	recommended: z.string().optional(),
 	timeout: DurationSchema.optional(),
@@ -3601,6 +3602,26 @@ const writePlugin = (stack, dir, description) => {
 	}
 	return dir;
 };
+// ../core/src/store/mask.ts
+/**
+* @file Masks secrets before anything is stored: tokens and keys in common
+*   formats, anywhere in an event's strings. The store and feedback records use
+*   the same patterns; the terminal is not masked (it is the user's own).
+*/
+const PATTERNS = [
+	/sk-ant-[\w-]{20,}/gu,
+	/\bgh[opsur]_[A-Za-z0-9]{20,}/gu,
+	/\bgithub_pat_\w{20,}/gu,
+	/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/gu,
+	/\bxox[abprs]-[\w-]{10,}/gu,
+	/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu,
+	/(?<=\bbearer\s+)[\w.~+/-]{20,}=*/giu,
+	/(?<=aws_secret_access_key\s*[=:]\s*)\S+/giu
+];
+const MASK = "[masked]";
+const maskSecrets = (text) => PATTERNS.reduce((out, pattern) => out.replaceAll(pattern, MASK), text);
+/** A `JSON.stringify` replacer that masks every string. */
+const maskReplacer = (_key, value) => typeof value === "string" ? maskSecrets(value) : value;
 // ../core/src/control/socket.ts
 /**
 * @file The per-run local socket (`~/.ork/sockets/<run>.sock`): the fast path
@@ -4223,27 +4244,39 @@ const stringify$1 = (value) => {
 	if (typeof value === "number" || typeof value === "boolean") return String(value);
 	return JSON.stringify(value);
 };
-const renderTemplate = (parts, scope) => parts.map((part) => typeof part === "string" ? part : stringify$1(evaluate(part.expr, scope))).join("");
-// ../core/src/store/mask.ts
+const isContainer = (value) => value !== null && typeof value === "object";
+const depthOf = (value) => isContainer(value) ? 1 + Math.max(0, ...Object.values(value).map((item) => depthOf(item))) : 0;
+/** Keeps a multi-line value inside its list item or `key:` line. */
+const hang = (text) => text.replaceAll("\n", "\n  ");
+/** A value at most two levels deep as Markdown list items and `key: value`. */
+const listed$2 = (value) => {
+	if (!isContainer(value)) return stringify$1(value);
+	if (Array.isArray(value)) return value.map((item) => `- ${hang(listed$2(item))}`).join("\n");
+	return Object.entries(value).map(([key, item]) => isContainer(item) ? `${key}:\n  ${hang(listed$2(item))}` : `${key}: ${hang(stringify$1(item))}`).join("\n");
+};
 /**
-* @file Masks secrets before anything is stored: tokens and keys in common
-*   formats, anywhere in an event's strings. The store and feedback records use
-*   the same patterns; the terminal is not masked (it is the user's own).
+* A value as a person reads it: Markdown, never a line of raw JSON. `before` is
+* the text so far: a list or object starts on its own line, after a blank one
+* when text shares its line.
 */
-const PATTERNS = [
-	/sk-ant-[\w-]{20,}/gu,
-	/\bgh[opsur]_[A-Za-z0-9]{20,}/gu,
-	/\bgithub_pat_\w{20,}/gu,
-	/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/gu,
-	/\bxox[abprs]-[\w-]{10,}/gu,
-	/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu,
-	/(?<=\bbearer\s+)[\w.~+/-]{20,}=*/giu,
-	/(?<=aws_secret_access_key\s*[=:]\s*)\S+/giu
-];
-const MASK = "[masked]";
-const maskSecrets = (text) => PATTERNS.reduce((out, pattern) => out.replaceAll(pattern, MASK), text);
-/** A `JSON.stringify` replacer that masks every string. */
-const maskReplacer = (_key, value) => typeof value === "string" ? maskSecrets(value) : value;
+const readableText = (value, before) => {
+	if (!isContainer(value)) return stringify$1(value);
+	if (depthOf(value) <= 2) {
+		const list = listed$2(value);
+		return list === "" || before === "" || before.endsWith("\n") ? list : `\n\n${list}`;
+	}
+	const code = JSON.stringify(value, void 0, 2).replaceAll(/^/gmu, "    ");
+	return before === "" || before.endsWith("\n\n") ? code : `\n\n${code}`;
+};
+/**
+* Fills a parsed template. `readable` is for text a person reads (a gate's
+* `question` and `document`); scripts and prompts keep JSON (ADR-047).
+*/
+const renderTemplate = (parts, scope, { readable = false } = {}) => parts.reduce((text, part) => {
+	if (typeof part === "string") return text + part;
+	const value = evaluate(part.expr, scope);
+	return text + (readable ? readableText(value, text) : stringify$1(value));
+}, "");
 // ../core/src/feedback/fingerprint.ts
 /**
 * @file Feedback fingerprints: records about the same thing (same target, kind,
@@ -5893,6 +5926,7 @@ const TEMPLATE_FIELDS = [
 	"command",
 	"cwd",
 	"question",
+	"document",
 	"workflow",
 	"project",
 	"ref"
@@ -13140,4 +13174,4 @@ const createWorkspace = (options) => {
 		close
 	};
 };
-export { text as $, isToolNode as $n, maskReplacer as $t, gitOk as A, projectRootOf as An, runScope as At, linkNodes as B, readDocument as Bn, serversIn as Bt, workflowTextHash as C, placeFiles as Cn, walkChecks as Ct, inspectProject as D, shownPath as Dn, userMessageText as Dt, BRANCH_PREFIX as E, runDirOf as En, MESSAGE_LIMIT as Et, declaredProblem as F, writePlainFile as Fn, PROJECT_FILE as Ft, requestContinue as G, EdgeInputSchema as Gn, planPost as Gt, tellNode as H, parseWorkflow as Hn, FEEDBACK_SEVERITIES as Ht, createCalls as I, skillsIn as In, gitRulesOf as It, tellLiveRun as J, expandEdge as Jn, publishPost as Jt, requestPause as K, WorkflowSchema as Kn, runGh as Kt, addressOf as L, WorkflowEditSchema as Ln, loadProject as Lt, clearGitLocalEnv as M, estimateTokens as Mn, envReadsOf as Mt, parseInputPairs as N, guardedBase as Nn, nodeSays as Nt, removeWorktree as O, workflowDirOf as On, heldTimeout as Ot, resolveInputs as P, plainPathInside as Pn, declaredOutputOf as Pt, inTransaction as Q, isClaudeNode as Qn, targetOf as Qt, endLink as R, applyEdits as Rn, MCP_FILE as Rt, readProjectTriggers as S, newProjectId as Sn, checkWorkflowText as St, watchingPid as T, projectsHome as Tn, startRun as Tt, unlinkNodes as U, serializeWorkflow as Un, FEEDBACK_TARGETS as Ut, peerOf as V, renderJsonSchema as Vn, FEEDBACK_KINDS as Vt, flattenTree as W, markValue as Wn, DISCUSSIONS as Wt, usageQueries as X, NodeSchema as Xn, fingerprint as Xt, backfillUsage as Y, settingsOf as Yn, createFeedback as Yt, eventOf as Z, beforeOf as Zn, normalizeTitle as Zt, lateTriggers as _, catalogAgent as _n, runStatus as _t, limitsNow as a, serveRun as an, integrationFor as ar, DETACHED_ENV as at, triggerStanding as b, hasInRepoFiles as bn, processAlive as bt, usd as c, wakeRun as cn, CLAUDE_DRIVERS as cr, explainWorkflowText as ct, runningRunIds as d, planMoveInto as dn, experimentsOn as dr, namingNoDriver as dt, maskSecrets as en, programsRunBy as er, adoptedCalls as et, runningScript as f, linkTools as fn, knownExperiments as fr, sessionDriver as ft, parseVersion as g, deleteAgent as gn, pausedOf as gt, isNewer as h, createAgent as hn, liveStatus as ht, NOT_STARTED as i, readCondition as in, TOOL_PREFIX as ir, replayLoopAnswers as it, lines as j, LESSON_CAP_TOKENS as jn, calledWorkflows as jt, git as k, inside as kn, scriptContactsOf as kt, planUpgrade as l, planAgentMigration as ln, firstLine as lr, explainSession as lt, compareVersions as m, toolsInUse as mn, reportSchemaFor as mt, resolveBase as n, parseTemplate as nn, timeoutMs as nr, resumable as nt, limitsReport as o, socketPath as on, AGENT_TOOL_LAYOUTS as or, detachRun as ot, detectInstaller as p, toolLinks as pn, parseReport as pt, requestStop as q, CheckReportSchema as qn, sendPost as qt, capsHere as r, renderTemplate as rn, INTEGRATIONS as rr, createReplay as rt, planReason as s, socketRoom as sn, ORK_LAYOUT as sr, followEvents as st, createWorkspace as t, evaluate as tn, NodeIdSchema as tr, detachResume as tt, releaseNotes as u, applySteps as un, EXPERIMENTS as ur, planNodeSession as ut, triggersReport as v, loadAgents as vn, runTree as vt, takeWatchLock as w, placeFor as wn, walkSummary as wt, declaredTriggers as x, inRepoPlace as xn, stillTheSameProcess as xt, createWatcher as y, PROJECT_MODES as yn, ownProcessStart as yt, endLinksOf as z, newWorkflowText as zn, mcpNotText as zt };
+export { text as $, isToolNode as $n, evaluate as $t, gitOk as A, projectRootOf as An, runScope as At, linkNodes as B, readDocument as Bn, serversIn as Bt, workflowTextHash as C, placeFiles as Cn, walkChecks as Ct, inspectProject as D, shownPath as Dn, userMessageText as Dt, BRANCH_PREFIX as E, runDirOf as En, MESSAGE_LIMIT as Et, declaredProblem as F, writePlainFile as Fn, PROJECT_FILE as Ft, requestContinue as G, EdgeInputSchema as Gn, planPost as Gt, tellNode as H, parseWorkflow as Hn, FEEDBACK_SEVERITIES as Ht, createCalls as I, skillsIn as In, gitRulesOf as It, tellLiveRun as J, expandEdge as Jn, publishPost as Jt, requestPause as K, WorkflowSchema as Kn, runGh as Kt, addressOf as L, WorkflowEditSchema as Ln, loadProject as Lt, clearGitLocalEnv as M, estimateTokens as Mn, envReadsOf as Mt, parseInputPairs as N, guardedBase as Nn, nodeSays as Nt, removeWorktree as O, workflowDirOf as On, heldTimeout as Ot, resolveInputs as P, plainPathInside as Pn, declaredOutputOf as Pt, inTransaction as Q, isClaudeNode as Qn, targetOf as Qt, endLink as R, applyEdits as Rn, MCP_FILE as Rt, readProjectTriggers as S, newProjectId as Sn, checkWorkflowText as St, watchingPid as T, projectsHome as Tn, startRun as Tt, unlinkNodes as U, serializeWorkflow as Un, FEEDBACK_TARGETS as Ut, peerOf as V, renderJsonSchema as Vn, FEEDBACK_KINDS as Vt, flattenTree as W, markValue as Wn, DISCUSSIONS as Wt, usageQueries as X, NodeSchema as Xn, fingerprint as Xt, backfillUsage as Y, settingsOf as Yn, createFeedback as Yt, eventOf as Z, beforeOf as Zn, normalizeTitle as Zt, lateTriggers as _, catalogAgent as _n, runStatus as _t, limitsNow as a, socketRoom as an, integrationFor as ar, DETACHED_ENV as at, triggerStanding as b, hasInRepoFiles as bn, processAlive as bt, usd as c, maskSecrets as cn, CLAUDE_DRIVERS as cr, explainWorkflowText as ct, runningRunIds as d, planMoveInto as dn, experimentsOn as dr, namingNoDriver as dt, parseTemplate as en, programsRunBy as er, adoptedCalls as et, runningScript as f, linkTools as fn, knownExperiments as fr, sessionDriver as ft, parseVersion as g, deleteAgent as gn, pausedOf as gt, isNewer as h, createAgent as hn, liveStatus as ht, NOT_STARTED as i, socketPath as in, TOOL_PREFIX as ir, replayLoopAnswers as it, lines as j, LESSON_CAP_TOKENS as jn, calledWorkflows as jt, git as k, inside as kn, scriptContactsOf as kt, planUpgrade as l, planAgentMigration as ln, firstLine as lr, explainSession as lt, compareVersions as m, toolsInUse as mn, reportSchemaFor as mt, resolveBase as n, readCondition as nn, timeoutMs as nr, resumable as nt, limitsReport as o, wakeRun as on, AGENT_TOOL_LAYOUTS as or, detachRun as ot, detectInstaller as p, toolLinks as pn, parseReport as pt, requestStop as q, CheckReportSchema as qn, sendPost as qt, capsHere as r, serveRun as rn, INTEGRATIONS as rr, createReplay as rt, planReason as s, maskReplacer as sn, ORK_LAYOUT as sr, followEvents as st, createWorkspace as t, renderTemplate as tn, NodeIdSchema as tr, detachResume as tt, releaseNotes as u, applySteps as un, EXPERIMENTS as ur, planNodeSession as ut, triggersReport as v, loadAgents as vn, runTree as vt, takeWatchLock as w, placeFor as wn, walkSummary as wt, declaredTriggers as x, inRepoPlace as xn, stillTheSameProcess as xt, createWatcher as y, PROJECT_MODES as yn, ownProcessStart as yt, endLinksOf as z, newWorkflowText as zn, mcpNotText as zt };

package/dist/{src-Bc9yaAiZ.mjs → src-HxtJOMRr.mjs}

@@ -1,4 +1,4 @@
-import { $n as isToolNode, At as runScope, Bt as serversIn, F as declaredProblem, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Rt as MCP_FILE, Wn as markValue, Zn as beforeOf, ar as integrationFor, er as programsRunBy, ft as sessionDriver, ir as TOOL_PREFIX, jt as calledWorkflows, mt as reportSchemaFor, nn as parseTemplate, nr as timeoutMs, rn as renderTemplate, rr as INTEGRATIONS, s as planReason, tn as evaluate, ut as planNodeSession, zt as mcpNotText } from "./src-BRB5EQyC.mjs";
+import { $n as isToolNode, $t as evaluate, At as runScope, Bt as serversIn, F as declaredProblem, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Rt as MCP_FILE, Wn as markValue, Zn as beforeOf, ar as integrationFor, en as parseTemplate, er as programsRunBy, ft as sessionDriver, ir as TOOL_PREFIX, jt as calledWorkflows, mt as reportSchemaFor, nr as timeoutMs, rr as INTEGRATIONS, s as planReason, tn as renderTemplate, ut as planNodeSession, zt as mcpNotText } from "./src-Do_MhwiV.mjs";
 import path from "node:path";
 import { accessSync, constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
@@ -1689,10 +1689,11 @@ const claudeExecutor = (options) => async (context) => {
 };
 // ../nodes/src/gate.ts
 /**
-* @file The `human.gate` node type: asks the human the rendered question,
-*   outputs their choice with the note they gave, and answers with the
-*   `default` when the `timeout` passes. The timeout counts only while the run
-*   and the gate are not paused (ADR-041).
+* @file The `human.gate` node type: asks the human the rendered question, with
+*   its document if it has one, both in readable text (no raw JSON), outputs
+*   their choice with the note they gave, and answers with the `default` when
+*   the `timeout` passes. The timeout counts only while the run and the gate
+*   are not paused (ADR-041).
 */
 /** A promise that never settles: the losing side of a race. */
 const NEVER = new Promise(() => {});
@@ -1714,8 +1715,13 @@ const gateExecutor = async (context) => {
 		output: {},
 		error: `${context.id} is not a gate`
 	};
-	const template = parseTemplate(node.question);
-	const question = template.ok ? renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId)) : node.question;
+	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const render = (text) => {
+		const template = parseTemplate(text);
+		return template.ok ? renderTemplate(template.parts, scope, { readable: true }) : text;
+	};
+	const question = render(node.question);
+	const document = render(node.document ?? "");
 	const options = node.options.map((o) => choiceOf(o));
 	const withdraw = new AbortController();
 	context.signal.addEventListener("abort", () => {
@@ -1732,6 +1738,7 @@ const gateExecutor = async (context) => {
 		}
 	};
 	if (node.recommended !== void 0) asked.recommended = node.recommended;
+	if (document.trim() !== "") asked.document = document;
 	const answer = context.human.ask(asked).then((choice) => ({
 		choice,
 		answeredBy: "user",