githolon 0.74.0 → 0.75.1

package/dist/cli.mjs

@@ -113,14 +113,14 @@ var init_git_fs = __esm({
 });
 
 // vendor/engine/tree.mjs
-function flatten(dir, prefix, out12) {
+function flatten(dir, prefix, out13) {
   for (const [name, inode] of dir.contents) {
     const path = prefix ? prefix + "/" + name : name;
     if (inode.contents instanceof Map) {
-      out12.push({ path, dir: true });
-      flatten(inode, path, out12);
+      out13.push({ path, dir: true });
+      flatten(inode, path, out13);
     } else {
-      out12.push({ path, dir: false, bytes: inode.data ?? new Uint8Array(0) });
+      out13.push({ path, dir: false, bytes: inode.data ?? new Uint8Array(0) });
     }
   }
 }
@@ -143,13 +143,13 @@ function serializeTree(workTree) {
   }
   let total = 0;
   for (const c of chunks) total += c.length;
-  const out12 = new Uint8Array(total);
+  const out13 = new Uint8Array(total);
   let off = 0;
   for (const c of chunks) {
-    out12.set(c, off);
+    out13.set(c, off);
     off += c.length;
   }
-  return out12;
+  return out13;
 }
 var enc, dec;
 var init_tree = __esm({
@@ -164,13 +164,13 @@ var init_tree = __esm({
 function concatBytes(chunks) {
   let n = 0;
   for (const c of chunks) n += c.length;
-  const out12 = new Uint8Array(n);
+  const out13 = new Uint8Array(n);
   let o = 0;
   for (const c of chunks) {
-    out12.set(c, o);
+    out13.set(c, o);
     o += c.length;
   }
-  return out12;
+  return out13;
 }
 function pkt(payload) {
   const body = typeof payload === "string" ? enc2.encode(payload) : payload;
@@ -418,6 +418,7 @@ __export(engine_exports, {
   readShape: () => readShape,
   rebirthCompact: () => rebirthCompact,
   refreshProjection: () => refreshProjection,
+  refusedSummary: () => refusedSummary,
   replicateIntents: () => replicateIntents,
   repoArgOf: () => repoArgOf,
   restoreCheckpointFromCustody: () => restoreCheckpointFromCustody,
@@ -461,13 +462,13 @@ async function sha256hex(t) {
 function osEntropyBuffer(n) {
   const bytes = new Uint8Array(n * 8);
   for (let o = 0; o < bytes.length; o += 65536) crypto.getRandomValues(bytes.subarray(o, Math.min(o + 65536, bytes.length)));
-  const out12 = new Array(n), T = 2 ** 53;
+  const out13 = new Array(n), T = 2 ** 53;
   for (let i = 0; i < n; i++) {
     let z = 0n;
     for (let b = 7; b >= 0; b--) z = z << 8n | BigInt(bytes[i * 8 + b]);
-    out12[i] = Number(z >> 11n) / T;
+    out13[i] = Number(z >> 11n) / T;
   }
-  return out12;
+  return out13;
 }
 function stringifyBig(o) {
   return JSON.stringify(o, (_k, v) => typeof v === "bigint" ? `@@B:${v}@@` : v).replace(/"@@B:(\d+)@@"/g, "$1");
@@ -914,15 +915,15 @@ function contribution(read, cur) {
   return { group, value: typeof raw === "number" ? raw : 0 };
 }
 function contributionDiff(read, before, after) {
-  const out12 = [];
+  const out13 = [];
   if (before && after && before.group === after.group) {
     const d = after.value - before.value;
-    if (d !== 0) out12.push({ readId: read.id, group: after.group, delta: d });
-    return out12;
+    if (d !== 0) out13.push({ readId: read.id, group: after.group, delta: d });
+    return out13;
   }
-  if (before) out12.push({ readId: read.id, group: before.group, delta: -before.value });
-  if (after) out12.push({ readId: read.id, group: after.group, delta: after.value });
-  return out12.filter((d) => d.delta !== 0);
+  if (before) out13.push({ readId: read.id, group: before.group, delta: -before.value });
+  if (after) out13.push({ readId: read.id, group: after.group, delta: after.value });
+  return out13.filter((d) => d.delta !== 0);
 }
 function countTenantRows(eng, ws) {
   let total = 0;
@@ -935,16 +936,16 @@ async function countTenantRowsByHome(eng, ws, homeKeys) {
   const keySet = new Set(homeKeys);
   const tagOf = /* @__PURE__ */ new Map();
   for (const hk of homeKeys) tagOf.set(await routeTagHexOfHomeKey(hk), hk);
-  const out12 = /* @__PURE__ */ new Map();
-  for (const hk of homeKeys) out12.set(hk, 0);
+  const out13 = /* @__PURE__ */ new Map();
+  for (const hk of homeKeys) out13.set(hk, 0);
   for (const type of tenantTypes(eng)) {
     for (const r of query(eng, ws, "aggregatesByType", JSON.stringify({ __type: type }))) {
       const id = String(r.id || "");
       const hk = keySet.has(id) ? id : tagOf.get(routeTagHexOfMintedId(id) ?? "");
-      if (hk !== void 0) out12.set(hk, (out12.get(hk) ?? 0) + 1);
+      if (hk !== void 0) out13.set(hk, (out13.get(hk) ?? 0) + 1);
     }
   }
-  return out12;
+  return out13;
 }
 async function collectHomedIntents(eng, ws, homeKeys) {
   const routes = directiveRoutes(eng);
@@ -969,7 +970,7 @@ async function collectHomedIntents(eng, ws, homeKeys) {
       strikeParity.set(target, (strikeParity.get(target) ?? 0) + 1);
     }
   }
-  const out12 = [];
+  const out13 = [];
   for (const { oid, blob, doc } of docs) {
     const id = doc && typeof doc.id === "string" ? doc.id : null;
     if (!id || (strikeParity.get(id) ?? 0) % 2 === 1) continue;
@@ -985,9 +986,9 @@ async function collectHomedIntents(eng, ws, homeKeys) {
       const tag = routeTagHexOfMintedId(value);
       homeKey = tag !== void 0 ? tagOf.get(tag) ?? null : null;
     }
-    if (homeKey !== null) out12.push({ oid, id, homeKey, blob });
+    if (homeKey !== null) out13.push({ oid, id, homeKey, blob });
   }
-  return out12;
+  return out13;
 }
 async function migrateHomes(eng, ws, ledger, sourceWs, homeKeys, { onlyIds = null } = {}) {
   const wanted = onlyIds ? new Set(onlyIds) : null;
@@ -1096,7 +1097,7 @@ async function collectGlobalIntents(eng, ws) {
       strikeParity.set(target, (strikeParity.get(target) ?? 0) + 1);
     }
   }
-  const out12 = [];
+  const out13 = [];
   for (const { oid, blob, doc } of docs) {
     const id = doc && typeof doc.id === "string" ? doc.id : null;
     let touches = false;
@@ -1107,9 +1108,9 @@ async function collectGlobalIntents(eng, ws) {
       if (t !== void 0 && globals.has(t)) touches = true;
     }
     if (!touches || !id || (strikeParity.get(id) ?? 0) % 2 === 1) continue;
-    out12.push({ oid, id, blob });
+    out13.push({ oid, id, blob });
   }
-  return out12;
+  return out13;
 }
 async function replicateIntents(eng, ws, ledger, intents, { push = true } = {}) {
   const main2 = await mainIntentIds(eng, ws);
@@ -1382,8 +1383,8 @@ function writeWork(eng, name, bytes) {
   eng.preopen.dir.contents.set(name, new File(bytes));
 }
 function currentLaw(eng, ws) {
-  const out12 = JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "currentLaw" }), branch: BRANCH }, eng.STDERR));
-  return out12.keyMap || {};
+  const out13 = JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "currentLaw" }), branch: BRANCH }, eng.STDERR));
+  return out13.keyMap || {};
 }
 function installedLaw(eng, ws) {
   return JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "installedLaw" }), branch: BRANCH }, eng.STDERR));
@@ -1392,8 +1393,8 @@ function domainPackage(eng, ws, hash) {
   return JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "domainPackage", hash }), branch: BRANCH }, eng.STDERR));
 }
 function declaredCapabilities(eng, ws) {
-  const out12 = JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "declaredCapabilities" }), branch: BRANCH }, eng.STDERR));
-  return out12.capabilities || [];
+  const out13 = JSON.parse(call(eng.ex, "query", { repoArg: repoArgOf(ws), workspace: ws, queryBytes: b64Json({ op: "declaredCapabilities" }), branch: BRANCH }, eng.STDERR));
+  return out13.capabilities || [];
 }
 function reactorScan(eng, ws) {
   return JSON.parse(call(eng.ex, "outbox", { repoArg: repoArgOf(ws), branch: BRANCH }, eng.STDERR));
@@ -1494,13 +1495,13 @@ async function streamAll(stream) {
   }
   let len = 0;
   for (const c of chunks) len += c.length;
-  const out12 = new Uint8Array(len);
+  const out13 = new Uint8Array(len);
   let at = 0;
   for (const c of chunks) {
-    out12.set(c, at);
+    out13.set(c, at);
     at += c.length;
   }
-  return out12;
+  return out13;
 }
 async function gzip(bytes) {
   const cs = new CompressionStream("gzip");
@@ -2078,13 +2079,16 @@ async function admitAll(eng, ws, ledger, { receiptFence = null, shardRouting = n
       _projDone();
     }
   }
+  let unparkedSessions = /* @__PURE__ */ new Set();
   if (deadLetters.length) {
     try {
-      await materializeRefused(eng, ws, ledger, deadLetters);
+      unparkedSessions = (await materializeRefused(eng, ws, ledger, deadLetters)).unparkedSessions;
     } catch (e) {
+      unparkedSessions = new Set(deadLetters.map((dl) => dl.session).filter(Boolean));
       log("refused-materialize-failed", { ws, error: String(e).slice(0, 200) });
     }
   }
+  const prunable = unparkedSessions.size ? consumed.filter((c) => !unparkedSessions.has(c.cid)) : consumed;
   const hasCoordination = !!(summaryCtx || placements.length || splits.length || globalsOut.length);
   const deferDurability = defer && !hasCoordination;
   let _sealed = true;
@@ -2102,7 +2106,7 @@ async function admitAll(eng, ws, ledger, { receiptFence = null, shardRouting = n
     }
   }
   if (_sealed && !deferDurability) {
-    for (const { ref } of consumed) {
+    for (const { ref } of prunable) {
       try {
         await custodyPush(eng, ws, ledger, { remoteRef: ref, del: true });
       } catch {
@@ -2125,7 +2129,7 @@ async function admitAll(eng, ws, ledger, { receiptFence = null, shardRouting = n
     ...globalsOut.length ? { globals: globalsOut } : {},
     // The adapter's backup lane consumes these: `deferred` ⇒ resident main carries totalAdmitted
     // un-backed-up commits and `consumed` are the session branches to delete AFTER the push lands.
-    ...deferDurability && totalAdmitted ? { deferred: true, consumed, admitted: totalAdmitted } : {}
+    ...deferDurability && totalAdmitted ? { deferred: true, consumed: prunable, admitted: totalAdmitted } : {}
   };
 }
 async function backupHead(eng, ws, ledger, head) {
@@ -2308,11 +2312,23 @@ async function archiveRefusedMain(eng, ws, ledger, label) {
 async function writeRefusedRef(eng, ws, dl) {
   const gitdir = gitdirOf(ws);
   const blob = dl.blob instanceof Uint8Array ? dl.blob : enc3.encode(String(dl.blob || ""));
+  const refForStamp = refusedRefName(dl.intentId || dl.oid);
+  let parkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const prevOid = kgit.resolveRef(eng, gitdir, refForStamp);
+    if (prevOid) {
+      const prev = JSON.parse(dec3.decode(kgit.readBlob(eng, gitdir, prevOid, "verdict.json")));
+      if (prev && typeof prev.parkedAt === "string") parkedAt = prev.parkedAt;
+    }
+  } catch {
+  }
   const verdict = enc3.encode(JSON.stringify({
     offerId: dl.intentId || null,
     oid: dl.oid || null,
     domain: dl.domain || null,
     directiveId: dl.directiveId || null,
+    session: dl.session || null,
+    parkedAt,
     verdict: { reason: String(dl.error || "refused") }
   }));
   const ref = refusedRefName(dl.intentId || dl.oid);
@@ -2328,31 +2344,46 @@ async function writeRefusedRef(eng, ws, dl) {
 async function listRefusedRefs(eng, ws) {
   const gitdir = gitdirOf(ws);
   const refs = kgit.listRefs(eng, gitdir, "refs/heads/refused/");
-  const out12 = [];
+  const out13 = [];
   for (const { ref, oid } of refs) {
     try {
       const vb = kgit.readBlob(eng, gitdir, oid, "verdict.json");
       const ib = kgit.readBlob(eng, gitdir, oid, "intent.json");
       const v = JSON.parse(dec3.decode(vb));
-      out12.push({ ref, ...v, intentB64: b64Bytes(ib) });
+      out13.push({ ref, ...v, intentB64: b64Bytes(ib) });
     } catch {
     }
   }
-  return out12;
+  return out13;
 }
-async function materializeRefused(eng, ws, ledger, deadLetters) {
+async function refusedSummary(eng, ws) {
   const gitdir = gitdirOf(ws);
+  const refs = kgit.listRefs(eng, gitdir, "refs/heads/refused/");
+  let count2 = 0, latestParkedAt = null;
+  for (const { oid } of refs) {
+    try {
+      const v = JSON.parse(dec3.decode(kgit.readBlob(eng, gitdir, oid, "verdict.json")));
+      count2++;
+      if (v && typeof v.parkedAt === "string" && (!latestParkedAt || v.parkedAt > latestParkedAt)) latestParkedAt = v.parkedAt;
+    } catch {
+    }
+  }
+  return { count: count2, latestParkedAt };
+}
+async function materializeRefused(eng, ws, ledger, deadLetters) {
   const refs = [];
+  const unparkedSessions = /* @__PURE__ */ new Set();
   for (const dl of deadLetters || []) {
     try {
       const ref = await writeRefusedRef(eng, ws, dl);
       await custodyPush(eng, ws, ledger, { remoteRef: ref });
       refs.push(ref);
     } catch (e) {
+      if (dl && dl.session) unparkedSessions.add(dl.session);
       log("refused-ref-materialize-failed", { ws, intentId: dl?.intentId, error: String(e).slice(0, 200) });
     }
   }
-  return refs;
+  return { refs, unparkedSessions };
 }
 async function deleteRefusedRef(eng, ws, ledger, offerId) {
   const gitdir = gitdirOf(ws);
@@ -2501,9 +2532,9 @@ async function ledgerStats(eng, ws, ledger = null) {
   const mounted = eng.mounted.get(ws);
   if (mounted?.ledgerStats?.head === head) return mounted.ledgerStats;
   const commits = kgit.intentsAbove(eng, gitdir, head).length;
-  const out12 = { head, commits };
-  if (mounted) mounted.ledgerStats = out12;
-  return out12;
+  const out13 = { head, commits };
+  if (mounted) mounted.ledgerStats = out13;
+  return out13;
 }
 async function countRemoteCommits(eng, ledger) {
   const head = (await custodyLsRefs(ledger, "refs/heads/main"))["refs/heads/main"] || null;
@@ -2976,6 +3007,7 @@ var governance_exports = {};
 __export(governance_exports, {
   HONEST_CEILING: () => HONEST_CEILING,
   ROOT_CUSTODIAN_SECRET: () => ROOT_CUSTODIAN_SECRET,
+  STAGE_THRESHOLD_CHARS: () => STAGE_THRESHOLD_CHARS,
   buildCertificate: () => buildCertificate,
   buildRebirthPlan: () => buildRebirthPlan,
   certifyEra: () => certifyEra,
@@ -2996,6 +3028,7 @@ __export(governance_exports, {
   rebirthApply: () => rebirthApply,
   rebirthPlanCommand: () => rebirthPlanCommand,
   rebirthWorkspace: () => rebirthWorkspace,
+  relaySealedOfferViaStage: () => relaySealedOfferViaStage,
   renderRebirthImpact: () => renderRebirthImpact,
   resolveGovernanceHash: () => resolveGovernanceHash,
   resolveGovernancePrincipal: () => resolveGovernancePrincipal,
@@ -3055,9 +3088,41 @@ async function signAndPostOffer(ws, domain, directiveId, payload, opts) {
     authorSecret: device.secret,
     actor: `user:${principal}`
   });
+  if (sealed.intentBytes.length > STAGE_THRESHOLD_CHARS) {
+    const staged = await relaySealedOfferViaStage(cloud, ws, directiveId, sealed.intentBytes, fetch);
+    if (staged !== null) {
+      out2(`  staged ${staged.size} sealed bytes content-addressed (sha256 ${staged.sha256.slice(0, 16)}\u2026) \u2014 the signed offer names the hash`);
+      return { ...staged.verdict, principal };
+    }
+    err2(`this cloud has no /v2/stage content-addressed lane \u2014 relaying the ${sealed.intentBytes.length}-char sealed offer inline (a 413 here means the worker needs upgrading to accept law this large signed)`);
+  }
   const verdict = await holon.postGovernanceOffer({ directiveId, intentBytes: sealed.intentBytes, ws });
   return { ...verdict, principal };
 }
+async function relaySealedOfferViaStage(cloud, ws, directiveId, intentBytesB64, fetchImpl) {
+  const raw = Buffer.from(intentBytesB64, "base64");
+  const sha2562 = createHash("sha256").update(raw).digest("hex");
+  let put;
+  try {
+    put = await fetchImpl(`${cloud}/v2/stage/${sha2562}`, { method: "PUT", body: raw });
+  } catch {
+    return null;
+  }
+  if (!put.ok) return null;
+  const r = await fetchImpl(`${cloud}/v2/workspaces/${ws}/${directiveId}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ intentRef: { sha256: sha2562, size: raw.length } })
+  });
+  const text = await r.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { sha256: sha2562, size: raw.length, verdict: { ok: r.ok, status: r.status, body } };
+}
 async function signAndPostGovernance(parent, directiveId, payload, opts) {
   return signAndPostOffer(parent, "workspaces", directiveId, payload, opts);
 }
@@ -4273,13 +4338,14 @@ function readSealedIntentBytes(eng, ws, intentOut) {
   if (f?.data === void 0) return void 0;
   return Buffer.from(f.data).toString("base64");
 }
-var out2, err2, HONEST_CEILING, ROOT_CUSTODIAN_SECRET, CLIENT_IMPACT;
+var out2, err2, STAGE_THRESHOLD_CHARS, HONEST_CEILING, ROOT_CUSTODIAN_SECRET, CLIENT_IMPACT;
 var init_governance = __esm({
   "src/governance.ts"() {
     "use strict";
     init_cloud();
     out2 = (s) => void process.stdout.write(s + "\n");
     err2 = (s) => void process.stderr.write("error: " + s + "\n");
+    STAGE_THRESHOLD_CHARS = 4 * 1024 * 1024;
     HONEST_CEILING = `The operator controls root's law and could deploy law removing the consent check \u2014 but that act is itself a signed, ordered, permanent fact in root's chain, visible to every tenant running \`replay root\`, and grounds for exit-with-everything. Not "we can't" \u2014 "we can't secretly, and you can always leave."`;
     ROOT_CUSTODIAN_SECRET = "nomos-root-custodian-key";
     CLIENT_IMPACT = "every connected client raises CustodyBreak(superseded); unsynced client work is invisible to the cloud \u2014 drain/sync clients first";
@@ -6582,11 +6648,11 @@ function bareTypeLabel(t) {
   return i > 0 && i < t.length - 1 ? t.slice(i + 1) : t;
 }
 function geoFieldsOfInstalls(installs) {
-  const out12 = /* @__PURE__ */ new Map();
+  const out13 = /* @__PURE__ */ new Map();
   const add2 = (type, field) => {
-    const set = out12.get(type) ?? /* @__PURE__ */ new Set();
+    const set = out13.get(type) ?? /* @__PURE__ */ new Set();
     set.add(field);
-    out12.set(type, set);
+    out13.set(type, set);
   };
   for (const inst of installs) {
     for (const layer of inst.layers) {
@@ -6602,7 +6668,7 @@ function geoFieldsOfInstalls(installs) {
       }
     }
   }
-  return out12;
+  return out13;
 }
 function pointOfOpValue(setOp) {
   let v = setOp["Json"];
@@ -7360,6 +7426,65 @@ var init_scene = __esm({
   }
 });
 
+// src/dlq.ts
+var dlq_exports = {};
+__export(dlq_exports, {
+  dlqSweep: () => dlqSweep,
+  renderSweepNode: () => renderSweepNode
+});
+function renderSweepNode(n, indent = "") {
+  const jammed = n.dlqCount > 0;
+  const badge = n.error !== void 0 ? "?" : jammed ? "\u2717" : "\u2713";
+  const detail = n.error !== void 0 ? `unreachable: ${n.error}` : jammed ? `${n.dlqCount} dead-letter${n.dlqCount === 1 ? "" : "s"} (latest ${n.latestParkedAt ?? "unknown"})` : "clean";
+  const lines = [`${indent}${badge} ${n.workspace} \u2014 ${detail}`];
+  for (const dl of n.deadLetters ?? []) {
+    lines.push(`${indent}    \xB7 ${dl.domain ?? "?"}/${dl.directiveId ?? "?"} [${dl.intentId ?? "?"}] ${String(dl.error ?? "").slice(0, 100)}`);
+  }
+  for (const c of n.children ?? []) lines.push(...renderSweepNode(c, indent + "  "));
+  if (n.truncatedChildren) lines.push(`${indent}  \u2026 ${n.truncatedChildren} more child(ren) truncated \u2014 raise ?limit or sweep a subtree`);
+  return lines;
+}
+async function dlqSweep(ws, opts = {}) {
+  const cloud = cloudBase(opts.cloud);
+  const q = new URLSearchParams();
+  if (opts.depth !== void 0) q.set("depth", String(opts.depth));
+  if (opts.full === true) q.set("full", "1");
+  const url = `${cloud}/v2/workspaces/${encodeURIComponent(ws)}/dlq-sweep${q.size ? `?${q}` : ""}`;
+  let body;
+  try {
+    const res = await fetch(url);
+    body = await res.json();
+    if (body.ok !== true || body.root === void 0) {
+      err12(`dlq sweep refused: ${String(body.error ?? "no sweep in the response").slice(0, 300)}`);
+      return 1;
+    }
+  } catch (e) {
+    err12(`dlq sweep failed against ${cloud}: ${e.message}`);
+    return 1;
+  }
+  if (opts.json === true) {
+    out12(JSON.stringify(body, null, 2));
+    return body.jammed ? 2 : 0;
+  }
+  out12(`DLQ sweep of '${ws}' \u2014 ${body.nodes} node(s), ${body.jammed} jammed`);
+  for (const line of renderSweepNode(body.root)) out12(line);
+  if (body.jammed) {
+    out12("");
+    out12("unjam: fix/deploy the law on the jammed workspace, then POST /v2/workspaces/<node>/dead-letters/retry");
+    out12("       (or from the app: holon.retryDeadLetter(id); discard is the app's explicit choice)");
+  }
+  return body.jammed ? 2 : 0;
+}
+var out12, err12;
+var init_dlq = __esm({
+  "src/dlq.ts"() {
+    "use strict";
+    init_cloud();
+    out12 = (s) => void process.stdout.write(s + "\n");
+    err12 = (s) => void process.stderr.write("error: " + s + "\n");
+  }
+});
+
 // src/cli.ts
 import { existsSync as existsSync14, readdirSync as readdirSync5, readFileSync as readFileSync14 } from "node:fs";
 import { spawnSync as spawnSync6 } from "node:child_process";
@@ -8078,6 +8203,18 @@ var HELP = {
     ],
     examples: ["githolon status", "githolon status my-guestbook", "githolon status --target prod"]
   },
+  dlq: {
+    usage: "githolon dlq sweep <workspace> [--depth <n>] [--full] [--json] [--cloud <url>]",
+    what: "THE FLEET/SUBTREE DLQ SWEEP (architecture/operator_dlq_sweep.md): one look across a platform's\ndead-letter queues. The cloud enumerates the subtree via the REGISTRY (the maintained\nworkspacesByParent projection index \u2014 never a chain walk), reads each node's O(1) DLQ summary\n({count, latestParkedAt}) and prints the tree; jammed nodes carry their parked entries under\n--full. Read-only; the unjam stays POST /v2/workspaces/<node>/dead-letters/retry after the law\nfix. Exit codes: 0 all clean \xB7 2 jams found \xB7 1 error.",
+    flags: [
+      ["<workspace>", "the subtree root \u2014 a platform, or any workspace (a non-governance node is a leaf)"],
+      ["--depth <n>", "recursion depth (default 2, max 4; 1 = the node alone)"],
+      ["--full", "include the parked entries for jammed nodes (clean nodes never pay a fetch)"],
+      ["--json", "the raw sweep tree, machine-consumable"],
+      ["--cloud <url>", "target cloud (default: $NOMOS_CLOUD or the public cloud)"]
+    ],
+    examples: ["githolon dlq sweep co2-platform", "githolon dlq sweep co2-platform --depth 3 --full", "githolon dlq sweep my-ws --json"]
+  },
   compat: {
     usage: "githolon compat <ws-url | deploy.json | interface.json | dir> [--config <cfg>] [--workspace <ws>] [--json]",
     what: "THE CI GATE (the compat superpower): compare the CURRENT build's structural interface\n(build/<name>.interface.json \u2014 run `githolon compile` first) against a TARGET's installed law,\nPER MEMBER via #72 subtyping. Exits NON-ZERO on any incompatible member, so a client/law\nmismatch is caught before it ships. Target: a deploy.json (its staged .interface is the offer),\nan .interface.json / build dir, or a LIVE workspace URL (connect()s + reads the on-ledger offer).",
@@ -8374,9 +8511,9 @@ function capJsonStrings(v, max = 2048) {
   if (typeof v === "string") return v.length > max ? `${v.slice(0, max)}\u2026(${v.length} chars)` : v;
   if (Array.isArray(v)) return v.map((x) => capJsonStrings(x, max));
   if (typeof v === "object" && v !== null) {
-    const out12 = {};
-    for (const [k, x] of Object.entries(v)) out12[k] = capJsonStrings(x, max);
-    return out12;
+    const out13 = {};
+    for (const [k, x] of Object.entries(v)) out13[k] = capJsonStrings(x, max);
+    return out13;
   }
   return v;
 }
@@ -8834,6 +8971,8 @@ deploy is OPEN + kernel-gated \u2014 births return no host secret, ownership is
             [--explain-current-interface]                lineage (active = served now)
   githolon domains retire <ws> <hashOrKey>                retire an install (marks it retired \u2014 replayable,
             [--with <hashOrKey>]                          no longer served) via a signed installDomain offer
+  githolon dlq sweep <ws> [--depth <n>] [--full]          sweep a platform subtree's dead-letter queues
+                                                       (registry-enumerated; exit 2 when jams exist)
   githolon secret set <ws> <push-password>                store a git push password (push-to-create birth lane)
   githolon secret rotate <ws>                             RETIRED \u2014 host holds no ownership credential (410)
 
@@ -8858,8 +8997,8 @@ Options:
 function cloudArgs(rest) {
   const pos = [];
   const opts = {};
-  const VALUE_FLAGS = ["--cloud", "--principal", "--as", "--file", "--target", "--parent", "--via", "--max", "--label", "--secret", "--payload", "--payload-file", "--save", "--format", "--with", "--out", "--reason", "--oid", "--seed-secret", "--gcp-secret", "--controller-hash", "--plan"];
-  const BOOL_FLAGS = ["--sha256", "--stamp", "--yes", "--clear", "--keep-beside", "--retire-replaced", "--explain-current-interface", "--dry-run", "--json"];
+  const VALUE_FLAGS = ["--cloud", "--principal", "--as", "--file", "--target", "--parent", "--via", "--max", "--label", "--secret", "--payload", "--payload-file", "--save", "--format", "--with", "--out", "--reason", "--oid", "--seed-secret", "--gcp-secret", "--controller-hash", "--plan", "--depth"];
+  const BOOL_FLAGS = ["--sha256", "--stamp", "--yes", "--clear", "--keep-beside", "--retire-replaced", "--explain-current-interface", "--dry-run", "--json", "--full"];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (BOOL_FLAGS.includes(a)) {
@@ -8871,6 +9010,7 @@ function cloudArgs(rest) {
       else if (a === "--explain-current-interface") opts.explain = true;
       else if (a === "--dry-run") opts.dryRun = true;
       else if (a === "--json") opts.json = true;
+      else if (a === "--full") opts.full = true;
       else opts.yes = true;
     } else if (VALUE_FLAGS.includes(a)) {
       const v = rest[++i];
@@ -8892,6 +9032,10 @@ function cloudArgs(rest) {
         const n = Number(v);
         if (!Number.isInteger(n) || n <= 0) return { pos, opts, bad: `--max requires a positive integer` };
         opts.max = n;
+      } else if (a === "--depth") {
+        const n = Number(v);
+        if (!Number.isInteger(n) || n <= 0) return { pos, opts, bad: `--depth requires a positive integer` };
+        opts.depth = n;
       } else opts.file = v;
     } else if (a.startsWith("--")) {
       return { pos, opts, bad: `unknown flag '${a}'` };
@@ -9155,10 +9299,10 @@ async function main(argv) {
     };
     const deployArg = pull("--deploy");
     const workspace = pull("--workspace") ?? "test-ws";
-    const out12 = pull("--out");
+    const out13 = pull("--out");
     const runtime = pull("--runtime");
     const deploy3 = (deployArg ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-    if (deploy3.length === 0 || out12 === void 0) {
+    if (deploy3.length === 0 || out13 === void 0) {
       process.stderr.write(
         `error: usage: githolon harness-install --deploy <deploy.json[,deploy.json...]> --workspace <ws> --out <snapshotPath> [--runtime <dir>]
 `
@@ -9166,7 +9310,7 @@ async function main(argv) {
       return 1;
     }
     const { harnessInstall: harnessInstall2 } = await Promise.resolve().then(() => (init_harness(), harness_exports));
-    return harnessInstall2({ deploy: deploy3, workspace, out: out12, ...runtime !== void 0 ? { runtime } : {} });
+    return harnessInstall2({ deploy: deploy3, workspace, out: out13, ...runtime !== void 0 ? { runtime } : {} });
   }
   if (argv[0] === "dev") {
     const rest = argv.slice(1);
@@ -9300,6 +9444,24 @@ ${commandHelp("status")}`);
   if (argv[0] === "ws" || argv[0] === "deploy" || argv[0] === "secret") {
     return runCloud(argv);
   }
+  if (argv[0] === "dlq") {
+    const { dlqSweep: dlqSweep2 } = await Promise.resolve().then(() => (init_dlq(), dlq_exports));
+    const { pos, opts, bad } = cloudArgs(argv.slice(1));
+    if (bad !== void 0) {
+      process.stderr.write(`error: ${bad}
+
+${commandHelp("dlq") ?? USAGE}`);
+      return 1;
+    }
+    const [sub2, ws] = pos;
+    if (sub2 !== "sweep" || ws === void 0) {
+      process.stderr.write(`error: expected: githolon dlq sweep <workspace> [--depth <n>] [--full] [--json]
+
+${commandHelp("dlq") ?? USAGE}`);
+      return 1;
+    }
+    return dlqSweep2(ws, opts);
+  }
   if (argv[0] === "domains") {
     const { domainsRetire: domainsRetire2, domainsStatus: domainsStatus2 } = await Promise.resolve().then(() => (init_lifecycle(), lifecycle_exports));
     const { pos, opts, bad } = cloudArgs(argv.slice(1));
@@ -9626,8 +9788,8 @@ ${USAGE}`);
   let parsed;
   try {
     parsed = parseArgs(argv);
-  } catch (err12) {
-    process.stderr.write(`error: ${err12.message}
+  } catch (err13) {
+    process.stderr.write(`error: ${err13.message}
 
 ${USAGE}`);
     return 1;
@@ -9646,8 +9808,8 @@ ${USAGE}`);
     process.stdout.write(`created ${path}
 `);
     return 0;
-  } catch (err12) {
-    process.stderr.write(`error: ${err12.message}
+  } catch (err13) {
+    process.stderr.write(`error: ${err13.message}
 `);
     return 1;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "githolon",
-  "version": "0.74.0",
+  "version": "0.75.1",
   "type": "module",
   "description": "githolon — the Nomos developer CLI: Rails-style generators for @githolon/dsl domains + the package compiler. Kernel-independent.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "0.4.2",
-    "@githolon/client": "^0.74.0",
-    "@githolon/dsl": "^0.74.0",
+    "@githolon/client": "^0.75.1",
+    "@githolon/dsl": "^0.75.1",
     "isomorphic-git": "^1.38.4"
   },
   "devDependencies": {