cool-workflow 0.1.80 → 0.1.81

package/dist/reclamation.js

@@ -29,7 +29,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReclamationError = exports.ReclamationAbort = exports.SKELETON_REQUIRED_KEYS = exports.RECLAMATION_SCHEMA_VERSION = void 0;
+exports.ReclamationError = exports.ReclamationAbort = exports.SKELETON_REQUIRED_KEYS = void 0;
 exports.sha256OfString = sha256OfString;
 exports.sha256OfFile = sha256OfFile;
 exports.dirBytes = dirBytes;
@@ -56,7 +56,7 @@ const multi_agent_eval_1 = require("./multi-agent-eval");
 const node_snapshot_1 = require("./node-snapshot");
 const state_1 = require("./state");
 const trust_audit_1 = require("./trust-audit");
-exports.RECLAMATION_SCHEMA_VERSION = 1;
+const compare_1 = require("./compare");
 /** The skeleton schema is the contract for what MUST survive every reclamation.
  *  Machine-checkable via validateSkeleton(). If extraction can't produce all of
  *  these, reclamation fails closed and frees nothing. */
@@ -135,7 +135,7 @@ function contentDigest(p) {
         return sha256OfFile(p);
     const parts = [];
     const walk = (dir, rel) => {
-        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (0, compare_1.compareBytes)(a.name, b.name))) {
             const abs = node_path_1.default.join(dir, entry.name);
             const r = node_path_1.default.join(rel, entry.name);
             if (entry.isDirectory())
@@ -261,7 +261,7 @@ function extractSkeleton(run) {
     }
     const evidenceDigests = [...evidenceMap.entries()]
         .map(([ref, digest]) => ({ ref, digest }))
-        .sort((a, b) => a.ref.localeCompare(b.ref));
+        .sort((a, b) => (0, compare_1.compareBytes)(a.ref, b.ref));
     const eventLog = auditEventLogPath(run);
     const auditLogDigest = node_fs_1.default.existsSync(eventLog) ? sha256OfFile(eventLog) : sha256OfString("");
     const events = node_fs_1.default.existsSync(eventLog)
@@ -287,7 +287,7 @@ function extractSkeleton(run) {
     };
     const collaboration = run.collaboration;
     const collaborationLog = {
-        digest: sha256OfString((0, multi_agent_eval_1.stableStringify)(collaboration || {})),
+        digest: sha256OfString((0, multi_agent_eval_1.replayStableStringify)(collaboration || {})),
         approvals: collaboration?.approvals?.length || 0,
         comments: collaboration?.comments?.length || 0,
         handoffs: collaboration?.handoffs?.length || 0
@@ -414,12 +414,12 @@ function snapshotProjectionDigest(node) {
         contractId: node.contractId,
         metadata: node.metadata
     });
-    return sha256OfString((0, multi_agent_eval_1.stableStringify)(body));
+    return sha256OfString((0, multi_agent_eval_1.replayStableStringify)(body));
 }
 /** Body digest of the RETAINED node (lives in state.json). The reconstruction
  *  verifier re-derives the projection from this retained input. */
 function nodeBodyDigest(node) {
-    return sha256OfString((0, multi_agent_eval_1.stableStringify)(rawNodeBody(node)));
+    return sha256OfString((0, multi_agent_eval_1.replayStableStringify)(rawNodeBody(node)));
 }
 function rawNodeBody(node) {
     return {
@@ -449,7 +449,6 @@ function planReclamation(run, policy = {}) {
     // freeable once the result node's worker-result artifact is re-pointed.
     let reclaimedScratch = false;
     if (!policy.keepScratch) {
-        const workersDir = run.paths.workersDir || node_path_1.default.join(runDir, "workers");
         for (const scope of run.workers || []) {
             const workerDir = scope.workerDir;
             if (!workerDir || !node_fs_1.default.existsSync(workerDir))
@@ -472,7 +471,6 @@ function planReclamation(run, policy = {}) {
             });
             reclaimedScratch = true;
         }
-        void workersDir;
     }
     // A node whose scratch is being re-pointed THIS pass must NOT also have its
     // snapshot freed in the same pass — re-pointing mutates the node body, which
@@ -515,7 +513,7 @@ function planReclamation(run, policy = {}) {
                     const recipe = {
                         recipeKind: "node-snapshot-projection",
                         inputDigests: [inputDigest],
-                        inputsDigest: sha256OfString((0, multi_agent_eval_1.stableStringify)([inputDigest])),
+                        inputsDigest: sha256OfString((0, multi_agent_eval_1.replayStableStringify)([inputDigest])),
                         expectDigest: snapshotProjectionDigest(node),
                         sourceRef: node.id
                     };
@@ -531,6 +529,13 @@ function planReclamation(run, policy = {}) {
     // retention, and we do not yet auto-capture reconstruction recipes for them.
     // The reference graph is consulted so the door is closed, not merely unbuilt.
     void buildReferenceGraph;
+    // Determinism (HARD constraint): the snapshot candidates above are gathered in
+    // fs.readdirSync order, which is filesystem-dependent. freeable feeds the freed
+    // manifest that buildTombstone binds into tombstoneHash (and the prevTombstoneHash
+    // chain), so an unsorted order makes the tombstone hash irreproducible across
+    // hosts. Sort by path — the same compareBytes discipline the directory reads at
+    // :128 and the reference list at :243 already use — before anything hashes it.
+    freeable.sort((a, b) => (0, compare_1.compareBytes)(a.path, b.path));
     const byKind = {};
     let bytesToFree = 0;
     for (const entry of freeable) {
@@ -557,16 +562,16 @@ function planReclamation(run, policy = {}) {
     return { freeable, bytesToFree, byKind, capability, capabilityReason };
 }
 function policyDigestOf(policy) {
-    return sha256OfString((0, multi_agent_eval_1.stableStringify)(policy));
+    return sha256OfString((0, multi_agent_eval_1.replayStableStringify)(policy));
 }
 /** genesis prevTombstoneHash = sha256 of the sealed skeleton. */
 function genesisPrevHash(skeleton) {
-    return sha256OfString((0, multi_agent_eval_1.stableStringify)(skeleton));
+    return sha256OfString((0, multi_agent_eval_1.replayStableStringify)(skeleton));
 }
 /** The canonical bytes a tombstoneHash binds: freed-manifest + sealed skeleton +
  *  prevTombstoneHash + capability. Recomputed independently by `gc verify`. */
 function tombstoneHashInput(t) {
-    return (0, multi_agent_eval_1.stableStringify)({
+    return (0, multi_agent_eval_1.replayStableStringify)({
         runId: t.runId,
         tombstoneId: t.tombstoneId,
         reclaimedAt: t.reclaimedAt,
@@ -574,7 +579,7 @@ function tombstoneHashInput(t) {
         policyDigest: t.policyDigest,
         freed: t.freed.map((f) => ({ path: f.path, kind: f.kind, bytes: f.bytes, sha256: f.sha256, recipe: f.recipe || null })),
         bytesFreed: t.bytesFreed,
-        skeletonDigest: sha256OfString((0, multi_agent_eval_1.stableStringify)(t.skeleton)),
+        skeletonDigest: sha256OfString((0, multi_agent_eval_1.replayStableStringify)(t.skeleton)),
         capability: t.capability,
         capabilityReason: t.capabilityReason,
         prevTombstoneHash: t.prevTombstoneHash
@@ -583,11 +588,11 @@ function tombstoneHashInput(t) {
 function computeTombstoneHash(t) {
     return sha256OfString(tombstoneHashInput(t));
 }
-let tombstoneCounter = 0;
-function tombstoneId(run, now) {
-    tombstoneCounter += 1;
-    const stamp = now.replace(/[-:.TZ]/g, "").slice(0, 14);
-    return `tomb-${stamp}-${String(tombstoneCounter).padStart(3, "0")}`;
+function tombstoneId(seq) {
+    // Deterministic (FreeBSD-audit L13): the chain POSITION, not a process-global
+    // counter or wall-clock stamp — tombstoneId is bound into the tombstoneHash
+    // chain that `gc verify` recomputes, so it must be reproducible.
+    return `tomb-${String(seq).padStart(3, "0")}`;
 }
 /** STEP 2: build the FULL tombstone (pre-deletion sha256 per freed path + the
  *  hash chain). Reads the freed files (still present); mutates nothing on disk. */
@@ -605,7 +610,7 @@ function buildTombstone(run, skeleton, plan, options = {}) {
     const base = {
         schemaVersion: 1,
         runId: run.id,
-        tombstoneId: tombstoneId(run, now),
+        tombstoneId: tombstoneId(prior.length + 1),
         reclaimedAt: now,
         actor: options.actor,
         policyDigest: policyDigestOf(options.policy || {}),
@@ -800,7 +805,7 @@ function reconstructArtifact(run, recipe) {
             return { inputsDigest: sha256OfString("absent"), expectDigest: sha256OfString("absent") };
         }
         const inputDigest = nodeBodyDigest(node);
-        const inputsDigest = sha256OfString((0, multi_agent_eval_1.stableStringify)([inputDigest]));
+        const inputsDigest = sha256OfString((0, multi_agent_eval_1.replayStableStringify)([inputDigest]));
         const expectDigest = snapshotProjectionDigest(node);
         return { inputsDigest, expectDigest };
     }

package/dist/run-export.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.exportRun = exportRun;
 exports.importRun = importRun;
 exports.verifyImportedRun = verifyImportedRun;
+exports.inspectArchive = inspectArchive;
 exports.importManifestPath = importManifestPath;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -21,6 +22,8 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const state_1 = require("./state");
 const version_1 = require("./version");
 const telemetry_ledger_1 = require("./telemetry-ledger");
+const trust_audit_1 = require("./trust-audit");
+const compare_1 = require("./compare");
 /** Export a run to a portable JSON archive with run-local bytes and digests. */
 function exportRun(run, outputPath) {
     const exportedAt = new Date().toISOString();
@@ -187,6 +190,17 @@ function verifyImportedRun(run) {
         pass: telemetry.verified,
         code: telemetry.verified ? undefined : "telemetry-ledger-invalid"
     });
+    // Re-prove the trust-audit hash chain on restore too. Telemetry was already
+    // re-proven above, but the decisions/sandbox/commit-gate audit chain — also
+    // exported under audit/ — was not, an asymmetry a tampered restore could slip
+    // through. An absent chain is verified:true (nothing to prove), so archives
+    // predating audit export append a PASSING check — no false-red.
+    const audit = (0, trust_audit_1.verifyTrustAudit)(run);
+    checks.push({
+        name: "trust-audit",
+        pass: audit.verified,
+        code: audit.verified ? undefined : "trust-audit-invalid"
+    });
     return {
         runId: run.id,
         ok: checks.every((check) => check.pass),
@@ -195,6 +209,70 @@ function verifyImportedRun(run) {
         checks
     };
 }
+/** Read-only integrity inspection of a portable archive WITHOUT importing it. Never
+ *  throws — a read error, bad JSON, unsupported schema, or any digest/size/count/
+ *  manifest mismatch is reported as a structured check with ok:false. Writes nothing. */
+function inspectArchive(archivePath) {
+    const base = {
+        schemaVersion: 1,
+        archivePath,
+        ok: false,
+        schemaSupported: false,
+        runId: null,
+        fileCount: 0,
+        manifestSha256: null,
+        archiveSha256: null,
+        checks: []
+    };
+    let bytes;
+    try {
+        bytes = node_fs_1.default.readFileSync(archivePath);
+    }
+    catch (error) {
+        return { ...base, checks: [{ name: "archive", pass: false, code: "archive-unreadable", path: archivePath, actual: messageOf(error) }] };
+    }
+    base.archiveSha256 = sha256Bytes(bytes);
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString("utf8"));
+    }
+    catch (error) {
+        return { ...base, checks: [{ name: "archive", pass: false, code: "archive-invalid-json", path: archivePath, actual: messageOf(error) }] };
+    }
+    if (raw.schemaVersion !== 1) {
+        return {
+            ...base,
+            schemaVersion: typeof raw.schemaVersion === "number" ? raw.schemaVersion : base.schemaVersion,
+            checks: [{ name: "schema", pass: false, code: "unsupported-schema", expected: "1", actual: String(raw.schemaVersion) }]
+        };
+    }
+    try {
+        const files = normalizeArchiveFiles(raw);
+        const { checks } = collectArchiveDigestChecks(files, raw.integrity);
+        // Faithful preview of what `run import` would do under the same env: with
+        // CW_REQUIRE_ARCHIVE_INTEGRITY=1 a stripped-integrity archive is refused by
+        // import, so inspect must also report it as failing (ok:false / exit 1) rather
+        // than green — otherwise inspect-before-import is misleading in that policy.
+        // Default (env unset) is unchanged: inspection only reports the digest checks.
+        if (!raw.integrity && /^(1|true|yes|on)$/i.test(process.env.CW_REQUIRE_ARCHIVE_INTEGRITY || "")) {
+            checks.push({ name: "archive-integrity", pass: false, code: "archive-integrity-required" });
+        }
+        return {
+            schemaVersion: 1,
+            archivePath,
+            ok: checks.every((c) => c.pass),
+            schemaSupported: true,
+            runId: raw.run && raw.run.id ? raw.run.id : null,
+            fileCount: files.length,
+            manifestSha256: raw.integrity ? digestManifest(files) : null,
+            archiveSha256: base.archiveSha256,
+            checks
+        };
+    }
+    catch (error) {
+        return { ...base, schemaSupported: true, checks: [{ name: "archive", pass: false, code: "archive-malformed", path: archivePath, actual: messageOf(error) }] };
+    }
+}
 function importManifestPath(run) {
     return node_path_1.default.join(run.paths.runDir, "import-manifest.json");
 }
@@ -216,7 +294,7 @@ function collectArchiveFiles(run) {
         if ((0, state_1.isContainedPath)(artifactPath, run.cwd))
             addExternalArtifactFile(entries, run, artifactPath);
     }
-    return [...entries.values()].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    return [...entries.values()].sort((left, right) => (0, compare_1.compareBytes)(left.relativePath, right.relativePath));
 }
 function addFile(entries, run, file, role) {
     const relativePath = toArchivePath(node_path_1.default.relative(run.paths.runDir, file));
@@ -318,34 +396,80 @@ function normalizeArchiveFiles(raw) {
         };
     });
 }
-function verifyArchiveFileDigests(files, integrity) {
+/** NON-throwing digest/size/count/manifest verification: one structured check per
+ *  file (in import order), then the integrity file-count + manifest checks. Shared
+ *  by the throwing import path (verifyArchiveFileDigests) and the read-only
+ *  inspectArchive, so a single offender list has one source of truth. */
+function collectArchiveDigestChecks(files, integrity) {
+    const checks = [];
     for (const file of files) {
         const bytes = Buffer.from(file.contentBase64, "base64");
         const actual = sha256Bytes(bytes);
-        if (actual !== file.sha256)
-            throw new Error(`Archive digest mismatch for ${file.relativePath}: expected ${file.sha256}, got ${actual}`);
-        if (bytes.length !== file.sizeBytes)
-            throw new Error(`Archive size mismatch for ${file.relativePath}: expected ${file.sizeBytes}, got ${bytes.length}`);
+        const digestOk = actual === file.sha256;
+        checks.push(digestOk
+            ? { name: "archive-file", pass: true, path: file.relativePath }
+            : { name: "archive-file", pass: false, code: "digest-mismatch", path: file.relativePath, expected: file.sha256, actual });
+        const sizeOk = bytes.length === file.sizeBytes;
+        checks.push(sizeOk
+            ? { name: "archive-file", pass: true, path: file.relativePath }
+            : { name: "archive-file", pass: false, code: "size-mismatch", path: file.relativePath, expected: String(file.sizeBytes), actual: String(bytes.length) });
     }
     if (integrity) {
+        const countOk = integrity.fileCount === files.length;
+        checks.push(countOk
+            ? { name: "archive-file-count", pass: true }
+            : { name: "archive-file-count", pass: false, code: "file-count-mismatch", expected: String(integrity.fileCount), actual: String(files.length) });
         const actualManifest = digestManifest(files);
-        if (integrity.fileCount !== files.length)
-            throw new Error(`Archive file count mismatch: expected ${integrity.fileCount}, got ${files.length}`);
-        if (integrity.manifestSha256 !== actualManifest) {
-            throw new Error(`Archive manifest digest mismatch: expected ${integrity.manifestSha256}, got ${actualManifest}`);
-        }
+        const manifestOk = integrity.manifestSha256 === actualManifest;
+        checks.push(manifestOk
+            ? { name: "archive-manifest", pass: true }
+            : { name: "archive-manifest", pass: false, code: "manifest-digest-mismatch", expected: integrity.manifestSha256, actual: actualManifest });
+    }
+    return { checks, ok: checks.every((c) => c.pass) };
+}
+/** Reconstruct the legacy throw message for a failing check, so the throwing import
+ *  path stays BYTE-IDENTICAL after the collector refactor. */
+function archiveCheckMessage(check) {
+    switch (check.code) {
+        case "digest-mismatch": return `Archive digest mismatch for ${check.path}: expected ${check.expected}, got ${check.actual}`;
+        case "size-mismatch": return `Archive size mismatch for ${check.path}: expected ${check.expected}, got ${check.actual}`;
+        case "file-count-mismatch": return `Archive file count mismatch: expected ${check.expected}, got ${check.actual}`;
+        case "manifest-digest-mismatch": return `Archive manifest digest mismatch: expected ${check.expected}, got ${check.actual}`;
+        default: return `Archive verification failed: ${check.name}`;
+    }
+}
+function verifyArchiveFileDigests(files, integrity) {
+    // Opt-in hardening (CW_REQUIRE_ARCHIVE_INTEGRITY=1): refuse an archive whose
+    // top-level integrity block (manifest digest + file count) is absent, closing the
+    // legacy fail-open seam where a stripped-integrity archive imported unverified.
+    // Same env-boolish convention as CW_REQUIRE_RESOLVABLE_EVIDENCE (evidence-grounding.ts:57).
+    // Default (unset) keeps legacy integrity-less archives byte-identical.
+    if (!integrity && /^(1|true|yes|on)$/i.test(process.env.CW_REQUIRE_ARCHIVE_INTEGRITY || "")) {
+        throw new Error("Archive integrity block required but absent (CW_REQUIRE_ARCHIVE_INTEGRITY=1)");
     }
+    // Throw-before-write preserved: throw on the FIRST failing check, in the same
+    // order (per-file digest then size, then file-count, then manifest) and with the
+    // same message the inline checks produced.
+    const failed = collectArchiveDigestChecks(files, integrity).checks.find((c) => !c.pass);
+    if (failed)
+        throw new Error(archiveCheckMessage(failed));
 }
 function digestManifest(files) {
     const manifest = files
+        // sourcePath is deliberately EXCLUDED: it is a host-absolute bookkeeping path
+        // (for externalPathMap), not integrity-bearing content — the file's bytes are
+        // already bound by sha256 + sizeBytes. Including it would make the digest
+        // differ across hosts for byte-identical content, defeating cross-host repro.
         .map((file) => ({
         relativePath: file.relativePath,
         role: file.role,
         sha256: file.sha256,
-        sizeBytes: file.sizeBytes,
-        sourcePath: file.sourcePath
+        sizeBytes: file.sizeBytes
     }))
-        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+        // Codepoint order, NOT localeCompare: this manifest feeds a sha256 integrity
+        // digest. Locale-sensitive collation would order identical bytes differently
+        // across hosts/locales, making the digest non-reproducible cross-host.
+        .sort((left, right) => (left.relativePath < right.relativePath ? -1 : left.relativePath > right.relativePath ? 1 : 0));
     return sha256Bytes(Buffer.from(JSON.stringify(manifest), "utf8"));
 }
 function rebaseRun(source, context) {

package/dist/run-registry/derive.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIFECYCLE_STATES = void 0;
+exports.compareRecords = compareRecords;
+exports.compareHistory = compareHistory;
+exports.compareQueue = compareQueue;
+exports.matchesQuery = matchesQuery;
+exports.distinctBackends = distinctBackends;
+exports.digestInputs = digestInputs;
+exports.countRecords = countRecords;
+exports.optionalLower = optionalLower;
+exports.clampInt = clampInt;
+exports.queueId = queueId;
+exports.isRunLifecycleState = isRunLifecycleState;
+exports.loadReclaimedFromDir = loadReclaimedFromDir;
+// Pure, stateless helpers for the run registry — comparison, query matching,
+// input digesting, counting, and small utilities. Carved out of run-registry.ts
+// (FreeBSD-audit R2) so the stateful RunRegistry class no longer bundles the pure
+// derivation layer. Nothing here touches `this`; everything is a pure function of
+// its arguments (queueId is the lone exception — a process-local counter, kept as
+// it was; making ID minting deterministic is a separate tracked item).
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const compare_1 = require("../compare");
+exports.LIFECYCLE_STATES = [
+    "queued",
+    "running",
+    "blocked",
+    "completed",
+    "failed",
+    "archived",
+    "reclaimed"
+];
+function compareRecords(a, b) {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? -1 : 1;
+    return (0, compare_1.compareBytes)(a.runId, b.runId);
+}
+function compareHistory(a, b) {
+    // Newest first.
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? 1 : -1;
+    return (0, compare_1.compareBytes)(a.runId, b.runId);
+}
+function compareQueue(a, b) {
+    if (a.priority !== b.priority)
+        return a.priority - b.priority;
+    if (a.enqueuedAt !== b.enqueuedAt)
+        return a.enqueuedAt < b.enqueuedAt ? -1 : 1;
+    return (0, compare_1.compareBytes)(a.id, b.id);
+}
+function matchesQuery(record, query) {
+    if (query.app && !(record.appId || record.workflowId || "").toLowerCase().includes(query.app))
+        return false;
+    if (query.status && record.lifecycle !== query.status && record.derivedLifecycle !== query.status)
+        return false;
+    if (query.repo && node_path_1.default.resolve(record.repo) !== query.repo)
+        return false;
+    if (query.since && record.createdAt < query.since)
+        return false;
+    if (query.until && record.createdAt > query.until)
+        return false;
+    if (query.text) {
+        const haystack = [
+            record.runId,
+            record.appId,
+            record.workflowId,
+            record.title,
+            record.repo,
+            record.lifecycle,
+            record.loopStage,
+            record.inputsDigest
+        ]
+            .filter(Boolean)
+            .join(" ")
+            .toLowerCase();
+        if (!haystack.includes(query.text))
+            return false;
+    }
+    return true;
+}
+/** Bounded, deterministic stringification of run inputs for free-text search.
+ *  Descriptive intent keys (question, prompt, ...) come first so they survive
+ *  truncation; the rest follow alphabetically. Deterministic and compact. */
+const DIGEST_PRIORITY_KEYS = ["question", "prompt", "task", "summary", "title", "objective", "focus", "topic"];
+/** Distinct execution backends used by a run's dispatches/tasks, recomputed from
+ *  source state. Sorted; empty for pre-v0.1.29 / default-only runs that never
+ *  recorded a backend. The registry stays backend-agnostic — this is metadata. */
+function distinctBackends(run) {
+    const backends = new Set();
+    for (const dispatch of run.dispatches || []) {
+        if (dispatch.backendId)
+            backends.add(dispatch.backendId);
+    }
+    for (const task of run.tasks || []) {
+        if (task.backendId)
+            backends.add(task.backendId);
+    }
+    return [...backends].sort();
+}
+function digestInputs(inputs) {
+    if (!inputs || typeof inputs !== "object")
+        return undefined;
+    const keys = Object.keys(inputs);
+    const ordered = [
+        ...DIGEST_PRIORITY_KEYS.filter((k) => keys.includes(k)),
+        ...keys.filter((k) => !DIGEST_PRIORITY_KEYS.includes(k)).sort()
+    ];
+    const parts = [];
+    for (const key of ordered) {
+        const value = inputs[key];
+        if (value === undefined || value === null)
+            continue;
+        const rendered = Array.isArray(value) ? value.join(",") : typeof value === "object" ? JSON.stringify(value) : String(value);
+        parts.push(`${key}=${rendered}`);
+    }
+    const joined = parts.join(" ").replace(/\s+/g, " ").trim();
+    return joined.length > 360 ? `${joined.slice(0, 357)}...` : joined;
+}
+function countRecords(records) {
+    const counts = {
+        total: records.length,
+        queued: 0,
+        running: 0,
+        blocked: 0,
+        completed: 0,
+        failed: 0,
+        archived: 0,
+        reclaimed: 0
+    };
+    for (const record of records) {
+        counts[record.lifecycle] = (counts[record.lifecycle] || 0) + 1;
+    }
+    return counts;
+}
+function optionalLower(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    return String(value).toLowerCase();
+}
+function clampInt(value, fallback, min) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.floor(n));
+}
+let queueCounter = 0;
+function queueId() {
+    queueCounter += 1;
+    const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+    return `q-${stamp}-${String(queueCounter).padStart(3, "0")}`;
+}
+function isRunLifecycleState(value) {
+    return typeof value === "string" && exports.LIFECYCLE_STATES.includes(value);
+}
+/** Read a run dir's `reclaimed.json` overlay (v0.1.39). Fail-closed to an empty
+ *  chain on absence/corruption — a malformed overlay must never brick the run. */
+function loadReclaimedFromDir(runDir) {
+    const file = node_path_1.default.join(runDir, "reclaimed.json");
+    if (!node_fs_1.default.existsSync(file))
+        return { schemaVersion: 1, runId: "", tombstones: [] };
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+        return { schemaVersion: 1, runId: parsed.runId || "", tombstones: Array.isArray(parsed.tombstones) ? parsed.tombstones : [] };
+    }
+    catch {
+        return { schemaVersion: 1, runId: "", tombstones: [] };
+    }
+}

package/dist/run-registry/format.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRegistryReport = formatRegistryReport;
+exports.formatRunSearch = formatRunSearch;
+exports.formatRunShow = formatRunShow;
+exports.formatGcPlan = formatGcPlan;
+exports.formatGcRun = formatGcRun;
+exports.formatGcVerify = formatGcVerify;
+exports.formatResume = formatResume;
+exports.formatHistory = formatHistory;
+exports.formatQueueList = formatQueueList;
+function countsLine(counts) {
+    return `total=${counts.total} queued=${counts.queued} running=${counts.running} blocked=${counts.blocked} completed=${counts.completed} failed=${counts.failed} archived=${counts.archived} reclaimed=${counts.reclaimed}`;
+}
+function recordLine(record) {
+    const flags = [record.archived ? "archived" : "", record.provenance?.rerunOf ? `rerunOf=${record.provenance.rerunOf}` : ""].filter(Boolean).join(" ");
+    return `  [${record.lifecycle}] ${record.runId} (${record.appId || record.workflowId}) ${record.loopStage}${flags ? ` {${flags}}` : ""}`;
+}
+function formatRegistryReport(report) {
+    const lines = [];
+    lines.push(`Run Registry (${report.scope}): ${report.root}`);
+    lines.push(`Freshness: ${report.freshness.status}${report.freshness.staleRuns.length ? ` (stale: ${report.freshness.staleRuns.join(", ")})` : ""}${report.freshness.missingRuns.length ? ` (missing: ${report.freshness.missingRuns.join(", ")})` : ""}`);
+    lines.push(`Repos: ${report.index.repos.length}`);
+    lines.push(countsLine(report.counts));
+    if (report.freshness.status !== "valid")
+        lines.push(`Next Action: ${report.nextAction}`);
+    return lines.join("\n");
+}
+function formatRunSearch(result) {
+    const lines = [];
+    lines.push(`Run Search (${result.scope}): ${result.total} match(es), showing ${result.records.length} [offset ${result.offset}] freshness=${result.freshness}`);
+    for (const record of result.records)
+        lines.push(recordLine(record));
+    if (!result.records.length)
+        lines.push("  (no matching runs)");
+    return lines.join("\n");
+}
+function formatRunShow(result) {
+    if (!result.found) {
+        return `Run ${result.runId}: MISSING (source state.json absent — fail closed). Next: ${result.nextAction}`;
+    }
+    const r = result.record;
+    const lines = [
+        `Run ${r.runId} [${r.lifecycle}] (derived: ${r.derivedLifecycle})`,
+        `  app=${r.appId || r.workflowId} loopStage=${r.loopStage} repo=${r.repo}`,
+        `  tasks: total=${r.tasks.total} pending=${r.tasks.pending} running=${r.tasks.running} failed=${r.tasks.failed} completed=${r.tasks.completed}`,
+        `  commits=${r.commitCount} (verifier-gated=${r.verifierGatedCommitCount}) openFeedback=${r.openFeedbackCount}`
+    ];
+    if (r.provenance?.rerunOf)
+        lines.push(`  provenance: rerunOf=${r.provenance.rerunOf} gen=${r.provenance.generation} origin=${r.provenance.originRunId}`);
+    if (r.tier && r.tier !== "live") {
+        lines.push(`  tier=${r.tier} capability=${r.capability} reason=${r.capabilityReason}${r.reclaimedBytes ? ` bytesFreed=${r.reclaimedBytes}` : ""}${r.tombstoneHash ? ` tombstone=${r.tombstoneHash.slice(0, 19)}` : ""}`);
+    }
+    return lines.join("\n");
+}
+function formatGcPlan(result) {
+    const lines = [
+        `GC Plan (${result.scope}): ${result.eligibleCount}/${result.total} eligible, ${result.bytesToFree} byte(s) would be freed [DRY-RUN, frees nothing]`,
+        `  policy: reclaimAfterArchiveDays=${result.policy.reclaimAfterArchiveDays} keepScratch=${result.policy.keepScratch} keepSnapshots=${result.policy.keepSnapshots}`
+    ];
+    for (const entry of result.entries) {
+        if (entry.eligible) {
+            const kinds = Object.entries(entry.byKind).map(([k, v]) => `${k}=${v}`).join(" ");
+            lines.push(`  [eligible] ${entry.runId} -> ${entry.capability} (${entry.capabilityReason}) ${entry.bytesToFree}B {${kinds}}`);
+        }
+        else {
+            lines.push(`  [skip:${entry.reason}] ${entry.runId} (tier=${entry.tier})`);
+        }
+    }
+    if (!result.entries.length)
+        lines.push("  (no runs in scope)");
+    return lines.join("\n");
+}
+function formatGcRun(result) {
+    const lines = [`GC Run (${result.scope}): reclaimed ${result.reclaimed.length} run(s), freed ${result.totalBytesFreed} byte(s)`];
+    for (const r of result.reclaimed)
+        lines.push(`  [reclaimed] ${r.runId} -> ${r.capability} (${r.capabilityReason}) ${r.bytesFreed}B tombstone=${r.tombstoneHash.slice(0, 19)}`);
+    for (const r of result.refused)
+        lines.push(`  [refused:${r.code}] ${r.runId}`);
+    if (!result.reclaimed.length && !result.refused.length)
+        lines.push("  (nothing eligible)");
+    return lines.join("\n");
+}
+function formatGcVerify(result) {
+    const lines = [
+        `GC Verify ${result.runId}: reclaimed=${result.reclaimed} verified=${result.verified} tier=${result.tier} capability=${result.capability}${result.tombstoneHash ? ` tombstone=${result.tombstoneHash.slice(0, 19)}` : ""}`
+    ];
+    for (const check of result.checks)
+        lines.push(`  ${check.pass ? "PASS" : "FAIL"} ${check.name}${check.code ? ` [${check.code}]` : ""}${check.detail ? ` (${check.detail})` : ""}`);
+    return lines.join("\n");
+}
+function formatResume(result) {
+    const lines = [
+        `Resume ${result.runId} [${result.lifecycle}] loopStage=${result.loopStage} (resolved from ${result.resolvedFrom}, ${result.freshness})`,
+        `  resumable=${result.resumable} nextTasks=${result.nextTasks.length}`
+    ];
+    for (const action of result.nextActions)
+        lines.push(`  -> ${action.command}\n     ${action.reason}`);
+    // Only when --drive/--once continued the run; the default read-only resume text is unchanged.
+    if (result.drive) {
+        const d = result.drive;
+        lines.push(`  drive: ${d.status} (${d.completedWorkers}/${d.plannedWorkers} workers${d.commitId ? `, committed ${d.commitId}` : ""})`);
+    }
+    return lines.join("\n");
+}
+function formatHistory(result) {
+    const lines = [];
+    lines.push(`Run History (${result.scope}): ${result.total} run(s) across ${result.repos.length} repo(s), freshness=${result.freshness}`);
+    for (const entry of result.entries) {
+        lines.push(`  ${entry.createdAt} [${entry.lifecycle}] ${entry.runId} (${entry.appId || entry.workflowId})${entry.provenance?.rerunOf ? ` rerunOf=${entry.provenance.rerunOf}` : ""}`);
+    }
+    if (!result.entries.length)
+        lines.push("  (no runs)");
+    return lines.join("\n");
+}
+function formatQueueList(result) {
+    const lines = [`Run Queue: ${result.total} entry(ies) [priority asc]`];
+    for (const entry of result.entries) {
+        lines.push(`  #${entry.priority} ${entry.id} [${entry.status}] ${entry.appId || entry.workflowId || entry.runId || "?"} repo=${entry.repo}${entry.note ? ` note=${entry.note}` : ""}`);
+    }
+    if (!result.entries.length)
+        lines.push("  (queue empty)");
+    return lines.join("\n");
+}