pi-plans 0.5.7 → 0.6.0

package/src/run-picker.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared run picker (v0.6.0 multi-run support): a descriptive selector form
+ * used by /plans-abandon, /plans-execute, and /resume-plans whenever more than
+ * one candidate run exists in the workdir. Labels show topic · status · skill ·
+ * updated_at, width-fitted; the recommended run (session binding or shared
+ * active) is listed first.
+ */
+
+import * as path from "node:path";
+import { readdirSync } from "node:fs";
+import { boundRunId } from "./run-context.ts";
+import { listRuns, TERMINAL_RUN_STATUSES, type RunSummary } from "./state.ts";
+import { truncateToWidth, visibleWidth } from "./refine-ui-helpers.ts";
+
+export interface RunPickerContext {
+	cwd: string;
+	sessionManager: unknown;
+	ui: {
+		select: (title: string, options: string[]) => Promise<string | undefined>;
+	};
+}
+
+/** Pick-window budget: keep labels to one selector row in normal terminals. */
+const LABEL_WIDTH_BUDGET = 88;
+
+/** True when the run's artifact dir contains at least one PLAN_vN.md. */
+function hasPlanFile(run: RunSummary): boolean {
+	try {
+		return readdirSync(run.artifact_dir).some((name) => /^PLAN_v\d+\.md$/i.test(name));
+	} catch {
+		return false;
+	}
+}
+
+/** Non-terminal runs (planning/accepted/executing/stopped) with ≥1 plan file. */
+export function executionCandidates(workdir: string): RunSummary[] {
+	return listRuns(workdir).filter((run) => !TERMINAL_RUN_STATUSES.has(run.status) && hasPlanFile(run));
+}
+
+/** Non-terminal runs (anything that can still be abandoned). */
+export function abandonCandidates(workdir: string): RunSummary[] {
+	return listRuns(workdir).filter((run) => !TERMINAL_RUN_STATUSES.has(run.status));
+}
+
+/** One-line descriptive label: topic · status · skill · updated_at. */
+export function runPickerLabel(run: RunSummary, recommended: boolean): string {
+	const label = `${recommended ? "★ " : ""}${run.topic} · ${run.status} · ${run.skill} · ${run.updated_at} · ${run.run_id}`;
+	if (visibleWidth(label) <= LABEL_WIDTH_BUDGET) return label;
+	return truncateToWidth(label, LABEL_WIDTH_BUDGET, "");
+}
+
+/**
+ * Show the descriptive run picker. Returns the chosen RunSummary, or null when
+ * cancelled / no UI. `candidates` must be pre-sorted newest-first (listRuns
+ * order); the recommended run is moved to the front.
+ */
+export async function pickRun(
+	ctx: RunPickerContext,
+	options: { candidates: RunSummary[]; recommendedId?: string | null; title: string },
+): Promise<RunSummary | null> {
+	const candidates = [...options.candidates];
+	if (options.recommendedId) {
+		const index = candidates.findIndex((run) => run.run_id === options.recommendedId);
+		if (index > 0) {
+			const [recommended] = candidates.splice(index, 1);
+			candidates.unshift(recommended);
+		}
+	}
+	const labels = candidates.map((run) => runPickerLabel(run, run.run_id === options.recommendedId));
+	const selected = await ctx.ui.select(options.title, labels);
+	if (selected === undefined) return null;
+	const index = labels.indexOf(selected);
+	return candidates[index] ?? null;
+}
+
+/**
+ * Resolve the run a command should operate on, binding-first:
+ * 1. the session-bound run when it is among the candidates;
+ * 2. exactly one candidate → direct (no form — 0.5.7 parity);
+ * 3. zero candidates → null;
+ * 4. multiple candidates → the descriptive picker (recommended = bound run).
+ */
+export async function resolveCommandRun(
+	ctx: RunPickerContext,
+	options: { candidates: RunSummary[]; title: string },
+): Promise<RunSummary | null> {
+	const bound = boundRunId(ctx.sessionManager, ctx.cwd);
+	const boundCandidate = bound ? options.candidates.find((run) => run.run_id === bound) ?? null : null;
+	if (boundCandidate !== null) return boundCandidate;
+	if (options.candidates.length === 0) return null;
+	if (options.candidates.length === 1) return options.candidates[0];
+	return pickRun(ctx, { ...options, recommendedId: bound });
+}
+
+/** Convert a RunSummary into the ActiveInfo shape used downstream. */
+export function activeInfoOf(run: RunSummary, stateRoot: string): { run_id: string; run_dir: string; artifact_dir: string } {
+	return { run_id: run.run_id, run_dir: path.join(stateRoot, "runs", run.run_id), artifact_dir: run.artifact_dir };
+}

package/src/state.ts

@@ -51,6 +51,8 @@ export interface PlansConfig {
 	/** null = never asked; the plans tool surfaces a hint so the agent asks once. */
 	graph_enabled: boolean | null;
 	graph_enabled_updated_at: string | null;
+	/** Delegated executor child timeout in minutes (v0.6.0). 0/absent = default (60). */
+	executor_timeout_minutes?: number;
 }
 
 const DEFAULT_ARTIFACT_ROOT = "./docs/pi-plans";
@@ -137,6 +139,93 @@ export interface ActiveInfo {
 	artifact_dir: string;
 }
 
+/** Lightweight registry view of one run (RunInfo minus the heavy fields). */
+export interface RunSummary {
+	run_id: string;
+	topic: string;
+	skill: string;
+	status: string;
+	created_at: string;
+	updated_at: string;
+	artifact_dir: string;
+}
+
+/** Terminal statuses: a run that can no longer be resumed or guarded. */
+export const TERMINAL_RUN_STATUSES = new Set(["abandoned", "done"]);
+
+function summarize(run: RunInfo): RunSummary {
+	return {
+		run_id: run.run_id,
+		topic: run.topic,
+		skill: run.skill,
+		status: run.status,
+		created_at: run.created_at,
+		updated_at: run.updated_at,
+		artifact_dir: run.artifact_dir,
+	};
+}
+
+/**
+ * Filesystem-derived run registry (v0.6.0): scans `<stateRoot>/runs/<runId>/run.json`
+ * and returns summaries sorted by `updated_at` desc (ties go to run_id desc so the
+ * newest-created run wins within one timestamp tick). Corrupt or partial run
+ * dirs are skipped, never thrown. This replaces the racy shared `active.json`
+ * pointer: there is no new shared mutable file, and per-run files are written
+ * only by the flow that owns the run.
+ */
+export function listRuns(workdir: string): RunSummary[] {
+	const stateRoot = resolveStateRootOrNull(workdir);
+	if (stateRoot === null) return [];
+	const runsRoot = path.join(stateRoot, "runs");
+	let entries: string[] = [];
+	try {
+		entries = fs.readdirSync(runsRoot);
+	} catch {
+		return [];
+	}
+	const summaries: Array<RunSummary & { mtimeMs: number }> = [];
+	for (const entry of entries) {
+		const runPath = path.join(runsRoot, entry, "run.json");
+		if (!existsSync(runPath)) continue;
+		try {
+			const run = JSON.parse(readFileSync(runPath, "utf8")) as RunInfo;
+			if (typeof run?.run_id !== "string" || typeof run?.status !== "string") continue;
+			// utcNow() has second precision: same-second runs tie on updated_at, so
+			// the per-run run.json mtime (written only by the owning flow) is the
+		// race-free recency tie-break.
+			summaries.push({ ...summarize(run), mtimeMs: Number(fs.statSync(runPath, { bigint: true }).mtimeNs) / 1e6 });
+	} catch {
+			/* corrupt run.json: skip, never fail the registry scan */
+		}
+	}
+	summaries.sort((a, b) =>
+		a.updated_at === b.updated_at
+			? a.mtimeMs === b.mtimeMs
+				? (a.run_id < b.run_id ? 1 : -1)
+				: b.mtimeMs - a.mtimeMs
+			: a.updated_at < b.updated_at ? 1 : -1,
+	);
+	return summaries.map(({ mtimeMs: _mtimeMs, ...summary }) => summary);
+}
+
+/** The newest non-terminal run (planning/accepted/executing/stopped), or null. */
+export function newestNonTerminalRun(workdir: string): RunSummary | null {
+	return listRuns(workdir).find((run) => !TERMINAL_RUN_STATUSES.has(run.status)) ?? null;
+}
+
+/** The newest run of ANY status — display-only (status widget), never attribution. */
+export function latestRun(workdir: string): RunSummary | null {
+	return listRuns(workdir)[0] ?? null;
+}
+
+function activeInfoFromSummary(stateRoot: string, run: RunSummary): ActiveInfo {
+	return {
+		run_id: run.run_id,
+		run_dir: path.join(stateRoot, "runs", run.run_id),
+		artifact_dir: run.artifact_dir,
+	};
+}
+
 export interface DecisionEntry {
 	question: string;
 	options: string[];
@@ -442,7 +531,15 @@ export function startRun(workdir: string, options: StartRunOptions): StartRunRes
 	let artifactRoot = config.artifact_root ?? DEFAULT_ARTIFACT_ROOT;
 	if (!path.isAbsolute(artifactRoot)) artifactRoot = path.resolve(workdir, artifactRoot);
 	const dateSlug = now.slice(0, 10);
-	const artifactDir = path.join(artifactRoot, `${dateSlug}-${topicSlug}`);
+	const baseArtifactDir = path.join(artifactRoot, `${dateSlug}-${topicSlug}`);
+	// v0.6.0: same-topic runs on the same day (concurrent sessions) must not
+	// share an artifact directory — suffix until unused, mirroring the run-id loop.
+	let artifactDir = baseArtifactDir;
+	let artifactSuffix = 2;
+	while (existsSync(artifactDir)) {
+		artifactDir = `${baseArtifactDir}-${artifactSuffix}`;
+		artifactSuffix += 1;
+	}
 	const runDir = path.join(stateRoot, "runs", runId);
 	mkdirSync(runDir, { recursive: true });
 	mkdirSync(artifactDir, { recursive: true });
@@ -464,11 +561,8 @@ export function startRun(workdir: string, options: StartRunOptions): StartRunRes
 		const ledger = path.join(runDir, name);
 		if (!existsSync(ledger)) writeFileSync(ledger, "", "utf8");
 	}
-	atomicWriteJson(path.join(stateRoot, "active.json"), {
-		run_id: runId,
-		run_dir: runDir,
-		artifact_dir: artifactDir,
-	} satisfies ActiveInfo);
+	// v0.6.0: the shared active.json pointer is no longer written — the run
+	// registry is derived from runs/*/run.json (race-free across sessions).
 	if (options.onStart) {
 		try {
 			options.onStart(run);
@@ -479,10 +573,19 @@ export function startRun(workdir: string, options: StartRunOptions): StartRunRes
 	return { run, notices };
 }
 
-/** Read the active run pointer; read-only, returns null when absent. */
+/**
+ * v0.6.0 registry-backed resolution (replaces the shared `active.json`
+ * pointer): the newest NON-TERMINAL run, or null when every run is terminal.
+ * Legacy fallback: when the scan finds zero runs but a pre-0.6.0 `active.json`
+ * exists, honor it once (one-release migration shim; deprecation is surfaced
+ * on the `/plans` and `/resume-plans` command surfaces, not here — this is a
+ * read-only hot path with no notices channel).
+ */
 export function readActive(workdir: string): ActiveInfo | null {
 	const stateRoot = resolveStateRootOrNull(workdir);
 	if (stateRoot === null) return null;
+	const newest = newestNonTerminalRun(workdir);
+	if (newest !== null) return activeInfoFromSummary(stateRoot, newest);
 	const activePath = path.join(stateRoot, "active.json");
 	if (!existsSync(activePath)) return null;
 	try {

package/src/subagent.ts

@@ -40,6 +40,16 @@ export interface SubagentOptions {
 	timeoutMs?: number;
 	/** Optional normalized progress sink. Exceptions from the sink are ignored. */
 	onProgress?: (event: SubagentProgressEvent) => void;
+	/**
+	 * Child env marker (v0.6.0): "refiner" (default — read-only reviewer/
+	 * criticizer/ref-analyst children; sets PI_PLANS_REFINER=1, which the code
+	 * graph gates treat as read-only), "executor" (delegated plan executor;
+	 * sets PI_PLANS_EXECUTOR=1 so the write guard and the graph-aware file
+	 * tools bypass staging and run natively), or "none".
+	 */
+	envMarker?: "refiner" | "executor" | "none";
+	/** Pin the run id a delegated executor child operates on (PI_PLANS_RUN_ID). */
+	runId?: string;
 }
 
 export interface SubagentResult {
@@ -283,6 +293,37 @@ function emitProgress(options: SubagentOptions, event: SubagentProgressEvent): v
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 
+/**
+ * Build the child process env for a subagent run (v0.6.0): refiner children
+ * carry PI_PLANS_REFINER=1, executor children PI_PLANS_EXECUTOR=1 plus an
+ * optional PI_PLANS_RUN_ID pin, and marker keys never leak across kinds.
+ */
+export function subagentChildEnv(
+	options: Pick<SubagentOptions, "envMarker" | "runId">,
+	parentEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	const childEnv: NodeJS.ProcessEnv = { ...parentEnv };
+	switch (options.envMarker ?? "refiner") {
+		case "refiner":
+			childEnv.PI_PLANS_REFINER = "1";
+			delete childEnv.PI_PLANS_EXECUTOR;
+			delete childEnv.PI_PLANS_RUN_ID;
+			break;
+		case "executor":
+			childEnv.PI_PLANS_EXECUTOR = "1";
+			delete childEnv.PI_PLANS_REFINER;
+			if (options.runId) childEnv.PI_PLANS_RUN_ID = options.runId;
+			else delete childEnv.PI_PLANS_RUN_ID;
+			break;
+		case "none":
+			delete childEnv.PI_PLANS_REFINER;
+			delete childEnv.PI_PLANS_EXECUTOR;
+			delete childEnv.PI_PLANS_RUN_ID;
+			break;
+	}
+	return childEnv;
+}
+
 export async function runPiSubagent(options: SubagentOptions): Promise<SubagentResult> {
 	const tools = options.tools ?? ["read", "grep", "find", "ls"];
 	let tmpDir = "";
@@ -322,7 +363,7 @@ export async function runPiSubagent(options: SubagentOptions): Promise<SubagentR
 				cwd: options.cwd,
 				shell: false,
 				stdio: ["ignore", "pipe", "pipe"],
-				env: { ...process.env, PI_PLANS_REFINER: "1" },
+				env: subagentChildEnv(options),
 			});
 			let buffer = "";
 			let closed = false;

package/src/workflow-state.ts

@@ -144,6 +144,9 @@ export interface ExecutionCheckpoint {
 	reverifyAll?: boolean;
 	/** True when this approval/progress was produced in a different (origin) worktree. */
 	originWorktree?: string;
+	/** v0.6.0: set while a delegated executor child owns the implementation;
+	 * stale after a restart (orphaned delegate — the child died with the parent). */
+	delegate?: { modelSelector: string; startedAt: string };
 }
 
 export interface OwnerInfo {
@@ -451,7 +454,7 @@ function asExecution(value: unknown, label: string): ExecutionCheckpoint {
 	const record = asRecord(value, label);
 	rejectExtraKeys(
 		record,
-		new Set(["approval", "doneVcIds", "implStatus", "currentI", "usage", "pausedReason", "reverifyAll", "originWorktree"]),
+		new Set(["approval", "doneVcIds", "implStatus", "currentI", "usage", "pausedReason", "reverifyAll", "originWorktree", "delegate"]),
 		label,
 	);
 	const execution: ExecutionCheckpoint = {
@@ -473,6 +476,14 @@ function asExecution(value: unknown, label: string): ExecutionCheckpoint {
 	if (record.pausedReason !== undefined) execution.pausedReason = asString(record.pausedReason, `${label}.pausedReason`);
 	if (record.reverifyAll !== undefined) execution.reverifyAll = asBool(record.reverifyAll, `${label}.reverifyAll`);
 	if (record.originWorktree !== undefined) execution.originWorktree = asString(record.originWorktree, `${label}.originWorktree`);
+	if (record.delegate !== undefined && record.delegate !== null) {
+		const delegate = asRecord(record.delegate, `${label}.delegate`);
+		rejectExtraKeys(delegate, new Set(["modelSelector", "startedAt"]), `${label}.delegate`);
+		execution.delegate = {
+			modelSelector: asString(delegate.modelSelector, `${label}.delegate.modelSelector`),
+			startedAt: asString(delegate.startedAt, `${label}.delegate.startedAt`),
+		};
+	}
 	return execution;
 }
 
@@ -1035,6 +1046,8 @@ export interface ExecutionProgressInput {
 	currentI?: string;
 	usage?: { inToks: number; outToks: number };
 	pausedReason?: string | null;
+	/** v0.6.0: set/clear the delegated-executor record; null clears it. */
+	delegate?: { modelSelector: string; startedAt: string } | null;
 }
 
 export function applyExecutionProgress(cp: WorkflowCheckpoint, progress: ExecutionProgressInput): WorkflowCheckpoint {
@@ -1051,6 +1064,8 @@ export function applyExecutionProgress(cp: WorkflowCheckpoint, progress: Executi
 	}
 	if (progress.pausedReason === null) delete execution.pausedReason;
 	else if (progress.pausedReason !== undefined) execution.pausedReason = progress.pausedReason;
+	if (progress.delegate === null) delete execution.delegate;
+	else if (progress.delegate !== undefined) execution.delegate = progress.delegate;
 	return { ...cp, execution };
 }
 
@@ -1148,7 +1163,8 @@ function migrationNextAction(cp: WorkflowCheckpoint): NextAction {
 /** Mark a paused stop without erasing the last phase (D-008). */
 export function applyExecutionStopped(cp: WorkflowCheckpoint, reason: string): WorkflowCheckpoint {
 	if (cp.phase !== "executing" || !cp.execution) throw new StateError("requires phase \"executing\"");
-	return { ...cp, execution: { ...cp.execution, pausedReason: reason } };
+	const { delegate: _delegate, ...execution } = cp.execution;
+	return { ...cp, execution: { ...execution, pausedReason: reason } };
 }
 
 // ---------------------------------------------------------------------------

package/tests/ask-choice-pros-cons.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Feature 5 (v0.6.0): every AI-written ask_choice option must state its
+ * advantage AND its drawback as '✓ <advantage> / ✗ <drawback>' in the
+ * configured language.
+ *
+ * The rule is SOFT GUIDANCE (deliberately — no runtime validation, no new
+ * schema fields), so these tests pin the *contract text* the model actually
+ * reads: the Option schema, the tool description, the promptGuidelines, the
+ * batch/single `options` arrays, the six skills, and the normative reference
+ * doc. They also prove the convention is actually RENDERABLE by the existing
+ * form renderer, so guidance can never drift away from what users see.
+ */
+
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, it } from "node:test";
+import { Value } from "typebox/value";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Option, AskChoiceParams, BatchQuestionParams, registerAskChoiceTool } from "../tools/ask-choice.ts";
+import { createFormState, formRender, type FormQuestion } from "../src/ask-form.ts";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const PRO = "✓";
+const CON = "✗";
+
+interface ToolDef {
+	name: string;
+	description: string;
+	promptSnippet: string;
+	promptGuidelines: string[];
+	parameters: unknown;
+	execute: (id: string, params: unknown, signal: undefined, update: undefined, ctx: unknown) => Promise<unknown>;
+}
+
+function loadTool(): ToolDef {
+	let tool: ToolDef | undefined;
+	const pi = { registerTool: (definition: ToolDef) => { tool = definition; } } as unknown as ExtensionAPI;
+	registerAskChoiceTool(pi);
+	if (!tool) throw new Error("ask_choice tool not registered");
+	return tool;
+}
+
+/** Read a TypeBox property description out of a schema object. */
+function propertyDescription(schema: unknown, property: string): string {
+	const properties = (schema as { properties?: Record<string, { description?: string }> }).properties;
+	const found = properties?.[property]?.description;
+	assert.equal(typeof found, "string", `expected a description on property ${property}`);
+	return found!;
+}
+
+const SKILL_DIRS = ["planning", "debug-and-plan", "plan-small", "plan-normal", "plan-big", "plan-with-refs"];
+
+describe("ask_choice pros/cons contract (v0.6.0 feature 5)", () => {
+	it("Option.description requires both halves via the ✓ / ✗ markers", () => {
+		const text = propertyDescription(Option, "description");
+		assert.ok(text.includes(PRO), "description must show the advantage marker");
+		assert.ok(text.includes(CON), "description must show the drawback marker");
+		assert.ok(/drawback/i.test(text), "description must name the drawback half");
+		assert.ok(/advantage/i.test(text), "description must name the advantage half");
+		assert.ok(/configured language/i.test(text), "description must pin the configured language");
+	});
+
+	it("the registered tool description states the rule and exempts the tool-appended tails", () => {
+		const tool = loadTool();
+		assert.ok(tool.description.includes(PRO) && tool.description.includes(CON));
+		assert.ok(/advantage/i.test(tool.description) && /drawback/i.test(tool.description));
+		assert.ok(/Other/.test(tool.description) && /Auto-complete/.test(tool.description));
+	});
+
+	it("promptGuidelines carry the rule as an imperative, not as new schema fields", () => {
+		const tool = loadTool();
+		assert.ok(Array.isArray(tool.promptGuidelines));
+		const joined = tool.promptGuidelines.join("\n");
+		assert.ok(joined.includes(PRO) && joined.includes(CON), "a guideline must carry the markers");
+		assert.ok(/drawback/i.test(joined), "a guideline must name the drawback half");
+		// The failure mode this guards: a model inventing `pros`/`cons` keys,
+		// which Option rejects (additionalProperties: false).
+		assert.ok(
+			/no separate pros\/cons fields|there are no separate pros\/cons fields/i.test(joined),
+			"guidelines must forbid inventing pros/cons fields",
+		);
+	});
+
+	it("both the batch and single-question options arrays propagate the rule", () => {
+		const batch = propertyDescription(BatchQuestionParams, "options");
+		assert.ok(batch.includes(PRO) && batch.includes(CON));
+		assert.ok(/configured language/i.test(batch));
+
+		const single = propertyDescription(AskChoiceParams, "options");
+		assert.ok(single.includes(PRO) && single.includes(CON));
+		assert.ok(/configured language/i.test(single));
+	});
+
+	it("every skill states the per-option pros/drawbacks rule", () => {
+		for (const dir of SKILL_DIRS) {
+			const file = path.join(ROOT, "skills", dir, "SKILL.md");
+			const text = fs.readFileSync(file, "utf8");
+			assert.ok(text.includes(PRO), `${dir}: must show the advantage marker`);
+			assert.ok(text.includes(CON), `${dir}: must show the drawback marker`);
+		}
+	});
+
+	it("the normative workflow doc states the rule at the options clause", () => {
+		const text = fs.readFileSync(path.join(ROOT, "references", "pi-planning-workflow.md"), "utf8");
+		const optionsBullet = text.split("\n").find((line) => line.startsWith("- `options`:"));
+		assert.ok(optionsBullet, "the options clause must exist");
+		assert.ok(optionsBullet!.includes(PRO) && optionsBullet!.includes(CON));
+		assert.ok(/configured language/i.test(optionsBullet!));
+		assert.ok(/accept\/execute/.test(optionsBullet!), "the handoff must be in scope");
+	});
+
+	it("the convention is renderable by the existing form renderer", () => {
+		const question: FormQuestion = {
+			question: "Which storage approach?",
+			options: [
+				{ label: "Reuse the existing table", description: `${PRO} no migration / ${CON} needs a backfill`, recommended: true },
+				{ label: "Add a new table", description: `${PRO} clean isolation / ${CON} doubles write cost` },
+			],
+			allowOther: true,
+			questionId: "q1",
+			autoComplete: true,
+		};
+		const rows = formRender(createFormState([question]), 100);
+		const rendered = rows.join("\n");
+		assert.ok(rendered.includes(PRO), "the advantage half must reach the user");
+		assert.ok(rendered.includes(CON), "the drawback half must reach the user");
+		assert.ok(rendered.includes("no migration"), "the advantage text must be shown");
+		assert.ok(rendered.includes("backfill"), "the drawback text must be shown");
+	});
+
+	it("a convention-following option still validates against the Option schema", () => {
+		// No new keys: the whole point of riding `description` is that the
+		// existing schema accepts it unchanged.
+		const ok = Value.Check(Option, {
+			label: "Reuse the existing table",
+			description: `${PRO} no migration / ${CON} needs a backfill`,
+			recommended: true,
+		});
+		assert.equal(ok, true);
+		// And stray pros/cons keys are still rejected loudly.
+		const stray = Value.Check(Option, { label: "x", pros: "a", cons: "b" });
+		assert.equal(stray, false);
+	});
+});