@rulvar/cli 1.0.0

package/dist/io-DUfUn6KG.js

@@ -0,0 +1,702 @@
+import { ConfigError, FileModelKnowledgeStore, JsonlFileStore, claimExpired, compilePermissionPreset, costReportFromJournal, createEngine, parseModelRef, priceUsdOf, remeasureQueue, resolvePricing, runProfile } from "@rulvar/core";
+import { parseArgs } from "node:util";
+import { join, resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline";
+//#region src/config.ts
+/**
+* CLI configuration convention (shell-owned; the canonical grammar in
+* docs/06 section 10.5 says nothing about engine assembly, and the CLI
+* builds exclusively from the public API per docs/02 section 4):
+*
+* - `rulvar.config.mjs` (or .js) in the working directory default-exports
+*   `{ engineOptions?, workflows? }`: adapters, stores, defaults come
+*   from the HOST's module, so @rulvar/cli itself depends only on
+*   @rulvar/core.
+* - `rulvar run <file>` imports the module at <file>: its default export
+*   (or named `workflow`) is the Workflow; optional named exports
+*   `engineOptions` and `workflows` merge OVER the config file's.
+* - `rulvar run <name>` and `rulvar resume <runId>` resolve names
+*   against the merged workflow registry (config first, file second).
+*/
+const CONFIG_BASENAMES = ["rulvar.config.mjs", "rulvar.config.js"];
+/**
+* ESM caches by URL for the process lifetime; a CLI process imports each
+* module once, but long-lived hosts (and the e2e suite) re-read edited
+* configs, so the mtime rides the URL.
+*/
+function moduleUrl(path) {
+	return `${pathToFileURL(path).href}?mtime=${statSync(path).mtimeMs}`;
+}
+function isWorkflowValue(value) {
+	return typeof value === "object" && value !== null && typeof value.name === "string" && typeof value.body === "function";
+}
+/** Loads `rulvar.config.mjs`/`.js` from cwd; absent config is fine. */
+async function loadCliConfig(cwd) {
+	for (const basename of CONFIG_BASENAMES) {
+		const path = resolve(cwd, basename);
+		if (!existsSync(path)) continue;
+		const mod = await import(moduleUrl(path));
+		const config = mod.default;
+		if (config !== void 0 && isWorkflowValue(config)) throw new ConfigError(`${basename} default-exports a workflow; it must default-export { engineOptions?, workflows? }`);
+		return {
+			...config ?? {},
+			...mod.engineOptions === void 0 ? {} : { engineOptions: mod.engineOptions },
+			...mod.workflows === void 0 ? {} : { workflows: mod.workflows }
+		};
+	}
+	return {};
+}
+/** Imports a workflow module given on the command line. */
+async function loadWorkflowModule(file, cwd) {
+	const path = resolve(cwd, file);
+	if (!existsSync(path)) throw new ConfigError(`workflow file not found: ${path}`);
+	const mod = await import(moduleUrl(path));
+	const candidate = mod.workflow ?? mod.default;
+	const loaded = {};
+	if (candidate !== void 0 && isWorkflowValue(candidate)) loaded.workflow = candidate;
+	if (mod.engineOptions !== void 0) loaded.engineOptions = mod.engineOptions;
+	if (mod.workflows !== void 0) loaded.workflows = mod.workflows;
+	return loaded;
+}
+/** True when the `run` target names a file rather than a registry entry. */
+function looksLikeFile(target) {
+	return target.includes("/") || target.includes("\\") || /\.(ts|mts|cts|js|mjs|cjs)$/.test(target);
+}
+//#endregion
+//#region src/engine-assembly.ts
+/**
+* Engine assembly for CLI commands: the host's config supplies adapters
+* and defaults (the CLI depends only on @rulvar/core, docs/02 section
+* 4); --store selects the JsonlFileStore directory (default `.rulvar`),
+* and an explicit stores entry in engineOptions wins over it.
+*/
+const DEFAULT_STORE_DIR = ".rulvar";
+function assembleEngine(options) {
+	const { config, module } = options;
+	let engineOptions = {
+		...config.engineOptions,
+		...module?.engineOptions
+	};
+	if (options.profile !== void 0) {
+		const profile = runProfile(options.profile);
+		if (profile === void 0) throw new ConfigError(`unknown run profile '${options.profile}'; shipped: fast, standard, deep, ultra`);
+		engineOptions = applyRunProfile(profile, engineOptions);
+	}
+	const store = engineOptions.stores?.journal ?? new JsonlFileStore({ dir: resolve(options.cwd, options.storePath ?? ".rulvar") });
+	const workflows = {
+		...config.workflows,
+		...module?.workflows
+	};
+	const adapters = engineOptions.adapters ?? [];
+	const engine = createEngine({
+		adapters,
+		...engineOptions,
+		stores: {
+			...engineOptions.stores,
+			journal: store
+		},
+		defaults: {
+			...engineOptions.defaults,
+			workflows
+		}
+	});
+	const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+	const priceUsd = (servedBy, usage) => {
+		const { adapterId, model } = parseModelRef(servedBy);
+		const pricing = resolvePricing(servedBy, engineOptions.pricing, byId.get(adapterId)?.caps(model).pricing);
+		return pricing === void 0 ? void 0 : priceUsdOf(pricing, usage);
+	};
+	return {
+		engine,
+		store,
+		workflows,
+		priceUsd
+	};
+}
+/**
+* Merges a RunProfile UNDER host engineOptions (host wins). Effort hints
+* seed per-role defaults on routing entries that carry none; concurrency
+* and budget defaults fill unset slots; the permission preset applies to
+* the engine-wide chain when the host set none.
+*/
+function applyRunProfile(profile, host) {
+	const merged = { ...host };
+	if (profile.perRunConcurrency !== void 0) merged.concurrency = {
+		perRun: profile.perRunConcurrency,
+		...host.concurrency
+	};
+	if (profile.lifetimeSpawnCap !== void 0 || profile.maxDepth !== void 0) merged.budgetDefaults = {
+		...profile.lifetimeSpawnCap === void 0 ? {} : { lifetimeSpawnCap: profile.lifetimeSpawnCap },
+		...profile.maxDepth === void 0 ? {} : { maxDepth: profile.maxDepth },
+		...host.budgetDefaults
+	};
+	if (profile.permissionPreset !== void 0 && host.defaults?.permissions === void 0) {
+		const compiled = compilePermissionPreset(profile.permissionPreset);
+		merged.defaults = {
+			...host.defaults,
+			permissions: compiled
+		};
+	}
+	return merged;
+}
+//#endregion
+//#region src/tui.ts
+function money(usd) {
+	return `$${usd.toFixed(4)}`;
+}
+/** Renders one event to a line, or undefined for silent event types. */
+function renderEventLine(event) {
+	const replayMark = event.replayed === true ? "replay " : "";
+	switch (event.type) {
+		case "run:start": return `run ${event.runId} ${event.resumed ? "resumed" : "started"} (workflow ${event.workflow})`;
+		case "phase:start": return `phase ${event.phase}`;
+		case "agent:start": return `${replayMark}agent ${event.agentType || "(anon)"}${event.label === void 0 ? "" : ` [${event.label}]`} ${event.role} on ${event.model}`;
+		case "agent:end": return `${replayMark}agent ${event.agentType || "(anon)"} ${event.status} (${money(event.costUsd)}, ${event.usage.inputTokens + event.usage.outputTokens} tok)`;
+		case "agent:error": return `agent ${event.agentType || "(anon)"} error: ${event.error.message}${event.willRetry ? " (will retry)" : ""}`;
+		case "agent:queued": return `agent ${event.agentType || "(anon)"} queued`;
+		case "tool:start": return `${replayMark}tool ${event.toolName}`;
+		case "tool:end": return `${replayMark}tool ${event.toolName} ${event.outcome} (${event.durationMs}ms)`;
+		case "approval:pending": return `approval pending: tool ${event.toolName} (entry ${event.entryRef})`;
+		case "log": return event.level === "debug" ? void 0 : `${event.level}: ${event.msg}`;
+		case "run:end": return `run ${event.runId} ${event.status}`;
+		default: return;
+	}
+}
+/** Attaches the renderer to a handle's event stream; returns a detach. */
+function attachProgress(handle, io) {
+	const detachers = [];
+	const forward = (event) => {
+		const line = renderEventLine(event);
+		if (line !== void 0) io.err(line);
+	};
+	for (const type of [
+		"run:start",
+		"phase:start",
+		"agent:start",
+		"agent:end",
+		"agent:error",
+		"agent:queued",
+		"tool:start",
+		"tool:end",
+		"approval:pending",
+		"log",
+		"run:end"
+	]) detachers.push(handle.on(type, forward));
+	return () => {
+		for (const detach of detachers) detach();
+	};
+}
+//#endregion
+//#region src/drive.ts
+const APPROVAL_PREFIX = "approval:";
+/** Parses an approval answer; undefined = unusable input. */
+function approvalDecision(answer) {
+	const normalized = answer.trim().toLowerCase();
+	if ([
+		"allow",
+		"a",
+		"yes",
+		"y"
+	].includes(normalized)) return { decision: "allow" };
+	if ([
+		"deny",
+		"d",
+		"no",
+		"n"
+	].includes(normalized)) return { decision: "deny" };
+}
+/**
+* Prompts for and applies resolutions for every pending suspension.
+* Returns the number applied; 0 means input was exhausted or unusable
+* and the run stays suspended.
+*/
+async function resolvePending(handle, pending, io) {
+	let applied = 0;
+	for (const item of pending) {
+		if (item.key.startsWith(APPROVAL_PREFIX)) {
+			const answer = await io.prompt(`approve '${item.prompt ?? item.key}'? [allow/deny]`);
+			if (answer === void 0) return applied;
+			const decision = approvalDecision(answer);
+			if (decision === void 0) {
+				io.err(`unrecognized answer '${answer.trim()}'; leaving ${item.key} suspended`);
+				continue;
+			}
+			const outcome = await handle.resolveExternal(item.key, decision);
+			io.err(`approval ${item.key}: ${decision.decision} (${outcome.applied ? "applied" : outcome.reason})`);
+			if (outcome.applied) applied += 1;
+			continue;
+		}
+		const label = item.prompt === void 0 ? item.key : `${item.key} (${item.prompt})`;
+		const answer = await io.prompt(`value for external '${label}' as JSON:`);
+		if (answer === void 0) return applied;
+		let value;
+		try {
+			value = JSON.parse(answer);
+		} catch {
+			io.err(`not valid JSON; leaving '${item.key}' suspended`);
+			continue;
+		}
+		const outcome = await handle.resolveExternal(item.key, value);
+		io.err(`external '${item.key}': ${outcome.applied ? "applied" : outcome.reason}`);
+		if (outcome.applied) applied += 1;
+	}
+	return applied;
+}
+/**
+* Drives a handle to a terminal outcome, resolving suspensions
+* interactively and resuming until the run settles or input runs dry.
+*/
+async function driveRun(options) {
+	let handle = options.first;
+	for (;;) {
+		const detach = attachProgress(handle, options.io);
+		const outcome = await handle.result;
+		detach();
+		if (outcome.status !== "suspended" || outcome.pending.length === 0) return outcome;
+		if (await resolvePending(handle, outcome.pending, options.io) === 0) return outcome;
+		handle = options.engine.resume(handle.runId, options.workflow, { args: options.args });
+	}
+}
+/** Renders the settled outcome; returns the process exit code. */
+function reportOutcome(outcome, io) {
+	io.err(`status: ${outcome.status}`);
+	if (outcome.value !== void 0) io.out(JSON.stringify(outcome.value, null, 2));
+	if (outcome.error !== void 0) io.err(`error: ${outcome.error.message}`);
+	if (outcome.dropped.length > 0) io.err(`dropped: ${outcome.dropped.length} item(s)`);
+	for (const pending of outcome.pending) io.err(`pending: ${pending.key} (entry ${pending.entryRef})`);
+	io.err(`cost: $${outcome.cost.totalUsd.toFixed(4)}`);
+	for (const [model, usd] of Object.entries(outcome.cost.byModel)) io.err(`  by model ${model}: $${usd.toFixed(4)}`);
+	for (const [phase, usd] of Object.entries(outcome.cost.byPhase)) if (phase !== "") io.err(`  by phase ${phase}: $${usd.toFixed(4)}`);
+	if (outcome.cost.unpriced.length > 0) io.err(`unpriced models: ${outcome.cost.unpriced.map((u) => u.model).join(", ")}`);
+	switch (outcome.status) {
+		case "ok":
+		case "suspended": return 0;
+		default: return 1;
+	}
+}
+//#endregion
+//#region src/commands.ts
+/**
+* The four M5 commands of the canonical CLI grammar (docs/06, section
+* 10.5; no aliases in v1):
+*
+*   rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]
+*   rulvar resume <runId>  [--store PATH]
+*   rulvar runs ls         [--store PATH]
+*   rulvar inspect <runId> [--store PATH]
+*
+* `plan` and `kb` land with M6+/M10. Every command builds strictly from
+* the public @rulvar/core API (docs/02, section 4).
+*/
+function parseRunFlags(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			args: { type: "string" },
+			store: { type: "string" },
+			"budget-usd": { type: "string" },
+			profile: { type: "string" }
+		}
+	});
+	const parsed = { positionals };
+	if (values.store !== void 0) parsed.store = values.store;
+	if (values.profile !== void 0) parsed.profile = values.profile;
+	if (values.args !== void 0) parsed.args = values.args;
+	if (values["budget-usd"] !== void 0) {
+		const budget = Number(values["budget-usd"]);
+		if (!Number.isFinite(budget) || budget <= 0) throw new ConfigError(`--budget-usd must be a positive number, got '${values["budget-usd"]}'`);
+		parsed.budgetUsd = budget;
+	}
+	return parsed;
+}
+function parseCommonFlags(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: { store: { type: "string" } }
+	});
+	return {
+		positionals,
+		...values.store === void 0 ? {} : { store: values.store }
+	};
+}
+async function runCommand(argv, context) {
+	const flags = parseRunFlags(argv);
+	const target = flags.positionals[0];
+	if (target === void 0) throw new ConfigError("usage: rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]");
+	const config = await loadCliConfig(context.cwd);
+	const module = looksLikeFile(target) ? await loadWorkflowModule(target, context.cwd) : void 0;
+	const assembled = assembleEngine({
+		config,
+		...module === void 0 ? {} : { module },
+		...flags.store === void 0 ? {} : { storePath: flags.store },
+		...flags.profile === void 0 ? {} : { profile: flags.profile },
+		cwd: context.cwd
+	});
+	const workflow = module?.workflow ?? assembled.workflows[target];
+	if (workflow === void 0) throw new ConfigError(looksLikeFile(target) ? `${target} exports no workflow (default export or named 'workflow')` : `no workflow named '${target}' in the registry; register it in rulvar.config.mjs`);
+	let args;
+	if (flags.args !== void 0) try {
+		args = JSON.parse(flags.args);
+	} catch {
+		throw new ConfigError(`--args is not valid JSON: ${flags.args}`);
+	}
+	const runOptions = { ...flags.budgetUsd === void 0 ? {} : { budgetUsd: flags.budgetUsd } };
+	const first = assembled.engine.run(workflow, args, runOptions);
+	context.io.err(`runId: ${first.runId}`);
+	return reportOutcome(await driveRun({
+		engine: assembled.engine,
+		workflow,
+		first,
+		io: context.io,
+		args
+	}), context.io);
+}
+async function resumeCommand(argv, context) {
+	const flags = parseRunFlags(argv);
+	const runId = flags.positionals[0];
+	if (runId === void 0) throw new ConfigError("usage: rulvar resume <runId> [--args JSON] [--store PATH]");
+	let args;
+	if (flags.args !== void 0) try {
+		args = JSON.parse(flags.args);
+	} catch {
+		throw new ConfigError(`--args is not valid JSON: ${flags.args}`);
+	}
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...flags.store === void 0 ? {} : { storePath: flags.store },
+		cwd: context.cwd
+	});
+	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
+	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	const name = meta.workflowName;
+	const workflow = name === void 0 ? void 0 : assembled.workflows[name];
+	if (workflow === void 0) throw new ConfigError(`run '${runId}' was started from workflow '${name ?? "(unknown)"}'; register it under that name in rulvar.config.mjs workflows to resume (docs/06, section 10.2: resume requires the in-process workflow value)`);
+	const first = assembled.engine.resume(runId, workflow, { args });
+	return reportOutcome(await driveRun({
+		engine: assembled.engine,
+		workflow,
+		first,
+		io: context.io,
+		args
+	}), context.io);
+}
+async function runsLsCommand(argv, context) {
+	const flags = parseCommonFlags(argv);
+	const metas = await assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...flags.store === void 0 ? {} : { storePath: flags.store },
+		cwd: context.cwd
+	}).store.listRuns();
+	if (metas.length === 0) {
+		context.io.err("no runs in the store");
+		return 0;
+	}
+	for (const meta of metas) {
+		const workflow = meta.workflowName === void 0 ? "" : ` workflow=${meta.workflowName}`;
+		const name = meta.name === void 0 ? "" : ` name=${meta.name}`;
+		context.io.out(`${meta.runId} ${meta.status} updated=${meta.updatedAt}${workflow}${name}`);
+	}
+	return 0;
+}
+async function inspectCommand(argv, context) {
+	const flags = parseCommonFlags(argv);
+	const runId = flags.positionals[0];
+	if (runId === void 0) throw new ConfigError("usage: rulvar inspect <runId> [--store PATH]");
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...flags.store === void 0 ? {} : { storePath: flags.store },
+		cwd: context.cwd
+	});
+	const meta = (await assembled.store.listRuns()).find((m) => m.runId === runId);
+	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	const entries = await assembled.store.load(runId);
+	context.io.out(`run ${meta.runId}: ${meta.status} (updated ${meta.updatedAt})`);
+	if (meta.workflowName !== void 0) context.io.out(`workflow: ${meta.workflowName}`);
+	const byKind = /* @__PURE__ */ new Map();
+	let openSuspensions = 0;
+	const resolvedRefs = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		byKind.set(entry.kind, (byKind.get(entry.kind) ?? 0) + 1);
+		if (entry.kind === "resolution" && typeof entry.ref === "number") resolvedRefs.add(entry.ref);
+	}
+	for (const entry of entries) if ((entry.kind === "external" || entry.kind === "approval") && entry.status === "suspended") {
+		if (!resolvedRefs.has(entry.seq)) openSuspensions += 1;
+	}
+	context.io.out(`entries: ${entries.length}`);
+	for (const [kind, count] of [...byKind.entries()].sort((a, b) => a[0].localeCompare(b[0]))) context.io.out(`  ${kind}: ${count}`);
+	context.io.out(`open suspensions: ${openSuspensions}`);
+	const cost = costReportFromJournal(entries, assembled.priceUsd);
+	context.io.out(`cost: $${cost.totalUsd.toFixed(4)}`);
+	for (const [model, usd] of Object.entries(cost.byModel)) context.io.out(`  ${model}: $${usd.toFixed(4)}`);
+	for (const item of cost.unpriced) context.io.out(`  unpriced: ${item.model} (${item.usage.inputTokens + item.usage.outputTokens} tok)`);
+	for (const entry of entries) {
+		const status = entry.status === void 0 ? "" : ` ${entry.status}`;
+		const served = entry.servedBy === void 0 ? "" : ` servedBy=${entry.servedBy}`;
+		context.io.out(`#${entry.seq} ${entry.kind}${status}${served}`);
+	}
+	return 0;
+}
+/**
+* rulvar plan "<goal>" [--dry-run] (docs/06, 10.5; M6-T11): plans a
+* workflow script through @rulvar/planner (loaded dynamically: the CLI's
+* static dependency stays @rulvar/core only, docs/02 dependency rules),
+* prints the accepted script and its advisories, and runs it in the
+* worker sandbox unless --dry-run.
+*/
+async function planCommand(argv, context) {
+	const parsed = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: { "dry-run": { type: "boolean" } }
+	});
+	const goal = parsed.positionals[0];
+	if (goal === void 0 || parsed.positionals.length > 1) throw new ConfigError("usage: rulvar plan \"<goal>\" [--dry-run]");
+	let plannerModule;
+	try {
+		plannerModule = await import("./dist-DtuSmcav.js");
+	} catch {
+		throw new ConfigError("rulvar plan requires @rulvar/planner (the plan agent, compileScript, and the worker sandbox live there); install it next to the CLI");
+	}
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		cwd: context.cwd
+	});
+	const planned = await plannerModule.plan(assembled.engine, goal);
+	context.io.err(`plan: accepted with ${String(planned.lint.length)} advisory diagnostic(s)`);
+	for (const diagnostic of planned.lint) context.io.err(`  ${diagnostic.ruleId}: ${diagnostic.message}`);
+	if (parsed.values["dry-run"] === true) {
+		context.io.out(planned.source);
+		return 0;
+	}
+	const workflow = planned.workflow;
+	const first = assembled.engine.run(workflow, null);
+	context.io.err(`runId: ${first.runId}`);
+	return reportOutcome(await driveRun({
+		engine: assembled.engine,
+		workflow,
+		first,
+		io: context.io,
+		args: null
+	}), context.io);
+}
+/**
+* rulvar kb list (docs/06, 10.5; docs/05, 4.4; M10-T04): the second
+* consumption path. Claims with full provenance for the humans who
+* author ladders, floors, and profiles; no run and no pin, so model
+* names render VERBATIM here (only in-run cards are nameless). Reads
+* the per-project file store (./rulvar.models.json). The grammar
+* members inbox (phase 3) and sweep (phase 2) fail loudly until their
+* phases ship.
+*/
+async function kbCommand(argv, context) {
+	const [sub, ...rest] = argv;
+	if (sub === "inbox") throw new ConfigError("rulvar kb inbox arrives with ModelKnowledge phase 3 (M12, gated by the measured-value checkpoint; docs/05, section \"Phases and placement\")");
+	if (sub === "sweep") return await kbSweepCommand(rest, context);
+	if (sub !== "list" || rest.length > 0) throw new ConfigError("usage: rulvar kb <list | inbox | sweep> (no aliases in v1)");
+	const snapshot = await new FileModelKnowledgeStore({ path: join(context.cwd, "rulvar.models.json") }).current();
+	context.io.out(`knowledge store: rulvar.models.json (version ${String(snapshot.version)}, ${String(snapshot.claims.length)} claim${snapshot.claims.length === 1 ? "" : "s"})`);
+	renderKbList(snapshot, context);
+	return 0;
+}
+function renderKbList(snapshot, context) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	for (const claim of snapshot.claims) {
+		const effort = claim.subject.effort === void 0 ? "" : ` effort=${claim.subject.effort}`;
+		const ttl = claim.status === "active" ? claimExpired(claim, now) ? " TTL EXPIRED" : " TTL holds" : "";
+		context.io.out(`${claim.id} [${claim.status}${ttl}] ${claim.subject.model}${effort} :: ${claim.taskClass} ${claim.polarity} (${claim.class}, confidence ${claim.confidence})`);
+		context.io.out(`  ${claim.statement}`);
+		context.io.out(`  observed=${claim.observedAt} expires=${claim.expiresAt} author=${claim.author.kind}:${claim.author.id} gate=${claim.author.kind === "human" ? "human (git review)" : "eval-committer"}`);
+		const evidence = claim.evidence.map((ref) => ref.kind === "journal" ? `journal ${ref.runId}#${String(ref.entryRef)}` : `eval ${ref.reportId} [${ref.caseIds.join(", ")}]`).join("; ");
+		context.io.out(`  evidence: ${evidence}`);
+		if (claim.metrics !== void 0) context.io.out(`  metrics: passRate=${String(claim.metrics.passRate)} n=${String(claim.metrics.n)} grader=${claim.metrics.graderId}`);
+		if (claim.supersedes !== void 0) context.io.out(`  supersedes: ${claim.supersedes}`);
+		if (claim.origin !== void 0) context.io.out(`  origin: ${claim.origin.kind} run=${claim.origin.runId}#${String(claim.origin.entryRef)}`);
+	}
+}
+/**
+* rulvar kb sweep (M11-T05; docs/05, section "Grounding and decay"):
+* falsification sweeps, run manually, from CI, or from a user cron,
+* NEVER engine-scheduled. The matrix is the config's FIXED pool
+* UNIONED with the store's falsification set: every model carrying an
+* active, unexpired negative claim MUST be included, and the
+* re-measurement queue (expired active eval claims) rides along. With
+* canary probes configured, drift flips stale strictly BEFORE the
+* sweep re-measures.
+*/
+async function kbSweepCommand(argv, context) {
+	if (argv.length > 0) throw new ConfigError("usage: rulvar kb sweep (configuration lives in rulvar.config.mjs)");
+	const config = await loadCliConfig(context.cwd);
+	const sweep = config.kbSweep;
+	if (sweep === void 0) throw new ConfigError("rulvar kb sweep requires a kbSweep section in rulvar.config.mjs ({ committerId, models, cases }; docs/05, section 'Grounding and decay')");
+	let evals;
+	try {
+		evals = await import("./dist-4eKFSpyW.js");
+	} catch {
+		throw new ConfigError("rulvar kb sweep requires @rulvar/evals (matrix sweeps, the eval-committer identity, and the canary live there); install it next to the CLI");
+	}
+	const store = new FileModelKnowledgeStore({ path: join(context.cwd, "rulvar.models.json") });
+	const snapshot = await store.current();
+	const observedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const memberKey = (member) => `${member.model} :: ${member.effort ?? ""}`;
+	const pool = /* @__PURE__ */ new Map();
+	for (const member of sweep.models) pool.set(memberKey(member), {
+		member,
+		origin: "config"
+	});
+	for (const claim of snapshot.claims) if (claim.status === "active" && claim.polarity === "weakness" && !claimExpired(claim, observedAt)) {
+		const member = { ...claim.subject };
+		if (!pool.has(memberKey(member))) pool.set(memberKey(member), {
+			member,
+			origin: "falsification (active negative claim)"
+		});
+	}
+	for (const claim of remeasureQueue(snapshot.claims, observedAt)) {
+		const member = { ...claim.subject };
+		if (!pool.has(memberKey(member))) pool.set(memberKey(member), {
+			member,
+			origin: "re-measure (expired eval claim)"
+		});
+	}
+	if (pool.size === 0) {
+		context.io.out("kb sweep: the pool is empty (no configured models, no falsification targets)");
+		return 0;
+	}
+	const base = config.engineOptions ?? {};
+	const engineFor = sweep.engineFor ?? ((member) => createEngine({
+		...base,
+		adapters: base.adapters ?? [],
+		defaults: {
+			...base.defaults,
+			routing: {
+				...base.defaults?.routing,
+				loop: member.model,
+				extract: member.model
+			}
+		}
+	}));
+	for (const { member, origin } of pool.values()) {
+		const effort = member.effort === void 0 ? "" : ` effort=${member.effort}`;
+		context.io.out(`pool: ${member.model}${effort} [${origin}]`);
+	}
+	if (sweep.canary !== void 0) for (const { member } of pool.values()) {
+		const engine = await engineFor(member);
+		const fingerprint = await evals.canaryFingerprint(engine, sweep.canary);
+		const drift = await evals.flipStaleOnCanaryDrift(store, member.model, fingerprint);
+		context.io.out(`canary ${member.model}: ${fingerprint.slice(0, 12)}...` + (drift.flipped.length === 0 ? " no drift" : ` DRIFT, ${String(drift.flipped.length)} claim(s) flipped stale`));
+	}
+	const report = await evals.runSweepMatrix({
+		models: [...pool.values()].map((entry) => entry.member),
+		cases: sweep.cases
+	}, {
+		reportId: sweep.reportId ?? `kb-sweep-${observedAt}`,
+		committerId: sweep.committerId,
+		observedAt,
+		engineFor,
+		store,
+		...sweep.thresholds === void 0 ? {} : { thresholds: sweep.thresholds }
+	});
+	for (const cell of report.cells) context.io.out(`cell ${cell.model} :: ${cell.taskClass}: passRate ${cell.passRate.toFixed(2)} over ${String(cell.n)} case${cell.n === 1 ? "" : "s"}`);
+	for (const claim of report.claims) context.io.out(`claim ${claim.id}: ${claim.taskClass} ${claim.polarity}`);
+	context.io.out(report.committedVersion === void 0 ? "no claims crossed a threshold; nothing committed" : `committed ${String(report.claims.length)} claim(s) as store version ${String(report.committedVersion)} (report ${report.reportId})`);
+	return 0;
+}
+//#endregion
+//#region src/cli-main.ts
+/**
+* Command dispatch for the canonical grammar (docs/06, section 10.5):
+* no aliases in v1; unknown commands and flags fail loudly with usage.
+*/
+const HELP = `rulvar: durable multi-agent workflows (docs/06, section 10.5)
+
+  rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]
+  rulvar resume <runId>  [--store PATH]
+  rulvar runs ls         [--store PATH]
+  rulvar inspect <runId> [--store PATH]
+  rulvar plan "<goal>"   [--dry-run]
+  rulvar kb <list | inbox | sweep>
+
+Engine assembly: adapters, defaults, and the workflow registry come from
+rulvar.config.mjs in the working directory (default export
+{ engineOptions?, workflows? }) or from the workflow module's named
+exports. --store selects the JsonlFileStore directory (default .rulvar).
+plan asks the planner model (role plan) to write a workflow script,
+lints and self-repairs it, then runs it in the worker sandbox; --dry-run
+prints the accepted script without running. Requires @rulvar/planner
+installed. kb list shows the per-project claim store
+(./rulvar.models.json) with full provenance. kb sweep runs the
+falsification matrix from the kbSweep section of rulvar.config.mjs
+(fixed pool UNIONED with every model carrying an active negative claim
+plus the re-measure queue; optional canary probes flip drifted claims
+stale first; requires @rulvar/evals installed). kb inbox arrives with
+ModelKnowledge phase 3.`;
+async function runCli(argv, options) {
+	const [command, ...rest] = argv;
+	const context = {
+		cwd: options.cwd,
+		io: options.io
+	};
+	try {
+		switch (command) {
+			case "run": return await runCommand(rest, context);
+			case "resume": return await resumeCommand(rest, context);
+			case "runs": {
+				const [sub, ...subRest] = rest;
+				if (sub !== "ls") throw new ConfigError("usage: rulvar runs ls [--store PATH] (no aliases in v1)");
+				return await runsLsCommand(subRest, context);
+			}
+			case "inspect": return await inspectCommand(rest, context);
+			case "plan": return await planCommand(rest, context);
+			case "kb": return await kbCommand(rest, context);
+			case void 0:
+			case "help":
+			case "--help":
+			case "-h":
+				options.io.out(HELP);
+				return command === void 0 ? 1 : 0;
+			default: throw new ConfigError(`unknown command '${command}' (no aliases in v1); see rulvar --help`);
+		}
+	} catch (thrown) {
+		if (thrown instanceof ConfigError) {
+			options.io.err(`error: ${thrown.message}`);
+			return 1;
+		}
+		throw thrown;
+	}
+}
+//#endregion
+//#region src/io.ts
+/**
+* CLI io seam: every command writes and prompts through this interface
+* so the e2e suite drives the real command paths in-process with
+* scripted stdin and captured output (docs/02, section 8.1: the CLI is
+* a shell strictly on top of the public APIs).
+*/
+/** The process-backed io the bin entry uses. */
+function processIo() {
+	return {
+		out: (line) => process.stdout.write(`${line}\n`),
+		err: (line) => process.stderr.write(`${line}\n`),
+		isTTY: process.stdout.isTTY === true,
+		prompt: (question) => new Promise((resolve) => {
+			const rl = createInterface({
+				input: process.stdin,
+				output: process.stderr
+			});
+			let settled = false;
+			rl.question(`${question} `, (answer) => {
+				settled = true;
+				rl.close();
+				resolve(answer);
+			});
+			rl.on("close", () => {
+				if (!settled) resolve(void 0);
+			});
+		})
+	};
+}
+//#endregion
+export { resumeCommand as a, driveRun as c, renderEventLine as d, DEFAULT_STORE_DIR as f, looksLikeFile as g, loadWorkflowModule as h, inspectCommand as i, reportOutcome as l, loadCliConfig as m, HELP as n, runCommand as o, assembleEngine as p, runCli as r, runsLsCommand as s, processIo as t, attachProgress as u };