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

package/dist/context-CEaKOVmG.mjs

@@ -0,0 +1,683 @@
+import { C as workflowTextHash, D as openStore, Mn as LESSON_CAP_TOKENS, O as storePath, R as driverRefusals, Rt as loadProject, S as readProjectTriggers, Tn as placeFor, _ as lateTriggers, _r as EXPERIMENTS, dr as readyDriver, gr as firstLine, hr as DRIVER_IDS, ht as walkSummary, ir as retiredDriverHint, kn as workflowDirOf, lt as namingNoDriver, mr as AGENT_DRIVERS, mt as walkChecks, nr as DriverSchema, on as socketRoom, or as INTEGRATIONS, pt as checkWorkflowText, st as explainSession, ur as driverChecks, v as triggersReport, vr as experimentsOn, wn as placeFiles, yr as knownExperiments, z as driverQueues } from "./src-Df6KOIDC.mjs";
+import { c as checkDue, d as pendingNotice, f as readUpdateCache, h as writeUpdateCache, i as registryOf, m as updateCachePath, n as ORK_VERSION, o as updateSwitchOff, p as refreshUpdateCache, r as isSwitchedOn, t as ORK_NAME, u as newerVersion } from "./__build_info__-DFF18K8y.mjs";
+import { a as write, i as style, o as writeErr, r as plain } from "./output-Bqljtmp_.mjs";
+import { c as registeredProjects, i as refusedBuiltin, o as workflowArg, r as findWorkflowFiles, s as projectAt } from "./workflows-BT1gDRIV.mjs";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { execFile, spawn } from "node:child_process";
+import { defineCommand } from "citty";
+import { styleText } from "node:util";
+// src/update/notify.ts
+/**
+* @file The new-version notice (ADR-038). At most once a day a command starts a
+*   detached copy of `ork` that asks the npm registry for the latest version
+*   and records it in `~/.ork/update-check.json`, so no command waits on the
+*   network; a later command, when a newer version is known, ends with one line
+*   on stderr (once a day). Off in CI, without a terminal, with `--json`, and
+*   with `ORK_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1`.
+*/
+/** Set in the background copy of `ork` that only runs the check. */
+const UPDATE_CHILD_ENV = "ORK_UPDATE_CHECK_CHILD";
+/**
+* Why the automatic check is off for this command, or `null` when it is on: the
+* environment's switches (core's, which `ork ui` reads too), then where a
+* notice on stderr would go.
+*/
+const updateCheckOff = (env, argv, terminal) => {
+	const switched = updateSwitchOff(env);
+	if (switched !== null) return switched === "CI" ? "in CI" : "turned off";
+	if (isSwitchedOn(env["ORK_DETACHED"]) || !terminal) return "no terminal";
+	if (argv.includes("--json")) return "JSON output";
+	if (argv[0] === "upgrade") return "ork upgrade checks for itself";
+	if (argv[0] === "ui" && argv.includes("--serve")) return "ork ui's server checks for itself";
+	return null;
+};
+/** The notice's text. */
+const updateNotice = (latest, current) => `Ork ${latest} is out (you have ${current}). Upgrade with: ork upgrade`;
+/**
+* Starts the background check when one is due. Records the attempt first, so
+* commands started in the next moments do not start one too.
+*/
+const startUpdateCheck = (file = updateCachePath(), now = /* @__PURE__ */ new Date()) => {
+	try {
+		const cache = readUpdateCache(file);
+		if (!checkDue(cache, now)) return;
+		writeUpdateCache(file, {
+			...cache,
+			checkedAt: now.toISOString()
+		});
+		const child = spawn(process.execPath, [...process.execArgv, process.argv[1] ?? ""], {
+			detached: true,
+			stdio: "ignore",
+			env: {
+				...process.env,
+				[UPDATE_CHILD_ENV]: "1"
+			}
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+};
+/** The background copy's whole job: ask the registry, record the answer. */
+const runUpdateChild = async () => {
+	const registry = registryOf(process.env);
+	await refreshUpdateCache(updateCachePath(), ORK_NAME, /* @__PURE__ */ new Date(), {
+		current: ORK_VERSION,
+		...registry === void 0 ? {} : { registry }
+	});
+};
+/** Prints the notice when a newer version is known and not told today. */
+const showUpdateNotice = (file = updateCachePath(), now = /* @__PURE__ */ new Date()) => {
+	try {
+		const cache = readUpdateCache(file);
+		const latest = pendingNotice(cache, ORK_VERSION, now);
+		if (cache === null || latest === null) return;
+		const text = updateNotice(latest, ORK_VERSION);
+		process.stderr.write(`\n${styleText("yellow", text, { stream: process.stderr })}\n`);
+		writeUpdateCache(file, {
+			...cache,
+			notified: {
+				version: latest,
+				at: now.toISOString()
+			}
+		});
+	} catch {}
+};
+// src/update/upgrade.ts
+/**
+* @file `ork doctor`'s line for Ork itself (ADR-038): the running version
+*   against the last update check, read from the record without asking the
+*   network. What `ork upgrade` does is core's (`planUpgrade`, `runInstall`),
+*   shared with the server behind `ork ui`.
+*/
+/** `ork doctor`'s line for Ork itself, from the last check. */
+const versionCheck = (current, cache, checksOff) => {
+	const newer = newerVersion(cache, current);
+	if (newer !== null) return {
+		name: "ork",
+		status: "warn",
+		detail: `${current}; ${newer} is out`,
+		hint: "Run ork upgrade."
+	};
+	return {
+		name: "ork",
+		status: "ok",
+		detail: `${current} (${cache?.latest === void 0 ? checksOff === null ? "not checked for updates yet" : `the daily update check is off here: ${checksOff}` : `the latest as of ${cache.checkedAt.slice(0, 10)}`})`
+	};
+};
+// src/doctor/checks.ts
+/**
+* @file The checks behind `ork doctor`: Ork's own version against the last
+*   update check, each tool's presence and login status (the drivers' own
+*   checks, which `ork run` also reads to pick the one ready), and whether a
+*   run's socket path fits, and which experiments are on, through an injectable
+*   `exec` so tests need no real tools. Never prints a token or an account.
+*/
+const TIMEOUT_MS = 15e3;
+const exec = (program, args) => new Promise((resolve) => {
+	execFile(program, args, {
+		timeout: TIMEOUT_MS,
+		encoding: "utf8"
+	}, (error, stdout) => {
+		resolve({
+			ok: error === null,
+			stdout
+		});
+	});
+});
+/** Ork's own version, against the last update check (no network). */
+const orkCheck = () => versionCheck(ORK_VERSION, readUpdateCache(updateCachePath()), updateCheckOff(process.env, [], process.stderr.isTTY));
+const MIN_NODE = [24, 20];
+const checkNode = (version) => {
+	const [major = 0, minor = 0] = version.split(".").map(Number);
+	const [minMajor, minMinor] = MIN_NODE;
+	return major > minMajor || major === minMajor && minor >= minMinor ? {
+		name: "node",
+		status: "ok",
+		detail: `v${version}`
+	} : {
+		name: "node",
+		status: "fail",
+		detail: `v${version}`,
+		hint: `Ork needs Node ${MIN_NODE.join(".")} or later.`
+	};
+};
+/** A work tree with no commit has no `HEAD` for a worktree to branch from. */
+const checkHead = async (run) => {
+	return (await run("git", [
+		"rev-parse",
+		"--verify",
+		"HEAD"
+	])).ok ? {
+		name: "git commits",
+		status: "ok",
+		detail: "HEAD exists"
+	} : {
+		name: "git commits",
+		status: "warn",
+		detail: "no commit yet",
+		hint: "Make a first commit: worktree runs branch from HEAD."
+	};
+};
+const checkGit = async (run) => {
+	const version = await run("git", ["--version"]);
+	if (!version.ok) return [{
+		name: "git",
+		status: "fail",
+		detail: "not found",
+		hint: "Install git; Ork gives each writing node its own worktree."
+	}];
+	const inside = await run("git", ["rev-parse", "--is-inside-work-tree"]);
+	const head = inside.ok ? await checkHead(run) : null;
+	return [
+		{
+			name: "git",
+			status: "ok",
+			detail: firstLine(version.stdout)
+		},
+		inside.ok ? {
+			name: "git repo",
+			status: "ok",
+			detail: "inside a work tree"
+		} : {
+			name: "git repo",
+			status: "warn",
+			detail: "not a git repository",
+			hint: "Run Ork inside a git repository so nodes can use worktrees."
+		},
+		...head === null ? [] : [head]
+	];
+};
+/** What `ork init` warns of: a work tree with no commit, else null. */
+const headWarning = async (run) => {
+	const head = (await checkGit(run)).find((r) => r.name === "git commits");
+	return head?.status === "warn" ? `${head.detail}. ${head.hint ?? ""}`.trim() : null;
+};
+/**
+* Runs every check: Node and git, then every registered agent driver and
+* integration (ADR-022). Node, git, and at least one driver are required;
+* integrations are optional.
+*/
+const runChecks = async (run, env, nodeVersion) => {
+	const [git, checked, tools] = await Promise.all([
+		checkGit(run),
+		driverChecks(run, env),
+		Promise.all(INTEGRATIONS.flatMap((i) => i.doctor === void 0 ? [] : [i.doctor(run, env)]))
+	]);
+	const drivers = checked.map(({ result }) => result);
+	const results = [
+		checkNode(nodeVersion),
+		...git,
+		...drivers,
+		...tools
+	];
+	return {
+		results,
+		ok: drivers.some((d) => d.status === "ok") && !results.some((r) => r.status === "fail")
+	};
+};
+/**
+* Whether a run's socket fits under `~` (L38). Past the limit a run can't
+* listen, and nothing else says so: answers, commands and followers fall back
+* to the store, a second at a time. `home` is the user's `~`.
+*/
+const socketCheck = (home, platform) => {
+	const { bytes, max } = socketRoom(home, platform);
+	if (max === void 0 || bytes <= max) return {
+		name: "sockets",
+		status: "ok",
+		detail: max === void 0 ? "not Unix sockets here" : `${String(bytes)} of ${String(max)} bytes`
+	};
+	return {
+		name: "sockets",
+		status: "warn",
+		detail: `a run's socket path is ${String(bytes)} bytes, past the ${String(max)} this system allows`,
+		hint: "Runs still work, but answers, commands and `ork logs --follow` wait up to a second for each, as they read the store instead. A shorter home folder path fixes it."
+	};
+};
+/**
+* What it says of triggers (RFC-011): a long-lived process can die quietly, so
+* a live trigger that hasn't looked when it should have is worth saying. `home`
+* is the user's `~` (tests pass a folder).
+*/
+const triggerChecks = (home) => {
+	const store = openStore(storePath(home));
+	try {
+		const report = triggersReport(store, store.projects(), home);
+		const broken = report.broken.map(({ file, message }) => ({
+			name: "triggers",
+			status: "warn",
+			detail: `${file}: ${message}`,
+			hint: "Its triggers are off until it can be read."
+		}));
+		const live = report.triggers.filter(({ standing }) => standing === "live");
+		if (live.length === 0) return broken;
+		const late = lateTriggers(report, /* @__PURE__ */ new Date());
+		if (late.length === 0) return [...broken, {
+			name: "ork watch",
+			status: "ok",
+			detail: `${String(live.length)} trigger(s) looking`
+		}];
+		return [...broken, {
+			name: "ork watch",
+			status: "warn",
+			detail: `not looking: ${late.map(({ trigger }) => trigger).join(", ")}`,
+			hint: report.pid === void 0 ? "Start it with `ork watch --detach`." : "See `ork watch --status`."
+		}];
+	} finally {
+		store.close();
+	}
+};
+const SOURCE_NAMES = {
+	project: "project file",
+	environment: "environment"
+};
+/**
+* Which experiments are on and who turned them on; an unknown name fails this
+* check alone. Prints names only. Outside a project, only the environment
+* counts.
+*/
+const experimentsCheck = (place, env = process.env, registry = EXPERIMENTS) => {
+	const { project, where } = loadProject(place.root, placeFiles(place).rules);
+	const state = experimentsOn({
+		env,
+		project,
+		where,
+		registry
+	});
+	if (!state.ok) return {
+		name: "experiments",
+		status: "fail",
+		detail: `unknown: ${state.unknown.map((u) => `\`${u.name}\` (${u.where})`).join(", ")}`,
+		hint: `Fix or remove the name. Known experiments: ${knownExperiments(registry)}.`
+	};
+	return {
+		name: "experiments",
+		status: "ok",
+		detail: state.on.length === 0 ? "none on" : state.on.map(({ name, sources }) => `${name} (${sources.map((s) => SOURCE_NAMES[s]).join(" and ")})`).join(", ")
+	};
+};
+// src/run/ready-driver.ts
+/**
+* @file The driver a run takes for the session nodes that name none (core's
+*   `driver.ts` has the whole rule): the one `ork doctor`'s own checks find
+*   ready on this machine, said in one line. With none ready, the run stops
+*   before any session starts, with the hints `ork doctor` gives. A resumed run
+*   keeps the driver it recorded.
+*/
+/** The real checks: the tools on this machine and its environment. */
+const checksHere = () => driverChecks(exec, process.env);
+const subject = (names, all) => {
+	if (all) return "No driver is named, so the run uses";
+	const [only] = names;
+	return names.length === 1 && only !== void 0 ? `${only} names no driver, so it uses` : `${names.join(", ")} name no driver, so they use`;
+};
+/**
+* The driver for `names`, the session nodes that name none, from `checks`.
+* `all` says whether they are every session node of the run.
+*/
+const chooseReadyDriver = (names, all, checks) => {
+	const ready = readyDriver(checks);
+	if (!ready.ok) return {
+		ok: false,
+		lines: [
+			`No agent driver is ready here, and ${names.join(", ")} ${names.length === 1 ? "names" : "name"} none.`,
+			...ready.hints,
+			"See `ork doctor`."
+		]
+	};
+	const why = ready.ready === 1 ? `the one ready here (${ready.detail})` : `more than one is ready, and a run takes ${ready.driver} first`;
+	return {
+		ok: true,
+		driver: ready.driver,
+		line: `${subject(names, all)} the ${ready.driver} driver: ${why}.`
+	};
+};
+/**
+* What a run takes for its session nodes that name no driver: nothing when
+* `--driver` overrides them all or each names one; the driver a resumed run
+* recorded; otherwise the one ready here.
+*/
+const runReadyDriver = async (workflow, options) => {
+	if (options.override !== void 0) return { ok: true };
+	const names = namingNoDriver(workflow);
+	if (names.length === 0) return { ok: true };
+	if (options.recorded !== void 0) return {
+		ok: true,
+		driver: options.recorded
+	};
+	const sessions = Object.values(workflow.nodes).filter((node) => node.type === "claude.leader" || node.type === "claude.worker").length;
+	return chooseReadyDriver(names, names.length === sessions, await (options.checks ?? checksHere)());
+};
+/**
+* What stops a session node from running on its driver, one line each: the
+* driver's declared `capabilities` and `proven` against what the node asks
+* (`drivers` default: the real descriptors; tests pass their own).
+*/
+const unfitLines = (workflow, drivers, choice) => driverRefusals(workflow, drivers ?? AGENT_DRIVERS, choice).map(({ message }) => message);
+// src/run/driver-check.ts
+/**
+* @file `ork validate`'s driver check: each session node against what its
+*   driver declares (core's `driver-needs.ts`), for `--driver` if given, else
+*   the driver a run would take, the one ready here (`ready-driver.ts`).
+*/
+const driverDiagnostics = async (workflow, options) => {
+	const ready = options.override === void 0 && namingNoDriver(workflow).length > 0 ? readyDriver(await (options.checks ?? checksHere)()) : void 0;
+	const drivers = options.drivers ?? AGENT_DRIVERS;
+	const choice = {
+		override: options.override,
+		ready: ready?.ok === true ? ready.driver : void 0
+	};
+	const at = (node, severity, code, message) => {
+		const path = ["nodes", node];
+		const found = {
+			severity,
+			code,
+			message,
+			path
+		};
+		const place = options.locate?.(path);
+		if (place !== null && place !== void 0) {
+			found.line = place.line;
+			found.column = place.column;
+		}
+		return found;
+	};
+	return [...driverRefusals(workflow, drivers, choice).map(({ node, message }) => at(node, "error", "driver.unfit", message)), ...driverQueues(workflow, drivers, choice).filter((found) => found.owner === void 0).flatMap(({ nodes, message }) => nodes.slice(0, 1).map((node) => at(node, "warning", "driver.queues", message)))];
+};
+/** The `--driver` value, or why it is not a driver. */
+const driverArg = (value) => {
+	if (value === void 0) return { ok: true };
+	const parsed = DriverSchema.safeParse(value);
+	return parsed.success ? {
+		ok: true,
+		driver: parsed.data
+	} : {
+		ok: false,
+		error: `--${retiredDriverHint(value) ?? `driver must be one of ${DRIVER_IDS.join(", ")}, got \`${value}\``}`
+	};
+};
+// src/commands/walk-report.ts
+/**
+* @file How `ork validate` shows a walk (RFC-009): one line on what it tried,
+*   and with `--paths`, each way a run can end. A gate's answer that ends the
+*   run shows here as an ending, not as a problem.
+*/
+/** The walk's one line; unless `--paths` is on, it points there for each ending. */
+const walkLine = (walk, showsPaths = false) => walk === void 0 ? [] : [style("dim", showsPaths ? walkSummary(walk) : `${walkSummary(walk)} See each with \`ork validate --paths\`.`)];
+const endingLine = ({ status, notRun, paths }) => {
+	const ways = `${String(paths)} ${paths === 1 ? "way" : "ways"}`;
+	const word = status === "succeeded" ? style("green", status) : style("red", status);
+	const rest = notRun.length === 0 ? "every node ran" : `didn't run: ${notRun.map((id) => plain(id)).join(", ")}`;
+	return `  ${word} ${style("dim", `(${ways})`)} ${rest}`;
+};
+const endingLines = (ending) => [endingLine(ending), ...ending.choices.map((choice) => style("dim", `      ${plain(choice)}`))];
+/** Each ending, the ones that succeeded first, with one way to get there. */
+const pathLines = (walk) => {
+	const endings = walk?.endings ?? [];
+	return [...endings.filter(({ status }) => status === "succeeded"), ...endings.filter(({ status }) => status !== "succeeded")].flatMap((ending) => endingLines(ending));
+};
+// src/commands/validate.ts
+/**
+* @file `ork validate`: loads, parses and compiles workflow files with the
+*   project's rules (`.ork/project.yaml`) and the agents they name, checks
+*   their skill and context references, and reports diagnostics compiler-style,
+*   with file, line and column. `loadWorkflow` is shared with `ork run`.
+*/
+const hasErrors = (diagnostics) => diagnostics.some((d) => d.severity === "error");
+/**
+* Parses and compiles one workflow file, with the agents the user and its
+* project offer. `home` is the user's `~` (tests pass a folder); `registered`
+* the projects a caller's store has, else those of the store in `home`.
+*/
+const loadWorkflow = (file, cwd, home, registered = registeredProjects(home)) => {
+	const absolute = path.resolve(cwd, file);
+	const place = placeFor(path.dirname(absolute), registered);
+	const where = {
+		place,
+		workflowDir: workflowDirOf(place, absolute)
+	};
+	let text;
+	try {
+		text = readFileSync(path.resolve(cwd, file), "utf8");
+	} catch (error) {
+		return {
+			report: {
+				file,
+				diagnostics: [{
+					severity: "error",
+					code: "file.read",
+					message: error instanceof Error && "code" in error && error.code === "ENOENT" ? "file not found" : "cannot read file",
+					path: []
+				}]
+			},
+			workflow: null,
+			graph: null,
+			...where
+		};
+	}
+	const { diagnostics, workflow, graph, summary, locate } = checkWorkflowText(text, {
+		...where,
+		registered,
+		home
+	});
+	return {
+		report: {
+			file,
+			diagnostics,
+			...summary === void 0 ? {} : { summary }
+		},
+		workflow,
+		graph,
+		textHash: workflowTextHash(text),
+		...locate === void 0 ? {} : { locate },
+		...where
+	};
+};
+const validateFile = (file, cwd) => loadWorkflow(file, cwd).report;
+/**
+* Walks what loaded, with its findings on its report. `ork validate` and `ork
+* run` do this; the rest of what loads a workflow doesn't pay for a walk.
+*/
+const walkLoaded = async (loaded) => {
+	const { diagnostics, walk } = await walkChecks({
+		diagnostics: loaded.report.diagnostics,
+		graph: loaded.graph,
+		...loaded.locate === void 0 ? {} : { locate: loaded.locate }
+	});
+	return {
+		...loaded,
+		report: {
+			...loaded.report,
+			diagnostics,
+			...walk === void 0 ? {} : { walk }
+		}
+	};
+};
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+const diagnosticLine = (file, d) => {
+	const where = d.line === void 0 ? file : `${file}:${d.line}:${d.column ?? 1}`;
+	const severity = d.severity === "error" ? style(["red", "bold"], "error") : style(["yellow", "bold"], "warning");
+	return `${style("dim", where)} ${severity} ${d.message} ${style("dim", `(${d.code})`)}`;
+};
+/** The warnings alone, for a run that goes ahead despite them. */
+const warningLines = (report) => report.diagnostics.filter((d) => d.severity === "warning").map((d) => diagnosticLine(report.file, d));
+/** Human-readable report, one line per diagnostic, compiler style. */
+const formatReport = (report, showsPaths = false) => {
+	const lines = report.diagnostics.map((d) => diagnosticLine(report.file, d));
+	const errors = report.diagnostics.filter((d) => d.severity === "error").length;
+	const warnings = report.diagnostics.length - errors;
+	if (report.summary === void 0 && errors === 0) lines.push(`${style("green", "✓")} ${report.file}${warnings === 0 ? "" : style("dim", ` (${plural(warnings, "warning")})`)}`);
+	else if (report.summary !== void 0 && errors === 0) {
+		const { nodes, edges, entries } = report.summary;
+		const extra = warnings > 0 ? `, ${plural(warnings, "warning")}` : "";
+		lines.push(`${style("green", "✓")} ${report.file} ${style("dim", `(${plural(nodes, "node")}, ${plural(edges, "edge")}, starts at ${entries.join(", ")}${extra})`)}`);
+	} else lines.push(`${style("red", "✗")} ${report.file} ${style("dim", `(${plural(errors, "error")}, ${plural(warnings, "warning")})`)}`);
+	return [...lines, ...walkLine(report.walk, showsPaths)];
+};
+const validate = defineCommand({
+	meta: {
+		name: "validate",
+		description: "Check workflow files: schema, ownership tree, edges, loops and references, and walk every way through them"
+	},
+	args: {
+		files: {
+			type: "positional",
+			description: "Workflow files or names in .ork/workflows/ (default: every workflow there, and the project's triggers)",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			description: "Print the reports as JSON",
+			default: false
+		},
+		paths: {
+			type: "boolean",
+			description: "List each way a run can end, and the choices that lead there",
+			default: false
+		},
+		driver: {
+			type: "string",
+			description: "Check the nodes against this driver (default: the one a run would take, the one ready here)"
+		}
+	},
+	run: async ({ args }) => {
+		const driver = driverArg(args.driver);
+		if (!driver.ok) {
+			writeErr(driver.error);
+			process.exitCode = 1;
+			return;
+		}
+		const cwd = process.cwd();
+		if (refusedBuiltin(args._, cwd)) return;
+		const files = findWorkflowFiles(args._, cwd, placeFiles(projectAt(cwd)).workflows);
+		if (files.length === 0) {
+			write("No workflow files found. Run `ork init`, or pass a path.");
+			process.exitCode = 1;
+			return;
+		}
+		const place = projectAt(cwd);
+		const triggers = args._.length === 0 ? readProjectTriggers(place, void 0, registeredProjects()) : void 0;
+		const walked = [];
+		for (const file of files) {
+			const loaded = await walkLoaded(loadWorkflow(file, cwd));
+			const { report } = loaded;
+			if (loaded.workflow !== null) report.diagnostics.push(...await driverDiagnostics(loaded.workflow, {
+				override: driver.driver,
+				locate: loaded.locate
+			}));
+			walked.push(report);
+		}
+		const reports = [...walked, ...triggers?.present === true ? [{
+			file: path.relative(cwd, triggers.file),
+			diagnostics: [...triggers.diagnostics, ...triggers.triggers.flatMap((item) => item.diagnostics)]
+		}] : []];
+		if (args.json) write(JSON.stringify(reports, void 0, 2));
+		else for (const report of reports) {
+			for (const line of formatReport(report, args.paths)) write(line);
+			if (args.paths) for (const line of pathLines(report.walk)) write(line);
+		}
+		if (reports.some((r) => hasErrors(r.diagnostics))) process.exitCode = 1;
+	}
+});
+// src/commands/context.ts
+/**
+* @file `ork context explain <wf> <node>`: what one node's session would load,
+*   layer by layer, as core's `explainSession` plans it without writing
+*   anything (one of Ork's own `ork:` workflows is written into the project's
+*   run folder first, as `ork run` does): its project instructions, every skill
+*   with the layer it came from and whether it is live, shadowed or switched
+*   off, its context files, its practices, and estimated tokens.
+*/
+/** Loads a workflow file and plans one node's session in it, in place. */
+const explainNode = (file, nodeId, cwd, home) => {
+	const { report, workflow, graph, place, workflowDir } = loadWorkflow(file, cwd, home);
+	if (workflow === null) return {
+		ok: false,
+		lines: formatReport(report)
+	};
+	const result = explainSession(workflow, graph, nodeId, {
+		root: place.root,
+		orkDir: place.dir,
+		workflowDir,
+		...home === void 0 ? {} : { home }
+	});
+	return result.ok ? result : {
+		ok: false,
+		lines: [result.error]
+	};
+};
+const approx = (count) => style("dim", `≈${count.toLocaleString("en")} tokens`);
+const formatExplanation = (e) => {
+	const width = Math.max(8, ...e.skills.map((s) => s.name.length));
+	const sourceWidth = Math.max(0, ...e.skills.map((s) => s.source.length));
+	const lines = [
+		`${style("bold", e.node)} ${style("dim", `(${e.type}) in ${e.workflow}`)}${e.template === void 0 ? "" : style("dim", `, planned as ${e.template}, the node it was spawned from`)}`,
+		"",
+		...e.agent === void 0 ? [] : [`${style("bold", "Agent")}  ${e.agent.name} ${style("dim", `(${e.agent.where})`)}  ${approx(e.agent.tokens)}`],
+		`${style("bold", "Instructions")}  ${e.instructions}`,
+		"",
+		style("bold", "Skills")
+	];
+	if (e.skills.length === 0) lines.push(style("dim", "  none"));
+	for (const s of e.skills) {
+		const mark = s.state === "live" ? style("green", "✓") : style("dim", "−");
+		const state = s.why === void 0 ? approx(s.tokens).replace("tokens", "tokens when used") : style("yellow", `off: ${s.why}`);
+		lines.push(`  ${mark} ${s.name.padEnd(width)}  ${s.layer.padEnd(8)}  ${style("dim", s.source.padEnd(sourceWidth))}  ${state}`);
+	}
+	lines.push("", style("bold", "Context files"));
+	if (e.files.length === 0) lines.push(style("dim", "  none"));
+	for (const f of e.files) {
+		const cut = f.cutFrom === void 0 ? "" : `  ${style("yellow", `cut at the ${LESSON_CAP_TOKENS.toLocaleString("en")}-token cap; the whole file is ${approx(f.cutFrom)}`)}`;
+		lines.push(`  ${f.layer.padEnd(8)}  ${f.name}  ${approx(f.tokens)}${cut}`);
+	}
+	lines.push("", style("bold", "Practices"));
+	for (const p of e.practices) lines.push(`  ${p.name.padEnd(8)}  ${approx(p.tokens)}`);
+	for (const name of e.skippedPractices) lines.push(`  ${name.padEnd(8)}  ${style("dim", "the project's own skill wins")}`);
+	if (e.practices.length === 0 && e.skippedPractices.length === 0) lines.push(style("dim", "  off"));
+	lines.push("", `Appended to Claude Code's system prompt: ${approx(e.appendedTokens)}`);
+	return lines;
+};
+const explain = defineCommand({
+	meta: {
+		name: "explain",
+		description: "Show what one node's session loads, layer by layer"
+	},
+	args: {
+		workflow: {
+			type: "positional",
+			description: "A workflow file, the name of one in the project's workflows (.ork/workflows/), or one of Ork's own (ork:feedback-apply)",
+			required: true
+		},
+		node: {
+			type: "positional",
+			description: "Node id",
+			required: true
+		},
+		json: {
+			type: "boolean",
+			description: "Print JSON",
+			default: false
+		}
+	},
+	run: ({ args }) => {
+		const cwd = process.cwd();
+		if (refusedBuiltin([args.workflow], cwd)) return;
+		const result = explainNode(workflowArg(args.workflow, cwd).file, args.node, cwd);
+		if (!result.ok) {
+			for (const line of result.lines) process.stderr.write(`${line}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if (args.json) write(JSON.stringify(result.explanation, void 0, 2));
+		else for (const line of formatExplanation(result.explanation)) write(line);
+	}
+});
+const context = defineCommand({
+	meta: {
+		name: "context",
+		description: "Inspect the context Ork compiles for each node"
+	},
+	subCommands: { explain }
+});
+export { startUpdateCheck as C, showUpdateNotice as S, runChecks as _, validate as a, UPDATE_CHILD_ENV as b, warningLines as c, runReadyDriver as d, unfitLines as f, orkCheck as g, headWarning as h, loadWorkflow as i, checksHere as l, experimentsCheck as m, explainNode as n, validateFile as o, exec as p, formatReport as r, walkLoaded as s, context as t, chooseReadyDriver as u, socketCheck as v, updateCheckOff as w, runUpdateChild as x, triggerChecks as y };