@rulvar/cli 1.22.0 → 1.24.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as processIo } from "./io-RtHEIn0r.js";
+import { r as runCli, t as processIo } from "./io-CL4wldEQ.js";
 import { inspect } from "node:util";
 //#region src/cli.ts
 /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as resumeCommand, c as driveRun, d as renderEventLine, f as DEFAULT_STORE_DIR, g as looksLikeFile, h as loadWorkflowModule, i as inspectCommand, l as reportOutcome, m as loadCliConfig, n as HELP, o as runCommand, p as assembleEngine, r as runCli, s as runsLsCommand, t as processIo, u as attachProgress } from "./io-RtHEIn0r.js";
+import { a as resumeCommand, c as driveRun, d as renderEventLine, f as DEFAULT_STORE_DIR, g as looksLikeFile, h as loadWorkflowModule, i as inspectCommand, l as reportOutcome, m as loadCliConfig, n as HELP, o as runCommand, p as assembleEngine, r as runCli, s as runsLsCommand, t as processIo, u as attachProgress } from "./io-CL4wldEQ.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**

package/dist/{io-RtHEIn0r.js → io-CL4wldEQ.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
+import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
@@ -190,18 +190,21 @@ function renderEventLine(event) {
 }
 function rawEventLine(event) {
 	const replayMark = event.replayed === true ? "replay " : "";
+	const str = (value) => typeof value === "string" ? value : "";
+	const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : 0;
+	const who = str(event.agentType) || "(anon)";
 	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}`;
+		case "run:start": return `run ${str(event.runId)} ${event.resumed === true ? "resumed" : "started"} (workflow ${str(event.workflow)})`;
+		case "phase:start": return `phase ${str(event.phase)}`;
+		case "agent:start": return `${replayMark}agent ${who}${str(event.label) === "" ? "" : ` [${str(event.label)}]`} ${str(event.role)} on ${str(event.model)}`;
+		case "agent:end": return `${replayMark}agent ${who} ${str(event.status)} (${money(num(event.costUsd))}, ${String(num(event.usage?.inputTokens) + num(event.usage?.outputTokens))} tok)`;
+		case "agent:error": return `agent ${who} error: ${str(event.error?.message)}${event.willRetry === true ? " (will retry)" : ""}`;
+		case "agent:queued": return `agent ${who} queued`;
+		case "tool:start": return `${replayMark}tool ${str(event.toolName)}`;
+		case "tool:end": return `${replayMark}tool ${str(event.toolName)} ${str(event.outcome)} (${String(num(event.durationMs))}ms)`;
+		case "approval:pending": return `approval pending: tool ${str(event.toolName)} (entry ${String(num(event.entryRef))})`;
+		case "log": return event.level === "debug" ? void 0 : `${str(event.level)}: ${str(event.msg)}`;
+		case "run:end": return `run ${str(event.runId)} ${str(event.status)}`;
 		default: return;
 	}
 }
@@ -300,6 +303,35 @@ async function driveRun(options) {
 		handle = options.engine.resume(handle.runId, options.workflow, { args: options.args });
 	}
 }
+/**
+* Renders the `resume --dry-run` preview (the v1.23.0 review): the
+* replay accounting from `handle.preview`, then what a real resume
+* would do. The engine's replay-strict mode guarantees zero journal or
+* meta writes and zero adapter calls. A preview that stops at a
+* would-be-live call is a SUCCESSFUL preview (the miss IS the answer),
+* so the exit code is 0 either way; only structural failures (missing
+* run, unregistered workflow, args refusal) exit nonzero via their
+* typed errors.
+*/
+async function reportDryRun(handle, io) {
+	const outcome = await handle.result;
+	const preview = await handle.preview;
+	io.err("dry-run preview (zero journal or meta writes, zero adapter calls):");
+	io.err(`  hits: ${preview.hits}  misses: ${preview.misses}  reruns: ${preview.reruns}  skipped: ${preview.skipped}`);
+	io.err(preview.orphaned.length === 0 ? "  orphaned effect roots: none" : `  orphaned effect roots (entryRefs): ${preview.orphaned.join(", ")}`);
+	if (preview.invalidResolutions.length === 0) io.err("  invalid resolutions: none");
+	else for (const invalid of preview.invalidResolutions) io.err(`  invalid resolution at seq ${invalid.seq}: ${invalid.detail}`);
+	if (outcome.error?.code === "journal_miss") {
+		io.err(`  stopped at the first would-be-live call: ${outcome.error.message}`);
+		io.err("  a real resume would perform new paid work from this point");
+		return 0;
+	}
+	io.err(`  would settle: ${outcome.status}`);
+	if (outcome.error !== void 0) io.err(`  error: ${outcome.error.message}`);
+	for (const pending of outcome.pending) io.err(`  pending: ${pending.key} (entry ${pending.entryRef})`);
+	if (outcome.value !== void 0) io.out(JSON.stringify(outcome.value, null, 2));
+	return 0;
+}
 /** Renders the settled outcome; returns the process exit code. */
 function reportOutcome(outcome, io) {
 	io.err(`status: ${outcome.status}`);
@@ -363,7 +395,12 @@ const GRAMMAR = {
 	resume: {
 		command: "resume",
 		positionals: ["<runId>"],
-		flags: [ARGS, STORE]
+		flags: [
+			ARGS,
+			STORE,
+			{ name: "dry-run" },
+			{ name: "allow-args-change" }
+		]
 	},
 	"runs ls": {
 		command: "runs ls",
@@ -642,10 +679,52 @@ async function runCommand(argv, context) {
 		args
 	}), context.io);
 }
+/**
+* The resume args safety gate (the v1.23.0 review): a run's logical
+* identity includes its genesis args, so a resume that silently drops,
+* adds, or changes them is refused BEFORE the engine starts (zero
+* provider calls, zero journal writes). `--allow-args-change` is the
+* explicit override for every divergence class; legacy runs recorded
+* before the binding existed require it (or explicit `--args`) because
+* nothing can be verified against them.
+*/
+function enforceArgsBinding(input) {
+	const { meta, argsGiven, args, allowChange, io } = input;
+	if (meta.argsProvided === void 0) {
+		if (!argsGiven && !allowChange) throw new ConfigError(`run '${meta.runId}' predates the args binding (rulvar < 1.24.0), so the CLI cannot tell whether it was started with --args, and resuming without them silently changes the logical run if any were used at start. Re-supply the original --args, or acknowledge explicitly with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+		if (argsGiven) io.err(`warning: run '${meta.runId}' predates the args binding; the supplied --args cannot be verified against the original invocation`);
+		return;
+	}
+	if (meta.argsProvided) {
+		if (!argsGiven) {
+			if (!allowChange) throw new ConfigError(`run '${meta.runId}' was started WITH args, but this resume supplies none; the workflow would see undefined and every args-dependent call would become new paid work instead of a replay. Re-supply the original --args, or force the change with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+			io.err(`warning: resuming '${meta.runId}' without its genesis args (--allow-args-change)`);
+			return;
+		}
+		if (meta.argsHash === void 0) {
+			io.err(`warning: run '${meta.runId}' recorded args presence but no hash (the genesis args were not JCS-serializable); the supplied --args cannot be verified`);
+			return;
+		}
+		const supplied = hashRunArgs(args);
+		if (supplied !== meta.argsHash) {
+			if (!allowChange) throw new ConfigError(`--args does not match the args run '${meta.runId}' was started with (recorded hash ${meta.argsHash.slice(0, 12)}, supplied ${supplied?.slice(0, 12) ?? "none"}); changed args silently change the logical run and re-pay every args-dependent call. Force deliberately with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+			io.err(`warning: resuming '${meta.runId}' with changed args (--allow-args-change)`);
+		}
+		return;
+	}
+	if (argsGiven) {
+		if (!allowChange) throw new ConfigError(`run '${meta.runId}' was started WITHOUT args, but this resume supplies some; added args silently change the logical run. Drop --args, or force the change with --allow-args-change; ${usageOf(GRAMMAR.resume)}`);
+		io.err(`warning: resuming no-args run '${meta.runId}' with args (--allow-args-change)`);
+	}
+}
 async function resumeCommand(argv, context) {
 	const parsed = parseCommand(GRAMMAR.resume, argv);
 	const runId = parsed.positionals[0];
-	const args = parseArgsJson(parsed.values.args);
+	const rawArgs = parsed.values.args;
+	const args = parseArgsJson(rawArgs);
+	const argsGiven = rawArgs !== void 0;
+	const dryRun = parsed.values["dry-run"] === true;
+	const allowChange = parsed.values["allow-args-change"] === true;
 	const store = parsed.values.store;
 	const assembled = assembleEngine({
 		config: await loadCliConfig(context.cwd),
@@ -654,10 +733,21 @@ async function resumeCommand(argv, context) {
 	});
 	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`);
+	enforceArgsBinding({
+		meta,
+		argsGiven,
+		args,
+		allowChange,
+		io: context.io
+	});
 	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 (resume requires the in-process workflow value)`);
-	const first = assembled.engine.resume(runId, workflow, { args });
+	const first = assembled.engine.resume(runId, workflow, {
+		args,
+		...dryRun ? { dryRun: true } : {}
+	});
+	if (dryRun) return await reportDryRun(first, context.io);
 	return reportOutcome(await driveRun({
 		engine: assembled.engine,
 		workflow,
@@ -698,6 +788,7 @@ async function inspectCommand(argv, context) {
 	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}`);
+	if (meta.argsProvided !== void 0) context.io.out(meta.argsProvided ? `args at genesis: provided${meta.argsHash === void 0 ? " (no hash: not JCS-serializable)" : ` (hash ${meta.argsHash})`}` : "args at genesis: none");
 	const byKind = /* @__PURE__ */ new Map();
 	let openSuspensions = 0;
 	const resolvedRefs = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Rulvar shell: run/resume/runs/inspect/plan/kb commands, TUI progress, createServer, createWorker, OTel exporter.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,17 +22,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.22.0"
+    "@rulvar/core": "1.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/planner": "1.22.0",
-    "@rulvar/plan": "1.22.0",
-    "@rulvar/store-sqlite": "1.22.0",
-    "@rulvar/evals": "1.22.0",
-    "@rulvar/testing": "1.22.0"
+    "@rulvar/testing": "1.24.0",
+    "@rulvar/store-sqlite": "1.24.0",
+    "@rulvar/planner": "1.24.0",
+    "@rulvar/evals": "1.24.0",
+    "@rulvar/plan": "1.24.0"
   },
   "bin": {
     "rulvar": "./dist/cli.js"