@sensigo/realm-cli 0.22.0 → 0.24.0

package/dist/commands/export.d.ts

@@ -1,18 +1,49 @@
 import { Command } from 'commander';
 import type { RunRecord, RunStore, FailedAttemptRecord, TraceBufferStore } from '@sensigo/realm';
+/** One artifact `buildExportBundle` could not read (issue #186) — never silently omitted. */
+export interface ExportArtifactError {
+    /** A human label for the artifact — the STORE owns the actual on-disk path/filename; the
+     *  command never reconstructs one, matching this file's own no-filename-layout discipline. */
+    artifact: string;
+    /** The errno/FsIoError code, or `'UNKNOWN'` if the thrown value carried none. */
+    code: string;
+    message: string;
+}
 export interface ExportBundle {
-    realm_export_version: 1;
+    /**
+     * Bumped 1 → 2 (issue #186): a v1 bundle predates the `complete`/`artifact_errors` fields, so a
+     * v1 bundle's completeness is UNKNOWN to a reader — it was written back when export was
+     * all-or-nothing (any read failure meant no bundle at all), so v1's mere existence was itself a
+     * (weaker) completeness signal, but nothing in a v1 bundle states it explicitly. v2 always
+     * states it explicitly via `complete`.
+     */
+    realm_export_version: 2;
     /** 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. */
+    /** Parsed failed-attempt records; `[]` if none were ever recorded for this run OR if the sidecar
+     *  read failed (see `artifact_errors` — the empty array does not by itself mean "none recorded"
+     *  in that case; check `complete` first). */
     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. */
+     *  at write time (append-and-stop), so `attempts` is NOT exhaustive. Independent of `complete`:
+     *  a sidecar can be BOTH fully readable AND capped (a known, positively-characterized
+     *  truncation) — that is a different signal from a read that failed outright. */
     attempts_capped: boolean;
-    /** `{ <stepId>: [...] }` — every buffered/WAL entry for the run, across all steps; `{}` if none. */
+    /** `{ <stepId>: [...] }` — every buffered/WAL entry for the run, across all steps; `{}` if none
+     *  OR if the WAL read failed (see `artifact_errors` — check `complete` first). */
     wal: Record<string, unknown[]>;
+    /**
+     * False iff any artifact below (`attempts`/`wal`) could not be read (issue #186) — a real I/O
+     * failure, not a genuine ENOENT absence (an absent artifact is legitimately `[]`/`{}` and
+     * `complete: true`). The bundle NEVER lies by omission: every readable artifact is still
+     * written, and the run record itself is always present when `complete` is `false` (a run-record
+     * read failure means no bundle is written at all — see `buildExportBundle`).
+     */
+    complete: boolean;
+    /** The artifacts that failed to read; always `[]` when `complete` is `true`. */
+    artifact_errors: ExportArtifactError[];
 }
 export interface ExportRunResult {
     bundle: ExportBundle;
@@ -39,6 +70,15 @@ export interface ExportStores {
  * 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).
+ *
+ * issue #186 — graceful degradation, never all-or-nothing: `run` is the bundle's core, so a
+ * failure reading IT propagates (there is genuinely nothing to hand off — no bundle at all). But
+ * `attempts` and `wal` are each read in their OWN try/catch: a real I/O failure on either (post
+ * #183, `failedAttemptStore.read`/`traceBufferStore.readAllForRun` throw on a genuine I/O error,
+ * not just a benign ENOENT-absence, which still legitimately yields `[]`/`{}`) substitutes the
+ * empty value, records the failure in `artifact_errors`, and the OTHER artifact is still
+ * attempted — the bundle self-describes its own incompleteness via `complete` instead of
+ * disappearing entirely.
  */
 export declare function buildExportBundle(runId: string, stores: ExportStores, now?: Date): Promise<ExportRunResult>;
 export interface ResolveExportPathOptions {

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

@@ -1 +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"}
+{"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,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC;kGAC8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,oBAAoB,EAAE,CAAC,CAAC;IACxB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,EAAE,SAAS,CAAC;IACf;;iDAE6C;IAC7C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;qFAGiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB;sFACkF;IAClF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,eAAe,EAAE,mBAAmB,EAAE,CAAC;CACxC;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;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,eAAe,CAAC,CA+C1B;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,SA4DtB,CAAC"}

package/dist/commands/export.js

@@ -20,23 +20,65 @@ 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';
+import { WorkflowError, isTerminalPhase, FsIoError } from '@sensigo/realm';
+/** Extracts an errno/FsIoError code from a thrown value; `'UNKNOWN'` if it carries none. */
+function errnoCodeOf(err) {
+    if (err instanceof FsIoError)
+        return err.code;
+    const code = err?.code;
+    return typeof code === 'string' ? code : 'UNKNOWN';
+}
 /**
  * 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).
+ *
+ * issue #186 — graceful degradation, never all-or-nothing: `run` is the bundle's core, so a
+ * failure reading IT propagates (there is genuinely nothing to hand off — no bundle at all). But
+ * `attempts` and `wal` are each read in their OWN try/catch: a real I/O failure on either (post
+ * #183, `failedAttemptStore.read`/`traceBufferStore.readAllForRun` throw on a genuine I/O error,
+ * not just a benign ENOENT-absence, which still legitimately yields `[]`/`{}`) substitutes the
+ * empty value, records the failure in `artifact_errors`, and the OTHER artifact is still
+ * attempted — the bundle self-describes its own incompleteness via `complete` instead of
+ * disappearing entirely.
  */
 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 artifactErrors = [];
+    let attempts = [];
+    let attemptsCapped = false;
+    try {
+        const result = await stores.failedAttemptStore.read(runId);
+        attempts = result.records;
+        attemptsCapped = result.capped;
+    }
+    catch (err) {
+        artifactErrors.push({
+            artifact: 'failed-attempt sidecar',
+            code: errnoCodeOf(err),
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    let wal = {};
+    try {
+        wal = await stores.traceBufferStore.readAllForRun(runId);
+    }
+    catch (err) {
+        artifactErrors.push({
+            artifact: 'trace-buffer WAL',
+            code: errnoCodeOf(err),
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
     const bundle = {
-        realm_export_version: 1,
+        realm_export_version: 2,
         exported_at: now.toISOString(),
         run,
         attempts,
         attempts_capped: attemptsCapped,
         wal,
+        complete: artifactErrors.length === 0,
+        artifact_errors: artifactErrors,
     };
     const warning = !isTerminalPhase(run.run_phase)
         ? `best-effort snapshot: run '${runId}' is still ${run.run_phase}; its artifacts are read at ` +
@@ -119,6 +161,18 @@ export const exportCommand = new Command('export')
         const target = resolveExportPath({ runId, out: opts.out, runsDir });
         const json = JSON.stringify(bundle, null, 2);
         await writeFile(target, json, 'utf8');
+        // issue #186: an incomplete bundle is still written (for recovery) but never reported as a
+        // plain success — the exit code carries the signal for CI/scripts, and the operator sees
+        // exactly which artifact(s) failed and why. No --allow-incomplete flag: honesty here is not
+        // opt-in.
+        if (!bundle.complete) {
+            console.error(`⚠ INCOMPLETE export: ${bundle.artifact_errors.length} artifact(s) could not be read`);
+            for (const e of bundle.artifact_errors) {
+                console.error(`  ✗ ${e.artifact} (${e.code}): ${e.message}`);
+            }
+            console.error(`The bundle was still written to '${target}' — inspect it for what could be recovered.`);
+            process.exit(1);
+        }
         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}`);

package/dist/commands/export.js.map

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

package/dist/commands/gc.d.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import type { OrphanSweepableStore } from '@sensigo/realm';
 export interface SweepOrphansOptions {
     /** Minimum age (ms) a `.tmp` must have to be reaped. Rejected below `FLOOR_MS` — see above. */
     olderThanMs: number;
@@ -43,5 +44,54 @@ export interface SweepOrphansResult {
  *    `unlink`ed — success → `reaped`; ENOENT → `already_gone`; anything else → `failed`.
  */
 export declare function sweepOrphans(runsDir: string, options: SweepOrphansOptions): Promise<SweepOrphansResult>;
+/** One orphan artifact's outcome in a sweep report — carries the runId alongside the path so an
+ *  operator can correlate a reaped file back to which run it belonged to. */
+export interface OrphanArtifactEntry {
+    path: string;
+    runId: string;
+}
+export interface OrphanArtifactSweepResult {
+    /** Reaped (force mode) or would-be-reaped (dry-run) artifacts. */
+    reaped: OrphanArtifactEntry[];
+    /** A candidate vanished on its own (unlink hit ENOENT) — benign, never a failure. */
+    already_gone: OrphanArtifactEntry[];
+    /** A genuine delete failure (permissions, I/O) — loud, never silently swallowed. */
+    failed: Array<{
+        path: string;
+        runId: string;
+        error: string;
+    }>;
+}
+/**
+ * Reaps run-less orphaned WAL/sidecar artifacts (issue #163) — the second sweep behind
+ * `realm run gc`. `stores` is every `OrphanSweepableStore` gc knows about (today:
+ * `JsonTraceBufferStore`, `FailedAttemptStore`); `liveRunIds` is the caller's ALREADY-COMPUTED
+ * `JsonFileStore.listRunIds()` result (computed once, shared across every store, and — this is
+ * load-bearing — the caller's responsibility to have fail-closed on: see the CLI action for why
+ * this function never calls `listRunIds()` itself).
+ *
+ * **The floor is the create-temp-window guard.** `append_trace` calls `runStore.get(runId)`
+ * BEFORE ever writing a WAL entry, so a WAL's `<runId>.json` provably existed at WAL-creation
+ * time and exists for the run's entire life (see this module's own header for the full
+ * correctness backbone). The ONLY way "artifact present, run file absent" can be true for a
+ * FRESH run is the sub-second window between the run file being written as a temp
+ * (`<id>.json.<pid>.tmp`) and its atomic rename to `<id>.json` — during which `listRunIds()`
+ * would not yet see it. `FLOOR_MS` (1h) dwarfs that window by many orders of magnitude, so a
+ * fresh in-flight run's WAL is always younger than the floor and never selected; a WAL/sidecar
+ * OLDER than the floor with no matching run file is genuinely run-less.
+ *
+ * Each `OrphanSweepableStore.listOrphans()` call is fail-closed BY THE STORE'S OWN CONTRACT (see
+ * `orphan-sweepable-store.ts`) — a non-ENOENT enumeration/stat failure throws, propagating out of
+ * THIS function too (uncaught here, deliberately): this sweep has nothing safe to report if it
+ * cannot trust what "orphaned" even means for that store, so it aborts entirely rather than
+ * reaping a partial, possibly-wrong candidate set.
+ */
+export declare function sweepOrphanArtifacts(stores: readonly OrphanSweepableStore[], liveRunIds: ReadonlySet<string>, options: SweepOrphansOptions): Promise<OrphanArtifactSweepResult>;
+/** gc's exit code: non-zero iff gc could not complete a sweep it attempted (issue #163
+ *  exit-code correction). A failed unlink in EITHER sweep, OR an aborted orphan sweep
+ *  (enumeration failed — `artifactSweepError` set), is a failure. Merely *finding* reapable
+ *  residue is NOT — that holds in both dry-run and `--force`, so this one helper decides both
+ *  branches' exit code instead of each re-deriving its own (inline) predicate. */
+export declare function gcExitCode(tempResult: SweepOrphansResult, artifactResult: OrphanArtifactSweepResult | undefined, artifactSweepError: string | undefined): number;
 export declare const gcCommand: Command;
 //# sourceMappingURL=gc.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,oBAAoB,EAAkB,MAAM,gBAAgB,CAAC;AAiC3E,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,CA0D7B;AAED;6EAC6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,qFAAqF;IACrF,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,oFAAoF;IACpF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,yBAAyB,CAAC,CA2CpC;AAqHD;;;;kFAIkF;AAClF,wBAAgB,UAAU,CACxB,UAAU,EAAE,kBAAkB,EAC9B,cAAc,EAAE,yBAAyB,GAAG,SAAS,EACrD,kBAAkB,EAAE,MAAM,GAAG,SAAS,GACrC,MAAM,CAMR;AAED,eAAO,MAAM,SAAS,SAuGlB,CAAC"}

package/dist/commands/gc.js

@@ -1,5 +1,7 @@
-// gc command — sweep orphaned atomic-write temps (issue #160, Phase 1: .tmp only).
+// gc command — sweep orphaned atomic-write temps (issue #160) AND run-less orphaned WAL/sidecar
+// artifacts (issue #163). One operator command, two independent sweeps, same flags.
 //
+// --- Sweep 1: 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
@@ -14,23 +16,49 @@
 // 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.
+// --- Sweep 2: run-less orphaned WAL/sidecar artifacts (issue #163) ---
+// #163 was ORIGINALLY filed on a premise that does not hold: it claimed a WAL could orphan
+// "between WAL-create and run-file-create." That path does not exist — `append_trace` calls
+// `runStore.get(runId)` FIRST, so a WAL's `<runId>.json` provably existed at WAL-creation time and
+// exists for the run's ENTIRE life. "Artifact present, run file absent" is therefore only true
+// AFTER the run file has been deleted (a pre-#183 purge, a manual `rm`, disk corruption) or DURING
+// the sub-second atomic-write temp-rename window (the run file is a `<id>.json.<pid>.tmp`, not yet
+// renamed). This is remediation for the rare/residual case, not a rescue for an ongoing leak — the
+// git history shows the pre-#183/#184 orphan-manufacturing window was ~48h and opt-in.
+//
+// `.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). Neither is this command's job
+// yet — 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 { WorkflowError, deleteIfExists } 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.
+ * Minimum `--older-than` EITHER 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); a run-less WAL/sidecar past this floor is genuinely orphaned, not merely
+ * in-flight (see `sweepOrphanArtifacts`'s own doc for why the floor is exactly the create-window
+ * guard there) — either way this floor is conservatism, not the per-sweep safety mechanism.
+ * Module-private: the only way to reach a delete in EITHER sweep is through `assertOlderThanFloor`,
+ * checked FIRST, before any filesystem access.
  */
 const FLOOR_MS = 3_600_000;
+/** Shared floor guard for both sweeps — checked before any filesystem access in either. */
+function assertOlderThanFloor(olderThanMs, subject) {
+    if (olderThanMs < FLOOR_MS) {
+        throw new WorkflowError(`--older-than must resolve to at least 1h (got ${olderThanMs}ms) — gc refuses to reap ` +
+            `${subject} younger than that, even with --force.`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { olderThanMs, floorMs: FLOOR_MS },
+        });
+    }
+}
 /**
  * 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
@@ -72,16 +100,7 @@ async function findTempCandidates(runsDir) {
  *    `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 },
-        });
-    }
+    assertOlderThanFloor(options.olderThanMs, 'crash residue');
     const now = options.now ?? new Date();
     const candidatePaths = await findTempCandidates(runsDir);
     const result = { reaped: [], already_gone: [], failed: [] };
@@ -136,6 +155,70 @@ export async function sweepOrphans(runsDir, options) {
     }
     return result;
 }
+/**
+ * Reaps run-less orphaned WAL/sidecar artifacts (issue #163) — the second sweep behind
+ * `realm run gc`. `stores` is every `OrphanSweepableStore` gc knows about (today:
+ * `JsonTraceBufferStore`, `FailedAttemptStore`); `liveRunIds` is the caller's ALREADY-COMPUTED
+ * `JsonFileStore.listRunIds()` result (computed once, shared across every store, and — this is
+ * load-bearing — the caller's responsibility to have fail-closed on: see the CLI action for why
+ * this function never calls `listRunIds()` itself).
+ *
+ * **The floor is the create-temp-window guard.** `append_trace` calls `runStore.get(runId)`
+ * BEFORE ever writing a WAL entry, so a WAL's `<runId>.json` provably existed at WAL-creation
+ * time and exists for the run's entire life (see this module's own header for the full
+ * correctness backbone). The ONLY way "artifact present, run file absent" can be true for a
+ * FRESH run is the sub-second window between the run file being written as a temp
+ * (`<id>.json.<pid>.tmp`) and its atomic rename to `<id>.json` — during which `listRunIds()`
+ * would not yet see it. `FLOOR_MS` (1h) dwarfs that window by many orders of magnitude, so a
+ * fresh in-flight run's WAL is always younger than the floor and never selected; a WAL/sidecar
+ * OLDER than the floor with no matching run file is genuinely run-less.
+ *
+ * Each `OrphanSweepableStore.listOrphans()` call is fail-closed BY THE STORE'S OWN CONTRACT (see
+ * `orphan-sweepable-store.ts`) — a non-ENOENT enumeration/stat failure throws, propagating out of
+ * THIS function too (uncaught here, deliberately): this sweep has nothing safe to report if it
+ * cannot trust what "orphaned" even means for that store, so it aborts entirely rather than
+ * reaping a partial, possibly-wrong candidate set.
+ */
+export async function sweepOrphanArtifacts(stores, liveRunIds, options) {
+    assertOlderThanFloor(options.olderThanMs, 'orphaned artifacts');
+    const now = options.now ?? new Date();
+    const candidates = [];
+    for (const store of stores) {
+        candidates.push(...(await store.listOrphans(liveRunIds)));
+    }
+    const result = { reaped: [], already_gone: [], failed: [] };
+    const toReap = [];
+    for (const artifact of candidates) {
+        const ageMs = now.getTime() - artifact.mtimeMs;
+        if (ageMs < 0)
+            continue; // future mtime (clock skew) — skip, never reap
+        if (ageMs <= options.olderThanMs)
+            continue; // too fresh — the create-temp-window guard above
+        toReap.push(artifact);
+    }
+    if (options.dryRun) {
+        result.reaped = toReap.map((a) => ({ path: a.path, runId: a.runId }));
+        return result;
+    }
+    for (const artifact of toReap) {
+        const entry = { path: artifact.path, runId: artifact.runId };
+        try {
+            // #183 discipline: deleteIfExists resolves false (not an error) on ENOENT — already gone
+            // is success, never a failure; any other errno throws.
+            const didDelete = await deleteIfExists(artifact.path);
+            if (didDelete) {
+                result.reaped.push(entry);
+            }
+            else {
+                result.already_gone.push(entry);
+            }
+        }
+        catch (err) {
+            result.failed.push({ ...entry, 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) {
@@ -159,12 +242,21 @@ function formatBytes(n) {
     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.';
+ *  does not touch — printed on every report, dry-run or force, empty or not. issue #163: WALs and
+ *  failed-attempt sidecars are now reaped (the second sweep above) — only `.lock` dirs remain
+ *  deferred (issue #164). */
+const NOT_REAPED_FOOTER = 'gc does NOT yet reap orphaned .lock dirs (deferred — issue #164). 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) {
+ *  the initial (always non-destructive) preview pass — see the action below for why.
+ *
+ * `artifactResult`/`artifactSweepError` are mutually exclusive (issue #163): a defined
+ * `artifactSweepError` means `listRunIds()` or a store's `listOrphans()` threw — the orphan
+ * sweep aborted loudly, reaping NOTHING, and there is no `artifactResult` to report. Both may be
+ * `undefined` only if the temp-only sweep somehow bypassed the orphan sweep entirely (never
+ * happens in the real CLI action — always one or the other).
+ */
+function printGcReport(result, previewBytes, dryRun, artifactResult, artifactSweepError) {
     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.');
@@ -187,11 +279,54 @@ function printGcReport(result, previewBytes, dryRun) {
     if (dryRun && !nothingToReport) {
         console.log('\nRe-run with --force to actually delete.');
     }
+    // --- orphan-artifacts section (issue #163) ---
+    if (artifactSweepError !== undefined) {
+        console.error(`\n✗ orphan-artifact sweep ABORTED (reaped nothing from it): ${artifactSweepError}`);
+    }
+    else if (artifactResult !== undefined) {
+        const nothingToReportArtifacts = artifactResult.reaped.length === 0 &&
+            artifactResult.already_gone.length === 0 &&
+            artifactResult.failed.length === 0;
+        if (nothingToReportArtifacts) {
+            console.log('\nNo run-less orphaned WAL/sidecar artifacts found to reap.');
+        }
+        else if (dryRun) {
+            console.log(`\n${artifactResult.reaped.length} run-less orphaned artifact(s) WOULD be reaped:`);
+            for (const a of artifactResult.reaped)
+                console.log(`  • ${a.path}  (run ${a.runId})`);
+            if (artifactResult.already_gone.length > 0) {
+                console.log(`(${artifactResult.already_gone.length} candidate(s) already vanished on their own.)`);
+            }
+        }
+        else {
+            console.log(`\nReaped ${artifactResult.reaped.length} run-less orphaned artifact(s). ` +
+                `${artifactResult.already_gone.length} already gone, ${artifactResult.failed.length} failed.`);
+            for (const a of artifactResult.reaped)
+                console.log(`  • ${a.path}  (run ${a.runId})`);
+        }
+        for (const f of artifactResult.failed) {
+            console.error(`  ✗ ${f.path} (run ${f.runId}): ${f.error}`);
+        }
+        if (dryRun && !nothingToReportArtifacts) {
+            console.log('Re-run with --force to actually delete.');
+        }
+    }
     console.log(`\n${NOT_REAPED_FOOTER}`);
 }
+/** gc's exit code: non-zero iff gc could not complete a sweep it attempted (issue #163
+ *  exit-code correction). A failed unlink in EITHER sweep, OR an aborted orphan sweep
+ *  (enumeration failed — `artifactSweepError` set), is a failure. Merely *finding* reapable
+ *  residue is NOT — that holds in both dry-run and `--force`, so this one helper decides both
+ *  branches' exit code instead of each re-deriving its own (inline) predicate. */
+export function gcExitCode(tempResult, artifactResult, artifactSweepError) {
+    const anyFailure = tempResult.failed.length > 0 ||
+        (artifactResult?.failed.length ?? 0) > 0 ||
+        artifactSweepError !== undefined;
+    return anyFailure ? 1 : 0;
+}
 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)')
+    .description('Sweep orphaned atomic-write .tmp files and run-less orphaned WAL/sidecar artifacts (dry-run by default)')
+    .requiredOption('--older-than <duration>', 'Reap residue 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;
@@ -203,16 +338,22 @@ export const gcCommand = new Command('gc')
         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.
+    // Defense-in-depth over sweepOrphans's/sweepOrphanArtifacts's own floor checks — 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 { 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);
+    const orphanSweepableStores = [traceBufferStore, failedAttemptStore];
     const now = new Date();
     try {
         // Always preview first — this NEVER mutates, in either mode — because it is the only
@@ -223,14 +364,53 @@ export const gcCommand = new Command('gc')
         // already_gone exists to absorb.
         const preview = await sweepOrphans(runsDir, { olderThanMs, dryRun: true, now });
         const bytes = await statPathBytes(preview.reaped);
+        // issue #163: FAIL-CLOSED. A `listRunIds()` (or a store's `listOrphans()`) failure aborts
+        // ONLY the orphan-artifact sweep, loudly — it must NEVER fabricate an empty `liveRunIds`,
+        // which would make every live run's artifacts look orphaned and reap them. The temp sweep
+        // above is fully independent of this and is completely unaffected either way.
+        let artifactPreview;
+        let artifactSweepError;
+        try {
+            const liveRunIds = await runStore.listRunIds();
+            artifactPreview = await sweepOrphanArtifacts(orphanSweepableStores, liveRunIds, {
+                olderThanMs,
+                dryRun: true,
+                now,
+            });
+        }
+        catch (err) {
+            artifactSweepError = err instanceof Error ? err.message : String(err);
+        }
         if (opts.force !== true) {
-            printGcReport(preview, bytes, true);
+            printGcReport(preview, bytes, true, artifactPreview, artifactSweepError);
+            if (gcExitCode(preview, artifactPreview, artifactSweepError) !== 0) {
+                process.exit(1);
+            }
             return;
         }
         const result = await sweepOrphans(runsDir, { olderThanMs, dryRun: false, now });
-        printGcReport(result, bytes, false);
-        if (result.failed.length > 0)
+        let artifactResult;
+        if (artifactSweepError === undefined) {
+            // The preview above already proved listRunIds()/listOrphans() succeed — re-read for the
+            // real pass (a fresh liveRunIds, since force mode is a separate call; a run created or
+            // completed between the preview and here is a benign, narrow race — exactly the same
+            // shape the temp sweep's own preview/force split already accepts).
+            try {
+                const liveRunIds = await runStore.listRunIds();
+                artifactResult = await sweepOrphanArtifacts(orphanSweepableStores, liveRunIds, {
+                    olderThanMs,
+                    dryRun: false,
+                    now,
+                });
+            }
+            catch (err) {
+                artifactSweepError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        printGcReport(result, bytes, false, artifactResult, artifactSweepError);
+        if (gcExitCode(result, artifactResult, artifactSweepError) !== 0) {
             process.exit(1);
+        }
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));