@gobing-ai/spur 0.3.91 → 0.3.93

package/plugins/sp/scripts/feature-verification-steps.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env bun
+/**
+ * feature-verification-steps — the single writer of feature verification
+ * receipts behind the `feature-verification` workflow (task 0915, remediated
+ * to the frozen v1 contract; no public CLI verb exists by design).
+ *
+ * Usage (workflow onEnter, vars: featureId, verificationCmd, spurBin, __runId):
+ *   bun plugins/sp/scripts/feature-verification-steps.ts verify \
+ *     --feature-id D63 --run-id <runId> --cmd "bun run spur-check-feature"
+ *
+ * One pass, in order:
+ *   1. resolve the selected `feature-verification` definition (project override
+ *      wins) for the verifier identity + configured command,
+ *   2. capture the before proof-input digest, record the RUNNING receipt (both
+ *      copies) and register the run-scoped receipt as a run artifact,
+ *   3. run the effective command via the safe launch splitter (never `sh -c`
+ *      interpolation), output to the run-scoped log,
+ *   4. capture the after digest — a mismatch records FAIL,
+ *   5. complete the receipt PASS/FAIL (both copies) and the coarse status file.
+ *
+ * Always exits 0 after verify; the transition guard reads the status file and
+ * the completion boundary validates the receipt (fail-closed). Unsafe ids are
+ * refused outright. Node-builtin imports only (ADR-065); the application seams come
+ * from the generated inline bundle (`plugins/sp/lib/inline-run.generated.mjs`) — never
+ * from `packages/app/src/index.ts`, which is not a plugin-script contract surface (0948 R3).
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+    closeSync,
+    existsSync,
+    mkdirSync,
+    openSync,
+    readdirSync,
+    readFileSync,
+    renameSync,
+    writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '../lib/env';
+
+/** Single safe filename component — same class as the inline-run-setup run-id guard. */
+const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Shape of the generated inline bundle / repo app source this script consumes. */
+interface VerificationModule {
+    startFeatureVerificationReceipt: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['startFeatureVerificationReceipt'];
+    completeFeatureVerificationReceipt: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['completeFeatureVerificationReceipt'];
+    captureFeatureReceiptDigest: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['captureFeatureReceiptDigest'];
+    resolveWorkflowDefinition: typeof import('../../packages/app/src/workflow/workflow-resolver')['resolveWorkflowDefinition'];
+    splitLaunchCommand: typeof import('../../packages/app/src/workflow/split-launch-command')['splitLaunchCommand'];
+    openInlineRunProjectDb: typeof import('../../packages/app/src/services/inline-run-setup')['openInlineRunProjectDb'];
+    ArtifactDao: new (
+        adapter: never,
+    ) => { record: (input: { runId: string; path: string; kind: string }) => Promise<unknown> };
+}
+
+/** Explicit module surface. Source is not the contract; the generated bundle is (0948 R3). */
+type ModuleMode = 'source' | 'bundle';
+
+function bundleEntry(): string {
+    return fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url));
+}
+
+/**
+ * Source mode names the mode and the fix. The app source entry does not export
+ * the verification seams, and "rebuild/install the sp plugin" cannot add them.
+ */
+function sourceModeError(spurBin: string): Error {
+    return new Error(
+        `source mode: refusing to load packages/app/src/index.ts (spurBin=${JSON.stringify(spurBin)}). ` +
+            'That entry is not the feature-verification contract surface — it does not export ' +
+            'splitLaunchCommand / ArtifactDao. Fix: run in bundle mode so ' +
+            'plugins/sp/lib/inline-run.generated.mjs is loaded (omit --module-mode, or pass --module-mode bundle) ' +
+            'and regenerate that bundle if it is missing. Reinstalling the sp plugin does not add these seams to the app source entry.',
+    );
+}
+
+function resolveModuleMode(raw: string): ModuleMode {
+    if (raw === '' || raw === 'bundle') return 'bundle';
+    if (raw === 'source') return 'source';
+    throw new Error(`unknown --module-mode ${JSON.stringify(raw)}; expected "source" or "bundle"`);
+}
+
+/**
+ * Bundle mode loads the generated inline bundle. Source mode fails closed with a named fix.
+ *
+ * `spurBin` no longer selects the module (it named the *caller's* CLI entry, not this
+ * script's runtime surface); it is kept only to make the failure message actionable.
+ */
+async function loadModule(spurBin: string, mode: ModuleMode): Promise<VerificationModule> {
+    if (mode === 'source') throw sourceModeError(spurBin);
+    const bundle = bundleEntry();
+    if (!existsSync(bundle)) {
+        throw new Error(
+            `feature-verification-steps: mode=bundle — the generated inline bundle is missing at ${bundle}` +
+                `${spurBin === '' ? '' : ` (spurBin=${spurBin})`}. ` +
+                'Fix: in a source checkout run `bun run build:bundle`; for an installed plugin reinstall it.',
+        );
+    }
+    return requireModule(bundle, mode);
+}
+
+/** Dynamic-import the entry and refuse modules missing the verification seams. */
+async function requireModule(entry: string, mode: ModuleMode): Promise<VerificationModule> {
+    const mod = (await import(entry)) as Partial<VerificationModule> & Record<string, unknown>;
+    const missing = (
+        [
+            'startFeatureVerificationReceipt',
+            'completeFeatureVerificationReceipt',
+            'captureFeatureReceiptDigest',
+            'resolveWorkflowDefinition',
+            'splitLaunchCommand',
+            'openInlineRunProjectDb',
+            'ArtifactDao',
+        ] as const
+    ).filter((k) => typeof mod[k] !== 'function');
+    if (missing.length > 0) {
+        throw new Error(
+            `feature-verification-steps: mode=${mode} — application entry ${entry} is missing feature-verification seams (${missing.join(', ')}). ` +
+                'Fix: the generated inline bundle is stale or incomplete — run `bun run build:bundle` in a source checkout, or reinstall the sp plugin.',
+        );
+    }
+    return mod as VerificationModule;
+}
+
+/** Refuse ids that could escape the run directory through receipt filenames. */
+function assertSafeId(kind: string, id: string): void {
+    if (!SAFE_ID_RE.test(id) || id.includes('..')) {
+        throw new Error(`refusing unsafe ${kind}: ${id}`);
+    }
+}
+
+/** Locate `<id>_<slug>.md` under the features directory. */
+function findFeatureFile(featureDir: string, featureId: string): string | undefined {
+    if (!existsSync(featureDir)) return undefined;
+    const name = readdirSync(featureDir).find((n) => n.startsWith(`${featureId}_`) && n.endsWith('.md'));
+    return name === undefined ? undefined : join(featureDir, name);
+}
+
+// ponytail: the receipt service is filesystem-pure over the ts-runtime
+// FileSystem port; only ensureDir/writeFile/rename are exercised on the
+// start/complete paths. Swap to createNodeFileSystem if more surface is needed.
+const nodeFsShim = {
+    ensureDir: (dir: string) => {
+        mkdirSync(dir, { recursive: true });
+    },
+    writeFile: (path: string, body: string) => {
+        writeFileSync(path, body);
+    },
+    rename: (src: string, dest: string) => {
+        renameSync(src, dest);
+    },
+    readFile: (path: string) => {
+        return readFileSync(path, 'utf8');
+    },
+} as never;
+
+/** One full verification pass for one feature. Always exits 0. */
+async function verify(
+    featureId: string,
+    runId: string,
+    cmdOverride: string,
+    spurBin: string,
+    mode: ModuleMode,
+): Promise<void> {
+    assertSafeId('feature id', featureId);
+    assertSafeId('run id', runId);
+    const cwd = process.cwd();
+    const mod = await loadModule(spurBin, mode);
+    const runDir = join(cwd, '.spur', 'run');
+    mkdirSync(runDir, { recursive: true });
+
+    // 1. Selected verifier definition (project override wins); its configured
+    // command is the completion contract — an override records but can't complete.
+    const selected = await mod.resolveWorkflowDefinition(cwd, 'feature-verification');
+    const vars = selected.workflow.vars as { verificationCmd?: unknown } | undefined;
+    const configuredCmd =
+        typeof vars?.verificationCmd === 'string' && vars.verificationCmd.length > 0
+            ? vars.verificationCmd
+            : 'bun run spur-check-feature';
+    const effectiveCmd = cmdOverride !== '' ? cmdOverride : configuredCmd;
+
+    const featureFile = findFeatureFile(join(cwd, 'docs', 'features'), featureId);
+    if (featureFile === undefined) {
+        throw new Error(`feature ${featureId} not found under ${join(cwd, 'docs', 'features')}`);
+    }
+    const featureContent = readFileSync(featureFile, 'utf8');
+    const learningsPath = join(cwd, '.spur', 'context', 'learnings.md');
+    const learningsContent = existsSync(learningsPath) ? readFileSync(learningsPath, 'utf8') : undefined;
+
+    // 2. Before digest + RUNNING receipt (both copies) + artifact registration.
+    const beforeDigest = await mod.captureFeatureReceiptDigest(cwd, featureContent, learningsContent);
+    const receipt = await mod.startFeatureVerificationReceipt(nodeFsShim, runDir, {
+        featureId,
+        runId,
+        workdir: cwd,
+        verifier: {
+            name: 'feature-verification',
+            sourcePath: selected.path,
+            layer: selected.layer,
+            definitionDigest: selected.digest,
+        },
+        verificationCmd: effectiveCmd,
+        inputDigest: beforeDigest,
+    });
+    const db = await mod.openInlineRunProjectDb(cwd);
+    try {
+        await new mod.ArtifactDao(db.adapter as never).record({
+            runId,
+            path: join(runDir, `${runId}-feature-verification.json`),
+            kind: 'feature-verification',
+        });
+    } finally {
+        db.close();
+    }
+
+    // 3. Run the effective command via the safe splitter (no `sh -c`).
+    const logPath = join(runDir, `${runId}-feature-verification.log`);
+    const launch = mod.splitLaunchCommand(effectiveCmd, 'feature-verification verificationCmd');
+    if ('error' in launch) {
+        await mod.completeFeatureVerificationReceipt(nodeFsShim, runDir, receipt, {
+            status: 'FAIL',
+            inputDigest: beforeDigest,
+        });
+        console.log(`feature-verification-steps: ${featureId} verification FAIL (${launch.error})`);
+        return;
+    }
+    const logFd = openSync(logPath, 'a');
+    try {
+        const result = spawnSync(launch.command, launch.leadingArgs, {
+            cwd,
+            stdio: ['ignore', logFd, logFd],
+            timeout: 4 * 60 * 60 * 1000,
+        });
+        const exit = result.status ?? 1;
+
+        // 4/5. After digest — a mismatch records FAIL (the pass did not verify
+        // the tree it left behind); otherwise the exit code decides.
+        const afterDigest = await mod.captureFeatureReceiptDigest(cwd, featureContent, learningsContent);
+        const status: 'PASS' | 'FAIL' = exit === 0 && afterDigest === beforeDigest ? 'PASS' : 'FAIL';
+        await mod.completeFeatureVerificationReceipt(nodeFsShim, runDir, receipt, { status, inputDigest: afterDigest });
+        console.log(`feature-verification-steps: ${featureId} verification ${status} (run ${runId}, log ${logPath})`);
+    } finally {
+        closeSync(logFd);
+    }
+}
+
+function main(): void {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const flag = (name: string): string => {
+        const i = args.indexOf(name);
+        return i >= 0 && i + 1 < args.length ? (args[i + 1] ?? '') : '';
+    };
+    if (command !== 'verify') {
+        console.error('Usage: feature-verification-steps.ts verify --feature-id <id> --run-id <id> [--cmd <command>]');
+        process.exit(2);
+    }
+    verify(
+        flag('--feature-id') || getEnvVar('featureId') || '',
+        flag('--run-id') || getEnvVar('__runId') || '',
+        flag('--cmd') || getEnvVar('verificationCmd') || '',
+        flag('--spur-bin') || getEnvVar('spurBin') || '',
+        resolveModuleMode(flag('--module-mode')),
+    )
+        .then(() => process.exit(0))
+        .catch((err: unknown) => {
+            console.error(`feature-verification-steps: ${String(err)}`);
+            process.exit(1);
+        });
+}
+
+main();

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -9,6 +9,7 @@ import {
   closeSync,
   existsSync,
   fsyncSync,
+  mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
@@ -434,6 +435,75 @@ HA_BASELINE_UNTIL=${baseline.until}
 `;
   return env;
 }
+function isRealDate(ymd) {
+  const m = ymd.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m)
+    return false;
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const dt = new Date(Date.UTC(y, mo - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d;
+}
+function validateSelector(opts) {
+  const errors = [];
+  const has = (v) => v !== undefined && v !== "";
+  const val = (v) => has(v) ? v : null;
+  const mode = has(opts.mode) ? opts.mode : "daily";
+  if (mode !== "daily" && mode !== "ad-hoc") {
+    return { ok: false, errors: [`--mode must be "daily" or "ad-hoc", got "${opts.mode}"`] };
+  }
+  const recompute = opts.recompute ?? "";
+  if (recompute !== "" && recompute !== "true" && recompute !== "false") {
+    errors.push(`--recompute must be "true" or "false", got "${recompute}"`);
+  }
+  if (mode === "daily") {
+    for (const [flag, v] of [
+      ["--focus", opts.focus],
+      ["--since", opts.since],
+      ["--until", opts.until],
+      ["--output", opts.output]
+    ]) {
+      if (has(v))
+        errors.push(`daily mode rejects ${flag}`);
+    }
+    if (has(opts.date) && !isRealDate(opts.date)) {
+      errors.push(`--date must be a real YYYY-MM-DD calendar day, got "${opts.date}"`);
+    }
+  } else {
+    if (has(opts.date))
+      errors.push("ad-hoc mode rejects --date");
+    if (recompute === "true")
+      errors.push("ad-hoc mode rejects --recompute");
+    if (!has(opts.focus))
+      errors.push("ad-hoc mode requires a non-empty --focus");
+    const sinceOk = has(opts.since);
+    const untilOk = has(opts.until);
+    if (!sinceOk)
+      errors.push("ad-hoc mode requires --since (inclusive ISO instant)");
+    if (!untilOk)
+      errors.push("ad-hoc mode requires --until (inclusive ISO instant)");
+    if (sinceOk && untilOk) {
+      const since = new Date(opts.since ?? "");
+      const until = new Date(opts.until ?? "");
+      if (Number.isNaN(since.getTime()))
+        errors.push(`--since must be a parseable ISO instant, got "${opts.since}"`);
+      if (Number.isNaN(until.getTime()))
+        errors.push(`--until must be a parseable ISO instant, got "${opts.until}"`);
+      if (!Number.isNaN(since.getTime()) && !Number.isNaN(until.getTime()) && since.getTime() > until.getTime()) {
+        errors.push(`--since must not be after --until ("${opts.since}" > "${opts.until}")`);
+      }
+    }
+  }
+  if (errors.length)
+    return { ok: false, errors };
+  return {
+    ok: true,
+    mode,
+    date: val(opts.date),
+    focus: val(opts.focus),
+    since: val(opts.since),
+    until: val(opts.until)
+  };
+}
 function buildProvenance(opts) {
   let raw;
   try {
@@ -699,19 +769,48 @@ ${result.problems.map((p) => `- ${p}
         return {
           exitCode: 1,
           stdout: "",
-          stderr: `usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>]
+          stderr: `usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>] [--focus <text>] [--recompute true|false] [--run-id <id>]
 `
         };
       }
-      writeFileSync(f.out, resolvePaths({
+      const v = validateSelector({
+        mode: f.mode,
+        date: f.date,
+        since: f.since,
+        until: f.until,
+        focus: f.focus,
+        recompute: f.recompute,
+        output: f.output
+      });
+      if (!v.ok)
+        return { exitCode: 1, stdout: "", stderr: `${v.errors.join(`
+`)}
+` };
+      const env = resolvePaths({
         helper: f.helper,
         reportDir: f["report-dir"] ?? "docs/report",
         date: f.date,
         output: f.output,
-        mode: f.mode,
+        mode: v.mode,
         since: f.since,
         until: f.until
-      }));
+      });
+      writeFileSync(f.out, env);
+      if (f["run-id"] !== undefined && f["run-id"] !== "") {
+        mkdirSync(".spur/run", { recursive: true });
+        const envVars = Object.fromEntries(env.trim().split(`
+`).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
+        const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+        writeFileSync(`.spur/run/${f["run-id"]}-selector.json`, `${JSON.stringify({
+          mode: v.mode,
+          date: envVars.HA_DATE ?? null,
+          focus: v.focus,
+          since: envVars.HA_SINCE ?? null,
+          until: envVars.HA_UNTIL ?? null,
+          timezone: tz
+        }, null, 2)}
+`);
+      }
       return { exitCode: 0, stdout: "", stderr: "" };
     }
     case "probe": {
@@ -805,6 +904,7 @@ ${reasons}`, stderr: "" };
   process.exitCode = exitCode;
 }
 export {
+  validateSelector,
   stampReport,
   semanticArtifactDigest,
   runCacheCli,

package/plugins/sp/scripts/history-anatomy-cache.ts

@@ -34,6 +34,7 @@ import {
     closeSync,
     existsSync,
     fsyncSync,
+    mkdirSync,
     openSync,
     readdirSync,
     readFileSync,
@@ -594,6 +595,94 @@ export function resolvePaths(opts: {
     return env;
 }
 
+/**
+ * Per-mode argument grammar for the `paths` command (0920): the deterministic owner of the
+ * mode/window validation the resolve-scope model hop used to perform. An empty string means
+ * "not provided" — the workflow passes every declared var, empty by default.
+ */
+export type SelectorValidation =
+    | {
+          ok: true;
+          mode: 'daily' | 'ad-hoc';
+          date: string | null;
+          focus: string | null;
+          since: string | null;
+          until: string | null;
+      }
+    | { ok: false; errors: string[] };
+
+/** Real calendar day (rejects e.g. 2026-02-30); tz-independent UTC round-trip. */
+function isRealDate(ymd: string): boolean {
+    const m = ymd.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!m) return false;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const dt = new Date(Date.UTC(y, mo - 1, d));
+    return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d;
+}
+
+export function validateSelector(opts: {
+    mode?: string;
+    date?: string;
+    since?: string;
+    until?: string;
+    focus?: string;
+    recompute?: string;
+    output?: string;
+}): SelectorValidation {
+    const errors: string[] = [];
+    const has = (v?: string) => v !== undefined && v !== '';
+    const val = (v?: string) => (has(v) ? v : null);
+    const mode = has(opts.mode) ? opts.mode : 'daily';
+    if (mode !== 'daily' && mode !== 'ad-hoc') {
+        return { ok: false, errors: [`--mode must be "daily" or "ad-hoc", got "${opts.mode}"`] };
+    }
+    const recompute = opts.recompute ?? '';
+    if (recompute !== '' && recompute !== 'true' && recompute !== 'false') {
+        errors.push(`--recompute must be "true" or "false", got "${recompute}"`);
+    }
+    if (mode === 'daily') {
+        for (const [flag, v] of [
+            ['--focus', opts.focus],
+            ['--since', opts.since],
+            ['--until', opts.until],
+            ['--output', opts.output],
+        ] as const) {
+            if (has(v)) errors.push(`daily mode rejects ${flag}`);
+        }
+        if (has(opts.date) && !isRealDate(opts.date)) {
+            errors.push(`--date must be a real YYYY-MM-DD calendar day, got "${opts.date}"`);
+        }
+    } else {
+        if (has(opts.date)) errors.push('ad-hoc mode rejects --date');
+        if (recompute === 'true') errors.push('ad-hoc mode rejects --recompute');
+        if (!has(opts.focus)) errors.push('ad-hoc mode requires a non-empty --focus');
+        const sinceOk = has(opts.since);
+        const untilOk = has(opts.until);
+        if (!sinceOk) errors.push('ad-hoc mode requires --since (inclusive ISO instant)');
+        if (!untilOk) errors.push('ad-hoc mode requires --until (inclusive ISO instant)');
+        if (sinceOk && untilOk) {
+            const since = new Date(opts.since ?? '');
+            const until = new Date(opts.until ?? '');
+            if (Number.isNaN(since.getTime()))
+                errors.push(`--since must be a parseable ISO instant, got "${opts.since}"`);
+            if (Number.isNaN(until.getTime()))
+                errors.push(`--until must be a parseable ISO instant, got "${opts.until}"`);
+            if (!Number.isNaN(since.getTime()) && !Number.isNaN(until.getTime()) && since.getTime() > until.getTime()) {
+                errors.push(`--since must not be after --until ("${opts.since}" > "${opts.until}")`);
+            }
+        }
+    }
+    if (errors.length) return { ok: false, errors };
+    return {
+        ok: true,
+        mode,
+        date: val(opts.date),
+        focus: val(opts.focus),
+        since: val(opts.since),
+        until: val(opts.until),
+    };
+}
+
 export interface ProbeOptions {
     artifact: string;
     target: string;
@@ -928,21 +1017,56 @@ export function runCacheCli(argv: string[]): CacheCliResult {
                 return {
                     exitCode: 1,
                     stdout: '',
-                    stderr: 'usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>]\n',
+                    stderr: 'usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>] [--focus <text>] [--recompute true|false] [--run-id <id>]\n',
                 };
             }
-            writeFileSync(
-                f.out,
-                resolvePaths({
-                    helper: f.helper,
-                    reportDir: f['report-dir'] ?? 'docs/report',
-                    date: f.date,
-                    output: f.output,
-                    mode: f.mode,
-                    since: f.since,
-                    until: f.until,
-                }),
-            );
+            const v = validateSelector({
+                mode: f.mode,
+                date: f.date,
+                since: f.since,
+                until: f.until,
+                focus: f.focus,
+                recompute: f.recompute,
+                output: f.output,
+            });
+            if (!v.ok) return { exitCode: 1, stdout: '', stderr: `${v.errors.join('\n')}\n` };
+            const env = resolvePaths({
+                helper: f.helper,
+                reportDir: f['report-dir'] ?? 'docs/report',
+                date: f.date,
+                output: f.output,
+                mode: v.mode,
+                since: f.since,
+                until: f.until,
+            });
+            writeFileSync(f.out, env);
+            // 0920: run-scoped selector observation artifact — written only after successful
+            // validation; historical selector files have incompatible shapes and are not consumed.
+            if (f['run-id'] !== undefined && f['run-id'] !== '') {
+                mkdirSync('.spur/run', { recursive: true });
+                const envVars = Object.fromEntries(
+                    env
+                        .trim()
+                        .split('\n')
+                        .map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]),
+                );
+                const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+                writeFileSync(
+                    `.spur/run/${f['run-id']}-selector.json`,
+                    `${JSON.stringify(
+                        {
+                            mode: v.mode,
+                            date: envVars.HA_DATE ?? null,
+                            focus: v.focus,
+                            since: envVars.HA_SINCE ?? null,
+                            until: envVars.HA_UNTIL ?? null,
+                            timezone: tz,
+                        },
+                        null,
+                        2,
+                    )}\n`,
+                );
+            }
             return { exitCode: 0, stdout: '', stderr: '' };
         }
         case 'probe': {

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -44,11 +44,12 @@ const DOCUMENTED = {
         'doctor.probe',
         'file.read.into-var',
         'hitl.confirm',
-        'hitl.select',
+        'hitl.input',
         'agent.run',
         'proof.fingerprint',
         'run.artifact',
         'command.gate',
+        'decide',
     ]),
     guards: new Set(['always', 'shell', 'action-ok', 'contract-violation']),
 } as const;