@sensigo/realm-cli 0.19.0 → 0.21.0

package/dist/commands/export.d.ts

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import type { RunRecord, RunStore, FailedAttemptRecord, TraceBufferStore } from '@sensigo/realm';
+export interface ExportBundle {
+    realm_export_version: 1;
+    /** ISO-8601, stamped by the CLI at assembly time. */
+    exported_at: string;
+    /** The full RunRecord — steps, evidence, skip_details, claims, etc. */
+    run: RunRecord;
+    /** Parsed failed-attempt records; `[]` if none were ever recorded for this run. */
+    attempts: FailedAttemptRecord[];
+    /** True if the run hit the failed-attempt sidecar's 256KB ceiling — later attempts were dropped
+     *  at write time (append-and-stop), so `attempts` is NOT exhaustive. */
+    attempts_capped: boolean;
+    /** `{ <stepId>: [...] }` — every buffered/WAL entry for the run, across all steps; `{}` if none. */
+    wal: Record<string, unknown[]>;
+}
+export interface ExportRunResult {
+    bundle: ExportBundle;
+    /**
+     * Set (to the warning text) when the run was non-terminal at export time — a best-effort
+     * snapshot, since its artifacts were read at slightly different instants and it may still be
+     * mid-flight. `undefined` for a terminal run (nothing to warn about — nothing changes post-seal).
+     * Returned as data, not printed here, so this stays assertable without a console spy (mirrors the
+     * `cleanup`/`purge` precedent of testing exported logic, not console output).
+     */
+    warning: string | undefined;
+}
+export interface ExportStores {
+    runStore: Pick<RunStore, 'get'>;
+    failedAttemptStore: {
+        read(runId: string): Promise<{
+            records: FailedAttemptRecord[];
+            capped: boolean;
+        }>;
+    };
+    traceBufferStore: Pick<TraceBufferStore, 'readAllForRun'>;
+}
+/**
+ * Assembles the export bundle for `runId` from each store's existing read methods — never writes,
+ * never locks, never touches `runsDir`. Throws `STATE_RUN_NOT_FOUND` (propagated from
+ * `runStore.get`) for a nonexistent run; the CLI action maps that to an error message + exit(1).
+ */
+export declare function buildExportBundle(runId: string, stores: ExportStores, now?: Date): Promise<ExportRunResult>;
+export interface ResolveExportPathOptions {
+    runId: string;
+    /** The raw `--out` flag value, if given. */
+    out?: string | undefined;
+    /** `runStore.runsDirPath` — the export target must never resolve inside it. */
+    runsDir: string;
+}
+/**
+ * Resolves the final, absolute output path for an export, or throws (never writes anything
+ * itself — purely a path decision). Resolution order:
+ *  1. No `--out` → `<cwd>/<runId>.realm.json`.
+ *  2. `--out` names an EXISTING DIRECTORY → `<out>/<runId>.realm.json`.
+ *  3. Otherwise `--out` is treated as the literal file path.
+ * Then refuses (throws `WorkflowError`, code `VALIDATION_INPUT_SCHEMA`) if the resolved path is:
+ *  - inside `runsDir` — export must never write into the store's own directory (would confuse
+ *    `list()`'s naive `.json`-suffix filter, and clutters the space `gc`/`purge` manage); or
+ *  - an already-existing file — export never clobbers; the operator picks a different `--out`.
+ */
+export declare function resolveExportPath(opts: ResolveExportPathOptions): string;
+export declare const exportCommand: Command;
+//# sourceMappingURL=export.d.ts.map

package/dist/commands/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGjG,MAAM,WAAW,YAAY;IAC3B,oBAAoB,EAAE,CAAC,CAAC;IACxB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,EAAE,SAAS,CAAC;IACf,mFAAmF;IACnF,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC;4EACwE;IACxE,eAAe,EAAE,OAAO,CAAC;IACzB,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAChC,kBAAkB,EAAE;QAClB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;YAAC,MAAM,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KACnF,CAAC;IACF,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,eAAe,CAAC,CAoB1B;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAqCxE;AAQD,eAAO,MAAM,aAAa,SA2CtB,CAAC"}

package/dist/commands/export.js

@@ -0,0 +1,131 @@
+// export command — archive a run's evidence into one inspectable JSON bundle (issue #159).
+//
+// The read-only, evidence-preserving companion to `realm run purge` (#107): before (or instead of)
+// permanently deleting a run's artifacts, `realm run export <id>` writes them into a single,
+// self-contained, human-readable JSON file an operator can `cat`/`grep`/`git add`/attach to a bug
+// report. Read-only and lock-free by construction — it only ever calls each store's existing PUBLIC
+// READ methods (`runStore.get`, `failedAttemptStore.read`, `traceBufferStore.readAllForRun`); no
+// filename layout is hard-coded here, and nothing is written to `runsDir`, unlinked, or locked.
+//
+// Works on ANY run, not just terminal ones — export's highest-value use is handing off a *stuck*
+// (non-terminal) run for debugging, which a terminal-only gate would forbid, and read-only means
+// there is no safety reason to restrict it. A non-terminal run gets a best-effort-snapshot warning
+// instead (its artifacts are read at slightly different instants and may be mid-flight); a terminal
+// run needs no warning, since nothing changes post-seal.
+//
+// The bundle deliberately excludes the idempotency-key pointer (`keys/<hash>.json`): that file is a
+// rebuildable hash→run INDEX (regenerated by `reconcile`), not run evidence, and the key it maps is
+// already present on the run record itself (`run.idempotency_key`).
+import { existsSync, statSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { Command } from 'commander';
+import { WorkflowError, isTerminalPhase } from '@sensigo/realm';
+/**
+ * Assembles the export bundle for `runId` from each store's existing read methods — never writes,
+ * never locks, never touches `runsDir`. Throws `STATE_RUN_NOT_FOUND` (propagated from
+ * `runStore.get`) for a nonexistent run; the CLI action maps that to an error message + exit(1).
+ */
+export async function buildExportBundle(runId, stores, now = new Date()) {
+    const run = await stores.runStore.get(runId);
+    const { records: attempts, capped: attemptsCapped } = await stores.failedAttemptStore.read(runId);
+    const wal = await stores.traceBufferStore.readAllForRun(runId);
+    const bundle = {
+        realm_export_version: 1,
+        exported_at: now.toISOString(),
+        run,
+        attempts,
+        attempts_capped: attemptsCapped,
+        wal,
+    };
+    const warning = !isTerminalPhase(run.run_phase)
+        ? `best-effort snapshot: run '${runId}' is still ${run.run_phase}; its artifacts are read at ` +
+            `slightly different instants and may be mid-flight`
+        : undefined;
+    return { bundle, warning };
+}
+/**
+ * Resolves the final, absolute output path for an export, or throws (never writes anything
+ * itself — purely a path decision). Resolution order:
+ *  1. No `--out` → `<cwd>/<runId>.realm.json`.
+ *  2. `--out` names an EXISTING DIRECTORY → `<out>/<runId>.realm.json`.
+ *  3. Otherwise `--out` is treated as the literal file path.
+ * Then refuses (throws `WorkflowError`, code `VALIDATION_INPUT_SCHEMA`) if the resolved path is:
+ *  - inside `runsDir` — export must never write into the store's own directory (would confuse
+ *    `list()`'s naive `.json`-suffix filter, and clutters the space `gc`/`purge` manage); or
+ *  - an already-existing file — export never clobbers; the operator picks a different `--out`.
+ */
+export function resolveExportPath(opts) {
+    let target;
+    if (opts.out === undefined) {
+        target = join(process.cwd(), `${opts.runId}.realm.json`);
+    }
+    else if (existsSync(opts.out) && statSync(opts.out).isDirectory()) {
+        target = join(opts.out, `${opts.runId}.realm.json`);
+    }
+    else {
+        target = opts.out;
+    }
+    const resolvedTarget = resolve(target);
+    const resolvedRunsDir = resolve(opts.runsDir);
+    if (resolvedTarget === resolvedRunsDir || resolvedTarget.startsWith(resolvedRunsDir + sep)) {
+        throw new WorkflowError(`Refusing to write the export inside runsDir ('${resolvedRunsDir}') — choose a different --out.`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+        });
+    }
+    if (existsSync(resolvedTarget)) {
+        throw new WorkflowError(`Refusing to overwrite existing file '${resolvedTarget}'. Choose a different --out.`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+        });
+    }
+    return resolvedTarget;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+export const exportCommand = new Command('export')
+    .description("Archive a run's evidence (record + failed-attempt sidecar + WAL traces) into one inspectable JSON bundle — read-only")
+    .argument('<run-id>', 'ID of the run to export')
+    .option('--out <path>', 'Output file or directory (default: ./<run-id>.realm.json)')
+    .action(async (runId, opts) => {
+    const { JsonFileStore, FailedAttemptStore } = await import('@sensigo/realm');
+    const { JsonTraceBufferStore } = await import('@sensigo/realm-mcp');
+    const runStore = new JsonFileStore();
+    const runsDir = runStore.runsDirPath;
+    const failedAttemptStore = new FailedAttemptStore(runsDir);
+    const traceBufferStore = new JsonTraceBufferStore(runsDir);
+    try {
+        const { bundle, warning } = await buildExportBundle(runId, {
+            runStore,
+            failedAttemptStore,
+            traceBufferStore,
+        });
+        if (warning !== undefined) {
+            console.warn(`⚠ ${warning}`);
+        }
+        if (bundle.attempts_capped) {
+            console.warn('⚠ failed-attempt log was truncated at its size ceiling — the exported attempts list is not exhaustive.');
+        }
+        const target = resolveExportPath({ runId, out: opts.out, runsDir });
+        const json = JSON.stringify(bundle, null, 2);
+        await writeFile(target, json, 'utf8');
+        const walStepCount = Object.keys(bundle.wal).length;
+        console.log(`Exported run '${runId}' to '${target}' (${formatBytes(Buffer.byteLength(json))}).\n` +
+            `  phase: ${bundle.run.run_phase}, attempts: ${bundle.attempts.length}, WAL steps: ${walStepCount}`);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=export.js.map

package/dist/commands/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,EAAE;AACF,mGAAmG;AACnG,6FAA6F;AAC7F,kGAAkG;AAClG,oGAAoG;AACpG,iGAAiG;AACjG,gGAAgG;AAChG,EAAE;AACF,iGAAiG;AACjG,iGAAiG;AACjG,mGAAmG;AACnG,oGAAoG;AACpG,yDAAyD;AACzD,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,oEAAoE;AACpE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqChE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,MAAoB,EACpB,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClG,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAE/D,MAAM,MAAM,GAAiB;QAC3B,oBAAoB,EAAE,CAAC;QACvB,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE;QAC9B,GAAG;QACH,QAAQ;QACR,eAAe,EAAE,cAAc;QAC/B,GAAG;KACJ,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC;QAC7C,CAAC,CAAC,8BAA8B,KAAK,cAAc,GAAG,CAAC,SAAS,8BAA8B;YAC5F,mDAAmD;QACrD,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAUD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA8B;IAC9D,IAAI,MAAc,CAAC;IACnB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,aAAa,CAAC,CAAC;IAC3D,CAAC;SAAM,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACpE,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,aAAa,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IAED,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,cAAc,KAAK,eAAe,IAAI,cAAc,CAAC,UAAU,CAAC,eAAe,GAAG,GAAG,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,aAAa,CACrB,iDAAiD,eAAe,gCAAgC,EAChG;YACE,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,YAAY;YACtB,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,KAAK;SACjB,CACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,aAAa,CACrB,wCAAwC,cAAc,8BAA8B,EACpF;YACE,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,YAAY;YACtB,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,KAAK;SACjB,CACF,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1D,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC;KAC/C,WAAW,CACV,sHAAsH,CACvH;KACA,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;KAC/C,MAAM,CAAC,cAAc,EAAE,2DAA2D,CAAC;KACnF,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,IAAsB,EAAE,EAAE;IACtD,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC7E,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC;IACrC,MAAM,kBAAkB,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,gBAAgB,GAAG,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAE3D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE;YACzD,QAAQ;YACR,kBAAkB;YAClB,gBAAgB;SACjB,CAAC,CAAC;QAEH,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CACV,wGAAwG,CACzG,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7C,MAAM,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEtC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACpD,OAAO,CAAC,GAAG,CACT,iBAAiB,KAAK,SAAS,MAAM,MAAM,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM;YACnF,YAAY,MAAM,CAAC,GAAG,CAAC,SAAS,eAAe,MAAM,CAAC,QAAQ,CAAC,MAAM,gBAAgB,YAAY,EAAE,CACtG,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/commands/gc.d.ts

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+export interface SweepOrphansOptions {
+    /** Minimum age (ms) a `.tmp` must have to be reaped. Rejected below `FLOOR_MS` — see above. */
+    olderThanMs: number;
+    /** true (default caller behavior): report only, never unlink. */
+    dryRun: boolean;
+    /** Injected clock for deterministic age math in tests; defaults to `new Date()`. */
+    now?: Date;
+}
+export interface SweepOrphansResult {
+    /** Reaped (force mode) or would-be-reaped (dry-run) `.tmp` paths. */
+    reaped: string[];
+    /** A candidate vanished on its own (lstat or unlink hit ENOENT) — benign, never a failure. */
+    already_gone: string[];
+    /** A candidate lstat'd to something other than ENOENT/regular-file/symlink (e.g. a directory
+     *  unexpectedly named `*.tmp`), or a genuine unlink error (permissions, I/O). Loud on purpose —
+     *  a type mismatch is never silently swallowed, in either dry-run or force mode. */
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Reaps orphaned atomic-write `.tmp` files older than `options.olderThanMs`. `FLOOR_MS` is
+ * checked FIRST, before any filesystem access, so no caller — CLI action, test, or future
+ * consumer — can reach a delete without crossing it.
+ *
+ * Per-candidate rule (uses `lstat`, never `readdir({ withFileTypes: true })` — on WSL/9p
+ * `Dirent.d_type` can be `DT_UNKNOWN`, which would make every type check false and the sweep
+ * reap nothing):
+ *  - `lstat` ENOENT (vanished before we could even examine it, or during the later `unlink`) →
+ *    `already_gone`, in either mode — a benign race, never a failure.
+ *  - a **symlink** → skipped silently (appears in no bucket). Never `unlink`ed, never followed.
+ *  - anything else that is **not a regular file** (a directory unexpectedly named `*.tmp`, a
+ *    socket, …) → `failed`, loud, in either mode — a type mismatch is never an ENOENT-style
+ *    silent swallow, because it signals something anomalous in `runsDir` worth surfacing even
+ *    from a dry-run.
+ *  - a **future mtime** (negative age — clock skew) → skipped silently, never reaped.
+ *  - a regular file younger than `olderThanMs` → skipped silently (almost certainly an in-flight
+ *    write's temp).
+ *  - a regular file older than `olderThanMs` → a reap candidate: in dry-run, its path lands in
+ *    `reaped` (interpreted as "would reap") without any filesystem mutation; in force mode, it is
+ *    `unlink`ed — success → `reaped`; ENOENT → `already_gone`; anything else → `failed`.
+ */
+export declare function sweepOrphans(runsDir: string, options: SweepOrphansOptions): Promise<SweepOrphansResult>;
+export declare const gcCommand: Command;
+//# sourceMappingURL=gc.d.ts.map

package/dist/commands/gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,MAAM,WAAW,mBAAmB;IAClC,+FAA+F;IAC/F,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,oFAAoF;IACpF,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8FAA8F;IAC9F,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;wFAEoF;IACpF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AA+DD,eAAO,MAAM,SAAS,SAwDlB,CAAC"}

package/dist/commands/gc.js

@@ -0,0 +1,240 @@
+// gc command — sweep orphaned atomic-write temps (issue #160, Phase 1: .tmp only).
+//
+// atomicWriteFile (packages/core/src/store/atomic-write.ts) writes a unique sibling temp
+// (`${path}.<pid>.<counter>.tmp`) then POSIX-renames it over the target. A process dying between
+// the write and the rename orphans that temp forever — it is not runId-keyed for the key-pointer
+// case (`keys/<hash>.json.<pid>.*.tmp`), so `realm run purge` (#107), which acts by runId, can
+// never reach it. Temps are invisible to `list()` (no `.json` suffix) but accumulate on disk
+// regardless. Windows never produces a temp at all (`atomicWriteFile` falls back to plain
+// `writeFile` on win32) — this sweep is a documented no-op there, not a design driver.
+//
+// Reaping a `.tmp` is unconditionally safe: if the sweep unlinks a temp mid-rename, the pending
+// `rename` gets ENOENT, `atomicWriteFile`'s own catch best-effort-unlinks its temp + rethrows — the
+// TARGET file is never touched (worst case: a spurious write error surfaces to the writer, never a
+// torn file). Combined with the 1h floor below, an in-flight write's temp (age ≪ floor) is never
+// even selected.
+//
+// Phase 1 = `.tmp` only. `.lock` reaping is deliberately split to #164 (deferred — proper-lockfile
+// self-heals a live-path lock; only a purged-target's lock lingers, which is negligible). Run-less
+// `trace-buffer-*.jsonl` WAL cleanup is #163. Neither is this command's job — see the report footer.
+import { readdir, lstat, unlink, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { WorkflowError } from '@sensigo/realm';
+import { parseDuration } from '../lib/parse-duration.js';
+/**
+ * Minimum `--older-than` the sweep will ever honor (1 hour) — a conservative floor for hygiene of
+ * non-urgent crash residue, and, forward-consistency-wise, the safety guard the deferred `.lock`
+ * reaping (#164) will also require; enforcing it here means #164 inherits an already-tested guard.
+ * Temps themselves are safe to reap at any age past a few seconds (see the module doc above) — this
+ * floor is conservatism, not the temp-safety mechanism. Module-private: the only way to reach a
+ * delete is through `sweepOrphans`, which checks this FIRST, before any filesystem access.
+ */
+const FLOOR_MS = 3_600_000;
+/**
+ * Every top-level `*.tmp` in `runsDir`, plus one level of recursion into `runsDir/keys/*.tmp` —
+ * `keys/` is the ONLY subdirectory any store ever creates in `runsDir` (verified: `JsonFileStore`'s
+ * `keysDir()`/`mkdir` calls are the only subdirectory creation anywhere in this codebase's
+ * `runsDir` usage). A plain `readdir(runsDir)` sees the `keys` entry itself (no `.json`/`.tmp`
+ * suffix, so it's filtered out) but NOT what's inside it — hence the explicit second `readdir`.
+ * Nothing else is recursed into; nothing else is globbed (no `*.lock` — that's #164).
+ * Tolerates a missing `runsDir` or a missing `keys/` (a fresh install, or one that never wrote a
+ * keyed run, legitimately lacks either) — a missing directory yields zero candidates, not a throw.
+ */
+async function findTempCandidates(runsDir) {
+    const topLevel = await readdir(runsDir).catch(() => []);
+    const paths = topLevel.filter((f) => f.endsWith('.tmp')).map((f) => join(runsDir, f));
+    const keysDir = join(runsDir, 'keys');
+    const keysEntries = await readdir(keysDir).catch(() => []);
+    paths.push(...keysEntries.filter((f) => f.endsWith('.tmp')).map((f) => join(keysDir, f)));
+    return paths;
+}
+/**
+ * Reaps orphaned atomic-write `.tmp` files older than `options.olderThanMs`. `FLOOR_MS` is
+ * checked FIRST, before any filesystem access, so no caller — CLI action, test, or future
+ * consumer — can reach a delete without crossing it.
+ *
+ * Per-candidate rule (uses `lstat`, never `readdir({ withFileTypes: true })` — on WSL/9p
+ * `Dirent.d_type` can be `DT_UNKNOWN`, which would make every type check false and the sweep
+ * reap nothing):
+ *  - `lstat` ENOENT (vanished before we could even examine it, or during the later `unlink`) →
+ *    `already_gone`, in either mode — a benign race, never a failure.
+ *  - a **symlink** → skipped silently (appears in no bucket). Never `unlink`ed, never followed.
+ *  - anything else that is **not a regular file** (a directory unexpectedly named `*.tmp`, a
+ *    socket, …) → `failed`, loud, in either mode — a type mismatch is never an ENOENT-style
+ *    silent swallow, because it signals something anomalous in `runsDir` worth surfacing even
+ *    from a dry-run.
+ *  - a **future mtime** (negative age — clock skew) → skipped silently, never reaped.
+ *  - a regular file younger than `olderThanMs` → skipped silently (almost certainly an in-flight
+ *    write's temp).
+ *  - a regular file older than `olderThanMs` → a reap candidate: in dry-run, its path lands in
+ *    `reaped` (interpreted as "would reap") without any filesystem mutation; in force mode, it is
+ *    `unlink`ed — success → `reaped`; ENOENT → `already_gone`; anything else → `failed`.
+ */
+export async function sweepOrphans(runsDir, options) {
+    if (options.olderThanMs < FLOOR_MS) {
+        throw new WorkflowError(`--older-than must resolve to at least 1h (got ${options.olderThanMs}ms) — gc refuses to ` +
+            `reap crash residue younger than that, even with --force.`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { olderThanMs: options.olderThanMs, floorMs: FLOOR_MS },
+        });
+    }
+    const now = options.now ?? new Date();
+    const candidatePaths = await findTempCandidates(runsDir);
+    const result = { reaped: [], already_gone: [], failed: [] };
+    const toReap = [];
+    for (const path of candidatePaths) {
+        let info;
+        try {
+            info = await lstat(path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                result.already_gone.push(path); // vanished between readdir and lstat
+            }
+            else {
+                result.failed.push({ path, error: err instanceof Error ? err.message : String(err) });
+            }
+            continue;
+        }
+        if (info.isSymbolicLink())
+            continue; // never unlink or follow a symlink — silent skip
+        if (!info.isFile()) {
+            result.failed.push({
+                path,
+                error: 'expected a regular file but found a different type (unexpected for a *.tmp name)',
+            });
+            continue;
+        }
+        const ageMs = now.getTime() - info.mtime.getTime();
+        if (ageMs < 0)
+            continue; // future mtime (clock skew) — skip, never reap
+        if (ageMs <= options.olderThanMs)
+            continue; // too fresh — most likely an in-flight write's temp
+        toReap.push(path);
+    }
+    if (options.dryRun) {
+        result.reaped = toReap;
+        return result;
+    }
+    for (const path of toReap) {
+        try {
+            await unlink(path);
+            result.reaped.push(path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                result.already_gone.push(path); // vanished between lstat and unlink
+            }
+            else {
+                result.failed.push({ path, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+    }
+    return result;
+}
+/** Best-effort total bytes for a known list of paths — reporting-only, never gates reaping.
+ *  Called against a fresh dry-run preview, so the paths are still on disk when stat'd. */
+async function statPathBytes(paths) {
+    let total = 0;
+    await Promise.all(paths.map(async (p) => {
+        try {
+            const info = await stat(p);
+            total += info.size;
+        }
+        catch {
+            // vanished between the preview pass and this stat — best-effort, ignore.
+        }
+    }));
+    return total;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** So an operator doesn't distrust the tool when `runsDir` still holds residue gc deliberately
+ *  does not touch — printed on every report, dry-run or force, empty or not. */
+const NOT_REAPED_FOOTER = 'gc does NOT reap orphaned .lock dirs (deferred — issue #164) or run-less trace-buffer-*.jsonl ' +
+    'WAL files (issue #163). Their presence in runsDir is expected and not a sign gc is broken.';
+/** Prints the dry-run / force report shared by both code paths. `previewBytes` always comes from
+ *  the initial (always non-destructive) preview pass — see the action below for why. */
+function printGcReport(result, previewBytes, dryRun) {
+    const nothingToReport = result.reaped.length === 0 && result.already_gone.length === 0 && result.failed.length === 0;
+    if (nothingToReport) {
+        console.log('No orphaned .tmp files found to reap.');
+    }
+    else if (dryRun) {
+        console.log(`${result.reaped.length} orphaned .tmp file(s) WOULD be reaped (${formatBytes(previewBytes)} to free):`);
+        for (const p of result.reaped)
+            console.log(`  • ${p}`);
+        if (result.already_gone.length > 0) {
+            console.log(`(${result.already_gone.length} candidate(s) already vanished on their own.)`);
+        }
+    }
+    else {
+        console.log(`Reaped ${result.reaped.length} orphaned .tmp file(s) (${formatBytes(previewBytes)} freed). ` +
+            `${result.already_gone.length} already gone, ${result.failed.length} failed.`);
+    }
+    for (const f of result.failed) {
+        console.error(`  ✗ ${f.path}: ${f.error}`);
+    }
+    if (dryRun && !nothingToReport) {
+        console.log('\nRe-run with --force to actually delete.');
+    }
+    console.log(`\n${NOT_REAPED_FOOTER}`);
+}
+export const gcCommand = new Command('gc')
+    .description('Sweep orphaned atomic-write .tmp files — crash residue from a process that died mid-write (dry-run by default)')
+    .requiredOption('--older-than <duration>', 'Reap temps idle at least this long (minimum 1h; e.g. 1h, 6h, 30d)')
+    .option('--force', 'Actually delete (without this, gc only reports what WOULD be reaped)')
+    .action(async (opts) => {
+    let olderThanMs;
+    try {
+        olderThanMs = parseDuration(opts.olderThan);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+        return;
+    }
+    // Defense-in-depth over sweepOrphans's own floor check — reject before touching the
+    // filesystem at all, with a CLI-friendly message naming the flag the operator just typed.
+    if (olderThanMs < FLOOR_MS) {
+        console.error(`--older-than must be at least 1h (got '${opts.olderThan}'). gc refuses to reap crash ` +
+            `residue younger than that, even with --force.`);
+        process.exit(1);
+        return;
+    }
+    const { JsonFileStore } = await import('@sensigo/realm');
+    const runsDir = new JsonFileStore().runsDirPath;
+    const now = new Date();
+    try {
+        // Always preview first — this NEVER mutates, in either mode — because it is the only
+        // reliable moment to `stat()` the candidates for the report's byte total: a force-mode
+        // reap deletes the files before sweepOrphans returns, so statting them afterward is
+        // impossible. The preview and the (optional) real pass share the same olderThanMs/now, so
+        // the candidate set is consistent bar a narrow, benign concurrent-activity window — which
+        // already_gone exists to absorb.
+        const preview = await sweepOrphans(runsDir, { olderThanMs, dryRun: true, now });
+        const bytes = await statPathBytes(preview.reaped);
+        if (opts.force !== true) {
+            printGcReport(preview, bytes, true);
+            return;
+        }
+        const result = await sweepOrphans(runsDir, { olderThanMs, dryRun: false, now });
+        printGcReport(result, bytes, false);
+        if (result.failed.length > 0)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=gc.js.map

package/dist/commands/gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.js","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"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"}

package/dist/commands-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AA4BA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAavB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}
+{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AA8BA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAevB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAM5B,CAAC"}

package/dist/commands-registry.js

@@ -9,6 +9,8 @@ import { abandonCommand } from './commands/abandon.js';
 import { reclaimCommand } from './commands/reclaim.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { purgeCommand } from './commands/purge.js';
+import { gcCommand } from './commands/gc.js';
+import { exportCommand } from './commands/export.js';
 import { reconcileCommand } from './commands/reconcile.js';
 import { attemptsCommand } from './commands/attempts.js';
 import { respondCommand } from './commands/respond.js';
@@ -47,6 +49,8 @@ export const runCommands = [
     respondCommand,
     cleanupCommand,
     purgeCommand,
+    gcCommand,
+    exportCommand,
     reconcileCommand,
     attemptsCommand,
 ];

package/dist/commands-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands-registry.js","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,eAAe;IACf,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;IACX,cAAc;CACf,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,gBAAgB;IAChB,eAAe;CAChB,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,aAAa;CACd,CAAC"}
+{"version":3,"file":"commands-registry.js","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,eAAe;IACf,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;IACX,cAAc;CACf,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,SAAS;IACT,aAAa;IACb,gBAAgB;IAChB,eAAe;CAChB,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,aAAa;CACd,CAAC"}

package/dist/index.js

@@ -4,7 +4,7 @@ import 'dotenv/config';
 import { Command } from 'commander';
 import { workflowCommands, runCommands, topLevelCommands } from './commands-registry.js';
 const program = new Command();
-program.name('realm').description('Realm workflow engine CLI').version('0.19.0');
+program.name('realm').description('Realm workflow engine CLI').version('0.21.0');
 // realm workflow — operations on workflow definitions
 const workflowCmd = new Command('workflow').description('Manage workflow definitions');
 for (const cmd of workflowCommands)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensigo/realm-cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,9 +61,9 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@sensigo/realm": "^0.19.0",
-    "@sensigo/realm-mcp": "^0.19.0",
-    "@sensigo/realm-testing": "^0.19.0",
+    "@sensigo/realm": "^0.21.0",
+    "@sensigo/realm-mcp": "^0.21.0",
+    "@sensigo/realm-testing": "^0.21.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "chalk": "^5.0.0",
     "commander": "^14.0.3",