githolon 0.31.1 → 0.32.0

package/dist/cli.mjs

@@ -348,6 +348,282 @@ var init_governance = __esm({
   }
 });
 
+// src/lifecycle.ts
+var lifecycle_exports = {};
+__export(lifecycle_exports, {
+  describeDeployPlan: () => describeDeployPlan,
+  domainKeysOf: () => domainKeysOf,
+  domainsRetire: () => domainsRetire,
+  domainsStatus: () => domainsStatus,
+  fetchInstalledLaw: () => fetchInstalledLaw,
+  fetchInstalledPackage: () => fetchInstalledPackage,
+  keysServedBy: () => keysServedBy,
+  packageHashOf: () => packageHashOf,
+  readDeployBody: () => readDeployBody,
+  resolveDeployPlan: () => resolveDeployPlan,
+  resolveInstallHash: () => resolveInstallHash,
+  signingAvailable: () => signingAvailable
+});
+import { createHash as createHash2 } from "node:crypto";
+import { readFileSync as readFileSync2 } from "node:fs";
+async function fetchInstalledLaw(cloud, ws) {
+  try {
+    const r = await fetch(`${cloud}/v2/workspaces/${ws}/domains`);
+    const d = await r.json().catch(() => void 0);
+    return d?.ok === true ? d : {};
+  } catch {
+    return {};
+  }
+}
+async function fetchInstalledPackage(cloud, ws, hash) {
+  try {
+    const r = await fetch(`${cloud}/v2/workspaces/${ws}/domains/${hash}/package.usda`);
+    if (!r.ok) return void 0;
+    const text = await r.text();
+    return text.length > 0 ? text : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readDeployBody(file) {
+  let body;
+  try {
+    body = JSON.parse(readFileSync2(file, "utf8"));
+  } catch (e) {
+    throw new Error(`deploy body ${file} is not valid JSON \u2014 recompile (githolon compile): ${e.message}`);
+  }
+  if (typeof body.packageUsda !== "string" || body.packageUsda === "") {
+    throw new Error(`deploy body ${file} is missing packageUsda \u2014 run \`githolon compile\` again`);
+  }
+  return body;
+}
+function domainKeysOf(body) {
+  return (body.summary?.domains ?? []).map((d) => d.domain).filter((k) => typeof k === "string" && k !== "");
+}
+function packageHashOf(packageUsda) {
+  return createHash2("sha256").update(Buffer.from(packageUsda, "utf8")).digest("hex");
+}
+function resolveDeployPlan(domainKeys, currentLaw, targetHash, opts = {}) {
+  const decisions = [];
+  const priors = /* @__PURE__ */ new Set();
+  for (const key of domainKeys) {
+    const currentHash = currentLaw[key];
+    if (currentHash === void 0) {
+      decisions.push({ key, action: "first" });
+    } else if (currentHash === targetHash) {
+      decisions.push({ key, currentHash, action: "idempotent" });
+    } else if (opts.keepBeside === true) {
+      decisions.push({ key, currentHash, action: "keep-beside" });
+    } else {
+      decisions.push({ key, currentHash, action: "supersedes" });
+      priors.add(currentHash);
+    }
+  }
+  const replaceCandidates = [...priors];
+  const idempotent = domainKeys.length > 0 && decisions.every((d) => d.action === "idempotent");
+  return {
+    decisions,
+    ...replaceCandidates.length > 0 ? { replaces: replaceCandidates[0] } : {},
+    retireReplaced: opts.retireReplaced === true,
+    idempotent,
+    replaceCandidates
+  };
+}
+function describeDeployPlan(plan, targetHash) {
+  const t = short(targetHash);
+  return plan.decisions.map((d) => {
+    switch (d.action) {
+      case "first":
+        return `  ${d.key}: ${t} installed (first)`;
+      case "supersedes":
+        return `  ${d.key}: ${t} supersedes ${short(d.currentHash)}${plan.retireReplaced ? " (retired)" : ""}`;
+      case "keep-beside":
+        return `  ${d.key}: ${t} kept beside ${short(d.currentHash)}`;
+      case "idempotent":
+        return `  ${d.key}: unchanged \u2014 ${t} is already the current served law`;
+    }
+  });
+}
+function resolveInstallHash(arg, currentLaw) {
+  if (/^[0-9a-f]{64}$/.test(arg)) return { hash: arg };
+  const hash = currentLaw[arg];
+  if (hash !== void 0) return { hash };
+  const keys = Object.keys(currentLaw);
+  return {
+    error: `'${arg}' is neither a 64-hex install hash nor a served domain key` + (keys.length > 0 ? ` (served keys: ${keys.join(", ")})` : " (this workspace serves no law)")
+  };
+}
+function keysServedBy(hash, currentLaw) {
+  return Object.keys(currentLaw).filter((k) => currentLaw[k] === hash);
+}
+async function domainsRetire(ws, target, opts) {
+  const cloud = cloudBase(opts.cloud);
+  const law = await fetchInstalledLaw(cloud, ws);
+  const currentLaw = law.currentLaw ?? {};
+  const resolved = resolveInstallHash(target, currentLaw);
+  if ("error" in resolved) {
+    err2(resolved.error);
+    return 1;
+  }
+  const retireHash = resolved.hash;
+  const installed = (law.domains ?? []).find((r) => r.domainHash === retireHash);
+  if (installed === void 0) {
+    err2(`no install '${short(retireHash)}' on ${ws} \u2014 GET /v2/workspaces/${ws}/domains lists the installed hashes`);
+    return 1;
+  }
+  let successorHash;
+  let successorUsda;
+  let successorSource;
+  if (opts.with !== void 0) {
+    const wResolved = resolveInstallHash(opts.with, currentLaw);
+    if ("error" in wResolved) {
+      err2(`--with ${wResolved.error}`);
+      return 1;
+    }
+    successorHash = wResolved.hash;
+    const bytes = await fetchInstalledPackage(cloud, ws, successorHash);
+    if (bytes === void 0) {
+      err2(`--with package '${short(successorHash)}' is not installed on ${ws} (its bytes could not be fetched)`);
+      return 1;
+    }
+    successorUsda = bytes;
+    successorSource = `installed package ${short(successorHash)}`;
+  } else {
+    let file;
+    try {
+      file = discoverDeployJson(process.cwd(), opts.file);
+    } catch (e) {
+      err2(`${e.message}
+  (or name an installed successor: githolon domains retire ${ws} ${target} --with <hashOrKey>)`);
+      return 1;
+    }
+    let body;
+    try {
+      body = readDeployBody(file);
+    } catch (e) {
+      err2(e.message);
+      return 1;
+    }
+    successorUsda = body.packageUsda;
+    successorHash = packageHashOf(successorUsda);
+    successorSource = `local package ${file.split("/").pop()} (${short(successorHash)})`;
+  }
+  if (successorHash === retireHash) {
+    err2(
+      `refusing to retire '${short(retireHash)}' with ITSELF as the successor \u2014 the framework has no standalone
+  retire-to-empty directive (retirement is the consequence of installing a different successor).
+  Name a different successor with --with <hashOrKey>, or deploy new law that supersedes it.`
+    );
+    return 1;
+  }
+  const retiredKeys = keysServedBy(retireHash, currentLaw);
+  const successorKeys = new Set(keysServedBy(successorHash, currentLaw));
+  const stranded = retiredKeys.filter((k) => !successorKeys.has(k));
+  const { signAndPostOffer: signAndPostOffer2, resolveGovernancePrincipal: resolveGovernancePrincipal2 } = await Promise.resolve().then(() => (init_governance(), governance_exports));
+  let v;
+  try {
+    const who = resolveGovernancePrincipal2(opts);
+    const installPayload2 = {
+      domainHash: successorHash,
+      packageUsda: successorUsda,
+      installedBy: `user:${who}`,
+      dependencies: [],
+      finalizers: [],
+      replaces: retireHash,
+      retireReplaced: true
+    };
+    v = await signAndPostOffer2(ws, "nomos", "installDomain", installPayload2, opts);
+  } catch (e) {
+    err2(e.message);
+    return 1;
+  }
+  if (!v.ok) {
+    err2(`retire '${short(retireHash)}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+    if (v.status === 401 || v.status === 403 || v.status === 422) {
+      err2(`  installing law is kernel-judged \u2014 retire as an authorized principal: --as <uid> (import its key: githolon key import)`);
+    }
+    return 1;
+  }
+  out2(`\u2713 retired ${short(retireHash)} on ${ws} (marked Retired \u2014 replayable, no longer served)`);
+  out2(`  successor: ${successorSource}`);
+  const after = await fetchInstalledLaw(cloud, ws);
+  const afterLaw = after.currentLaw ?? {};
+  for (const k of retiredKeys) {
+    const now = afterLaw[k];
+    out2(`  key '${k}' now serves: ${now !== void 0 ? short(now) : "NO served law"}`);
+  }
+  if (stranded.length > 0 && retiredKeys.some((k) => afterLaw[k] === void 0)) {
+    err2(`\u26A0 retiring left these keys with NO served law: ${stranded.join(", ")} \u2014 nothing dispatches/reads them now`);
+    err2(`  (deploy law covering them, or this is intentional \u2014 the kernel allows an unserved key)`);
+  }
+  return 0;
+}
+async function domainsStatus(ws, opts) {
+  const cloud = cloudBase(opts.cloud);
+  const law = await fetchInstalledLaw(cloud, ws);
+  if (law.ok === false || law.domains === void 0 && law.currentLaw === void 0) {
+    err2(`no installed-law report for ${ws} on ${cloud} (unborn, or the workspace did not answer)`);
+    return 1;
+  }
+  const currentLaw = law.currentLaw ?? {};
+  const rows = law.domains ?? [];
+  const phaseOf = (hash) => rows.find((r) => r.domainHash === hash)?.phase ?? "(unknown)";
+  const keys = Object.keys(currentLaw).sort();
+  out2(`installed law on ${ws} (${cloud})`);
+  if (keys.length === 0) {
+    out2(`  (no domain key resolves a served law \u2014 nothing is dispatched/read here)`);
+  } else {
+    out2(`current interface \u2014 the served law per domain key (the frontier):`);
+    for (const key of keys) {
+      const hash = currentLaw[key];
+      out2(`  ${key}  \u2192  ${short(hash)}  [${phaseOf(hash)}]`);
+    }
+  }
+  const servedHashes = new Set(Object.values(currentLaw));
+  const behind = rows.filter((r) => typeof r.domainHash === "string" && !servedHashes.has(r.domainHash));
+  if (behind.length > 0) {
+    out2(`superseded / retired lineage (replayable, NEVER served):`);
+    for (const r of behind) {
+      out2(`  ${short(r.domainHash)}  [${r.phase ?? "(unknown)"}]${r.generation !== void 0 ? `  gen ${r.generation}` : ""}`);
+    }
+  } else if (rows.length > 0) {
+    out2(`no superseded/retired installs behind the frontier \u2014 every install is current`);
+  }
+  if (opts.explain === true) {
+    out2(``);
+    out2(`why this is the current interface (the frontier resolution):`);
+    out2(`  the holon resolves, per domain key, the NEWEST '${SERVED_PHASE}' install that is not superseded/`);
+    out2(`  retired (refresh_key_map / rpc_current_law). Every live surface \u2014 the interface identity, reads,`);
+    out2(`  and dispatch \u2014 reads from THIS map, so a superseded/retired install can never pollute it.`);
+    for (const key of keys) {
+      const hash = currentLaw[key];
+      out2(`  \u2022 '${key}' serves ${short(hash)} \u2014 it is the newest ${SERVED_PHASE} install for this key.`);
+    }
+    if (behind.length > 0) {
+      const excluded = behind.filter((r) => EXCLUDED_PHASES.has(r.phase ?? "") || !servedHashes.has(r.domainHash)).map((r) => `${short(r.domainHash)} [${r.phase ?? "?"}]`);
+      out2(`  \u2022 excluded from the interface (replayable, not served): ${excluded.join(", ")}`);
+    }
+    out2(`  interface identity per key = the current served hash above; older installs are lineage, not surface.`);
+  }
+  return 0;
+}
+function signingAvailable(opts) {
+  const principal = opts.principal ?? activePrincipal();
+  return opts.principal !== void 0 || principal !== void 0 && getDeviceKey(principal) !== void 0;
+}
+var out2, err2, short, SERVED_PHASE, EXCLUDED_PHASES;
+var init_lifecycle = __esm({
+  "src/lifecycle.ts"() {
+    "use strict";
+    init_cloud();
+    out2 = (s) => void process.stdout.write(s + "\n");
+    err2 = (s) => void process.stderr.write("error: " + s + "\n");
+    short = (h) => h.length > 16 ? h.slice(0, 16) + "\u2026" : h;
+    SERVED_PHASE = "Active";
+    EXCLUDED_PHASES = /* @__PURE__ */ new Set(["Superseded", "Retired", "Disabled", "Failed", "Pending", "Retiring"]);
+  }
+});
+
 // src/cloud.ts
 var cloud_exports = {};
 __export(cloud_exports, {
@@ -379,8 +655,8 @@ __export(cloud_exports, {
   wsRetire: () => wsRetire,
   wsStatus: () => wsStatus
 });
-import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { createHash as createHash2 } from "node:crypto";
+import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { createHash as createHash3 } from "node:crypto";
 import { join as join2 } from "node:path";
 import { homedir } from "node:os";
 function cloudBase(flag) {
@@ -400,7 +676,7 @@ function credsPath() {
 }
 function loadCreds() {
   if (!existsSync2(credsPath())) return { version: 1, secrets: {} };
-  return JSON.parse(readFileSync2(credsPath(), "utf8"));
+  return JSON.parse(readFileSync3(credsPath(), "utf8"));
 }
 function saveCreds(c) {
   mkdirSync2(configDir(), { recursive: true });
@@ -440,24 +716,24 @@ function clearActAs() {
 async function authUse(principal, opts = {}) {
   if (opts.clear === true) {
     clearActAs();
-    out2("\u2713 cleared the active signing principal \u2014 signed lanes fall back to the session / bare default");
+    out3("\u2713 cleared the active signing principal \u2014 signed lanes fall back to the session / bare default");
     return 0;
   }
   if (principal === void 0) {
     const c = loadCreds();
     const active = c.actAs;
-    out2(active !== void 0 ? `acting as  ${active}${getDeviceKey(active) ? "  (key on file \u2713)" : "  \u26A0 no signing key \u2014 githolon key import --principal " + active}` : "no active signing principal set (githolon use <uid>) \u2014 signed lanes use the session / bare default");
+    out3(active !== void 0 ? `acting as  ${active}${getDeviceKey(active) ? "  (key on file \u2713)" : "  \u26A0 no signing key \u2014 githolon key import --principal " + active}` : "no active signing principal set (githolon use <uid>) \u2014 signed lanes use the session / bare default");
     const keyed = Object.keys(c.devices ?? {});
     if (keyed.length > 0) {
-      out2(`keys on file:`);
-      for (const p of keyed) out2(`  ${p}${p === active ? "  \u2190 active" : ""}`);
+      out3(`keys on file:`);
+      for (const p of keyed) out3(`  ${p}${p === active ? "  \u2190 active" : ""}`);
     }
     return 0;
   }
   setActAs(principal);
-  out2(`\u2713 now acting as ${principal} (signed deploy/gov/grant/key author as this principal)`);
+  out3(`\u2713 now acting as ${principal} (signed deploy/gov/grant/key author as this principal)`);
   if (getDeviceKey(principal) === void 0) {
-    out2(`  \u26A0 no signing key on file for ${principal} yet \u2014 import it: githolon key import --principal ${principal} --secret <key>`);
+    out3(`  \u26A0 no signing key on file for ${principal} yet \u2014 import it: githolon key import --principal ${principal} --secret <key>`);
   }
   return 0;
 }
@@ -530,7 +806,7 @@ function discoverDeployJson(cwd, explicit) {
 }
 async function login(opts) {
   if (opts.agent !== true && opts.token === void 0) {
-    err2(
+    err3(
       "browser login is not wired up yet \u2014 use one of:\n  githolon login --agent             anonymous sign-in (verified identity, linkable later)\n  githolon login --token <refresh>   adopt an existing captain app session"
     );
     return 1;
@@ -538,33 +814,33 @@ async function login(opts) {
   const d = opts.agent === true ? await gotrue("/auth/v1/signup", "{}") : await gotrue("/auth/v1/token?grant_type=refresh_token", JSON.stringify({ refresh_token: opts.token }));
   const s = sessionFromGotrue(d);
   if (s === void 0) {
-    err2(`login failed: ${d.error_description ?? d.error ?? d.msg ?? JSON.stringify(d)}`);
+    err3(`login failed: ${d.error_description ?? d.error ?? d.msg ?? JSON.stringify(d)}`);
     return 1;
   }
   saveSession(s);
-  out2(`\u2713 logged in${s.anonymous ? " (anonymous agent identity \u2014 linkable to a full account later)" : ""}`);
-  out2(`  principal uid ${s.uid}`);
-  out2(`  session saved \u2192 ${credsPath()} (auto-refreshed; births now ride x-nomos-auth)`);
+  out3(`\u2713 logged in${s.anonymous ? " (anonymous agent identity \u2014 linkable to a full account later)" : ""}`);
+  out3(`  principal uid ${s.uid}`);
+  out3(`  session saved \u2192 ${credsPath()} (auto-refreshed; births now ride x-nomos-auth)`);
   return 0;
 }
 async function whoami() {
   const c = loadCreds();
   if (c.session !== void 0) {
-    out2(`session: ${c.session.anonymous ? "anonymous agent" : "account"} uid ${c.session.uid} (auth ${c.session.url})`);
+    out3(`session: ${c.session.anonymous ? "anonymous agent" : "account"} uid ${c.session.uid} (auth ${c.session.url})`);
   } else if (c.principal !== void 0) {
-    out2(`bare principal (transitional, unverified): ${c.principal}`);
+    out3(`bare principal (transitional, unverified): ${c.principal}`);
   } else {
-    out2("not logged in \u2014 githolon login --agent, or pass --principal <uid> per birth");
+    out3("not logged in \u2014 githolon login --agent, or pass --principal <uid> per birth");
   }
   const active = activePrincipal();
   if (c.actAs !== void 0) {
-    out2(`acting as: ${c.actAs}${getDeviceKey(c.actAs) ? " (key on file \u2713)" : " \u26A0 no signing key"}  [githolon use <uid> to switch]`);
+    out3(`acting as: ${c.actAs}${getDeviceKey(c.actAs) ? " (key on file \u2713)" : " \u26A0 no signing key"}  [githolon use <uid> to switch]`);
   } else if (active !== void 0) {
-    out2(`signed lanes act as: ${active} (the session/bare default \u2014 githolon use <uid> to switch)`);
+    out3(`signed lanes act as: ${active} (the session/bare default \u2014 githolon use <uid> to switch)`);
   }
   const keyed = Object.keys(c.devices ?? {});
   if (keyed.length > 0) {
-    out2(`signing keys on file: ${keyed.map((p) => p === active ? `${p} \u2190active` : p).join(", ")}`);
+    out3(`signing keys on file: ${keyed.map((p) => p === active ? `${p} \u2190active` : p).join(", ")}`);
   }
   return 0;
 }
@@ -572,7 +848,7 @@ async function logout() {
   const c = loadCreds();
   delete c.session;
   saveCreds(c);
-  out2("\u2713 session cleared (stored workspace secrets kept)");
+  out3("\u2713 session cleared (stored workspace secrets kept)");
   return 0;
 }
 async function wsCreate(name, opts) {
@@ -589,24 +865,24 @@ async function wsCreate(name, opts) {
         opts
       );
     } catch (e) {
-      err2(e.message);
+      err3(e.message);
       return 1;
     }
     if (!v.ok) {
-      err2(`createWorkspace '${name}' refused (${v.status}) at ${opts.via}: ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+      err3(`createWorkspace '${name}' refused (${v.status}) at ${opts.via}: ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
       return 1;
     }
-    out2(`\u2713 createWorkspace '${name}' requested via signed governance offer to ${opts.via} on ${cloud}`);
-    out2(`  the worker provisions it on first touch; deploy is open (kernel-gated)`);
-    out2(`  (want the direct birth instead? drop --via: githolon ws create ${name})`);
+    out3(`\u2713 createWorkspace '${name}' requested via signed governance offer to ${opts.via} on ${cloud}`);
+    out3(`  the worker provisions it on first touch; deploy is open (kernel-gated)`);
+    out3(`  (want the direct birth instead? drop --via: githolon ws create ${name})`);
     return 0;
   }
-  let principal = opts.principal ?? await sessionToken().catch((e) => (err2(e.message), void 0)) ?? loadCreds().principal;
+  let principal = opts.principal ?? await sessionToken().catch((e) => (err3(e.message), void 0)) ?? loadCreds().principal;
   if (principal === void 0) {
     const d2 = await gotrue("/auth/v1/signup", "{}");
     const s = sessionFromGotrue(d2);
     if (s === void 0) {
-      err2(
+      err3(
         `a birth needs a principal, and automatic agent login failed: ${d2.error_description ?? d2.error ?? d2.msg ?? JSON.stringify(d2)}
   githolon login --agent (self-onboarding), githolon login --token <refresh>,
   or pass --principal <your-auth-uid or access token> (saved as the default)`
@@ -614,9 +890,9 @@ async function wsCreate(name, opts) {
       return 1;
     }
     saveSession(s);
-    out2(`no principal on file \u2014 self-onboarded an anonymous agent identity (githolon login --agent)`);
-    out2(`  principal uid ${s.uid} (linkable to a full account later)`);
-    out2(`  session saved \u2192 ${credsPath()} (auto-refreshed; births ride x-nomos-auth)`);
+    out3(`no principal on file \u2014 self-onboarded an anonymous agent identity (githolon login --agent)`);
+    out3(`  principal uid ${s.uid} (linkable to a full account later)`);
+    out3(`  session saved \u2192 ${credsPath()} (auto-refreshed; births ride x-nomos-auth)`);
     principal = s.accessToken;
   }
   const r = await fetch(`${cloud}/v2/workspaces/${name}`, {
@@ -625,12 +901,12 @@ async function wsCreate(name, opts) {
   });
   const d = await r.json().catch(() => void 0);
   if (!r.ok || d?.ok !== true) {
-    err2(`create '${name}' refused (${r.status}): ${d ? JSON.stringify(d) : "no body"}`);
+    err3(`create '${name}' refused (${r.status}): ${d ? JSON.stringify(d) : "no body"}`);
     return 1;
   }
   if (opts.principal !== void 0) setPrincipal(opts.principal);
-  out2(`\u2713 workspace ${name} created on ${cloud}`);
-  out2(`  deploy is open (kernel-gated): githolon deploy ${name}`);
+  out3(`\u2713 workspace ${name} created on ${cloud}`);
+  out3(`  deploy is open (kernel-gated): githolon deploy ${name}`);
   return 0;
 }
 async function wsStatus(name, opts) {
@@ -638,10 +914,10 @@ async function wsStatus(name, opts) {
   const r = await fetch(`${cloud}/v2/workspaces/${name}`);
   const text = await r.text();
   if (!r.ok) {
-    err2(`status '${name}' (${r.status}): ${text}`);
+    err3(`status '${name}' (${r.status}): ${text}`);
     return 1;
   }
-  out2(text);
+  out3(text);
   return 0;
 }
 async function wsRetire(ws, opts) {
@@ -657,16 +933,16 @@ async function wsRetire(ws, opts) {
       v = await signAndPostGovernance2(parent, "retireWorkspace", payload, opts);
     }
   } catch (e) {
-    err2(e.message);
+    err3(e.message);
     return 1;
   }
   if (!v.ok) {
-    err2(`retire '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+    err3(`retire '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
     return 1;
   }
-  out2(`\u2713 workspace ${ws} retired via signed governance offer to ${parent} on ${cloud}`);
-  out2("  nothing was deleted \u2014 the ledger and its data are retained per the Nomos Pre-Release License");
-  out2("  it no longer counts toward your workspace allowance; reads keep serving, deploys/pushes refuse");
+  out3(`\u2713 workspace ${ws} retired via signed governance offer to ${parent} on ${cloud}`);
+  out3("  nothing was deleted \u2014 the ledger and its data are retained per the Nomos Pre-Release License");
+  out3("  it no longer counts toward your workspace allowance; reads keep serving, deploys/pushes refuse");
   return 0;
 }
 async function wsReclaim(ws, opts) {
@@ -683,15 +959,15 @@ async function wsReclaim(ws, opts) {
       opts
     );
   } catch (e) {
-    err2(e.message);
+    err3(e.message);
     return 1;
   }
   if (!v.ok) {
-    err2(`reclaim '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+    err3(`reclaim '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
     return 1;
   }
-  out2(`\u2713 workspace ${ws} reclaimed via signed governance offer to ${parent} on ${cloud}`);
-  out2("  the custodian drops the ledger bytes on seeing this fact folded; the reclaimed FACT is append-only");
+  out3(`\u2713 workspace ${ws} reclaimed via signed governance offer to ${parent} on ${cloud}`);
+  out3("  the custodian drops the ledger bytes on seeing this fact folded; the reclaimed FACT is append-only");
   return 0;
 }
 async function deploy(ws, opts) {
@@ -700,11 +976,27 @@ async function deploy(ws, opts) {
   try {
     file = discoverDeployJson(process.cwd(), opts.file);
   } catch (e) {
-    err2(e.message);
+    err3(e.message);
     return 1;
   }
   const fileName = file.split("/").pop();
-  const before = await fetch(`${cloud}/v2/workspaces/${ws}/domains`).then((br) => br.json()).then((bd) => bd.ok === true ? bd.domains ?? [] : []).catch(() => []);
+  const beforeLaw = await fetch(`${cloud}/v2/workspaces/${ws}/domains`).then((br) => br.json()).then((bd) => bd.ok === true ? bd : {}).catch(() => ({}));
+  const before = beforeLaw.domains ?? [];
+  const currentLaw = beforeLaw.currentLaw ?? {};
+  const { readDeployBody: readDeployBody3, domainKeysOf: domainKeysOf2, packageHashOf: packageHashOf2, resolveDeployPlan: resolveDeployPlan2, describeDeployPlan: describeDeployPlan2 } = await Promise.resolve().then(() => (init_lifecycle(), lifecycle_exports));
+  let plan;
+  let targetHash;
+  try {
+    const body = readDeployBody3(file);
+    targetHash = packageHashOf2(body.packageUsda);
+    plan = resolveDeployPlan2(domainKeysOf2(body), currentLaw, targetHash, {
+      keepBeside: opts.keepBeside === true,
+      retireReplaced: opts.retireReplaced === true
+    });
+  } catch {
+    plan = void 0;
+    targetHash = void 0;
+  }
   const principal = opts.principal ?? activePrincipal();
   const signed = opts.principal !== void 0 || principal !== void 0 && getDeviceKey(principal) !== void 0;
   let phaseSuffix = "";
@@ -712,52 +1004,54 @@ async function deploy(ws, opts) {
   if (signed) {
     let body;
     try {
-      body = JSON.parse(readFileSync2(file, "utf8"));
+      body = JSON.parse(readFileSync3(file, "utf8"));
     } catch (e) {
-      err2(`deploy body ${file} is not valid JSON \u2014 recompile: ${e.message}`);
+      err3(`deploy body ${file} is not valid JSON \u2014 recompile: ${e.message}`);
       return 1;
     }
     const packageUsda = body.packageUsda;
     if (typeof packageUsda !== "string" || packageUsda === "") {
-      err2(`deploy body ${file} is missing packageUsda \u2014 run \`githolon compile\` again`);
+      err3(`deploy body ${file} is missing packageUsda \u2014 run \`githolon compile\` again`);
       return 1;
     }
-    const targetHash = createHash2("sha256").update(Buffer.from(packageUsda, "utf8")).digest("hex");
+    const targetHash2 = createHash3("sha256").update(Buffer.from(packageUsda, "utf8")).digest("hex");
     const { signAndPostOffer: signAndPostOffer2, resolveGovernancePrincipal: resolveGovernancePrincipal2 } = await Promise.resolve().then(() => (init_governance(), governance_exports));
     let v;
     try {
       const who = resolveGovernancePrincipal2(opts);
       const installPayload2 = {
-        domainHash: targetHash,
+        domainHash: targetHash2,
         packageUsda,
         installedBy: `user:${who}`,
         dependencies: [],
         finalizers: [],
+        // REPLACE-CURRENT: supersede the prior install per key (unless --keep-beside / first-install / idempotent).
+        ...plan?.replaces !== void 0 ? { replaces: plan.replaces, retireReplaced: plan.retireReplaced } : {},
         ...body.dispositions !== void 0 && body.dispositions !== null ? { dispositions: body.dispositions } : {}
       };
       v = await signAndPostOffer2(ws, "nomos", "installDomain", installPayload2, opts);
     } catch (e) {
-      err2(e.message);
+      err3(e.message);
       return 1;
     }
     if (!v.ok) {
-      err2(`signed deploy '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+      err3(`signed deploy '${ws}' refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
       return 1;
     }
-    deployedHash = targetHash;
+    deployedHash = targetHash2;
   } else {
     const r = await fetch(`${cloud}/v2/workspaces/${ws}/domains`, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: readFileSync2(file, "utf8")
+      body: readFileSync3(file, "utf8")
     });
     const d = await r.json().catch(() => void 0);
     if (!r.ok || d?.ok !== true) {
       const txt = d ? JSON.stringify(d) : "no body";
-      err2(`deploy '${ws}' failed (${r.status}): ${txt}`);
+      err3(`deploy '${ws}' failed (${r.status}): ${txt}`);
       if (r.status === 401 || r.status === 403 || r.status === 422 || /warrant|signed|signer|unsigned|authorship|forged|relation|installDomain/i.test(txt)) {
-        err2(`  this workspace looks WARRANTED \u2014 re-run with --as <principal> to author a SIGNED install offer`);
-        err2(`  (import the admin signing key first if needed: githolon key import --principal <uid> --secret <key>)`);
+        err3(`  this workspace looks WARRANTED \u2014 re-run with --as <principal> to author a SIGNED install offer`);
+        err3(`  (import the admin signing key first if needed: githolon key import --principal <uid> --secret <key>)`);
       }
       return 1;
     }
@@ -769,24 +1063,36 @@ async function deploy(ws, opts) {
   const currentHashes = new Set(Object.values(after.currentLaw ?? {}));
   const hasCurrencyData = Object.keys(after.currentLaw ?? {}).length > 0;
   const isCurrent = deployedHash !== void 0 && (currentHashes.has(deployedHash) || (after.domains ?? []).some((x) => x.domainHash === deployedHash && x.current === true));
+  const emitPlan = () => {
+    if (plan === void 0 || targetHash === void 0 || plan.decisions.length === 0) return;
+    for (const line of describeDeployPlan2(plan, targetHash)) out3(line);
+    if (plan.replaceCandidates.length > 1) {
+      out3(`  \u26A0 the package's keys were served by ${plan.replaceCandidates.length} different installs \u2014 installDomain supersedes one (${plan.replaces.slice(0, 16)}\u2026); the newest-Active frontier still serves this deploy for every key.`);
+    }
+    if (!signed && plan.replaces !== void 0 && !opts.keepBeside) {
+      out3(`  note: the OPEN (unsigned) lane installs BESIDE \u2014 the new law is current (newest Active) but the prior install is not marked Superseded. Sign with --as <uid> to record the supersession.`);
+    }
+  };
   if (deployedHash !== void 0 && isCurrent) {
-    out2(`\u2713 deployed ${fileName} \u2192 ${ws}${phaseSuffix}`);
-    out2(`  law ${describeLawMove(before, deployedHash)}`);
-    out2(`  \u2713 current \u2014 dispatch + reads now resolve ${deployedHash.slice(0, 16)}\u2026`);
+    out3(`\u2713 deployed ${fileName} \u2192 ${ws}${phaseSuffix}`);
+    out3(`  law ${describeLawMove(before, deployedHash)}`);
+    emitPlan();
+    out3(`  \u2713 current \u2014 dispatch + reads now resolve ${deployedHash.slice(0, 16)}\u2026`);
     return 0;
   }
   if (deployedHash === void 0 || !hasCurrencyData) {
-    out2(`\u2713 deployed ${fileName} \u2192 ${ws}${phaseSuffix}`);
-    if (deployedHash !== void 0) out2(`  law ${describeLawMove(before, deployedHash)}`);
-    out2(`  \u26A0 couldn't confirm it is the current serving law (this workspace did not report current-law resolution).`);
+    out3(`\u2713 deployed ${fileName} \u2192 ${ws}${phaseSuffix}`);
+    if (deployedHash !== void 0) out3(`  law ${describeLawMove(before, deployedHash)}`);
+    emitPlan();
+    out3(`  \u26A0 couldn't confirm it is the current serving law (this workspace did not report current-law resolution).`);
     return 0;
   }
-  err2(`deployed ${fileName} \u2192 ${ws}${phaseSuffix}, but it is NOT the current serving law \u2014 the upgrade did not take effect`);
-  out2(`  law ${describeLawMove(before, deployedHash)} (committed as an install, but the holon does not resolve it as current)`);
+  err3(`deployed ${fileName} \u2192 ${ws}${phaseSuffix}, but it is NOT the current serving law \u2014 the upgrade did not take effect`);
+  out3(`  law ${describeLawMove(before, deployedHash)} (committed as an install, but the holon does not resolve it as current)`);
   const leads = (after.domains ?? []).filter((x) => x.current === true && typeof x.domainHash === "string").map((x) => x.domainHash);
-  if (leads.length > 0) err2(`  current serving: ${leads.map((h) => h.slice(0, 16) + "\u2026").join(", ")}`);
-  else err2(`  the workspace resolves NO current law for this domain (materialisation wedged \u2014 the evolve gate did not advance it)`);
-  err2(`  re-run \`githolon deploy ${ws}\`; if it persists, the deploy committed but the workspace kept the old law (report it).`);
+  if (leads.length > 0) err3(`  current serving: ${leads.map((h) => h.slice(0, 16) + "\u2026").join(", ")}`);
+  else err3(`  the workspace resolves NO current law for this domain (materialisation wedged \u2014 the evolve gate did not advance it)`);
+  err3(`  re-run \`githolon deploy ${ws}\`; if it persists, the deploy committed but the workspace kept the old law (report it).`);
   return 2;
 }
 function describeLawMove(before, newHash) {
@@ -797,19 +1103,19 @@ function describeLawMove(before, newHash) {
 }
 async function secretSet(ws, secret, opts) {
   setSecret(cloudBase(opts.cloud), ws, secret);
-  out2(`\u2713 git push password for ${ws} saved \u2192 ${credsPath()} (used by the push-to-create birth lane)`);
+  out3(`\u2713 git push password for ${ws} saved \u2192 ${credsPath()} (used by the push-to-create birth lane)`);
   return 0;
 }
 async function secretRotate(ws, opts) {
   const cloud = cloudBase(opts.cloud);
-  err2(
+  err3(
     `secret rotate is retired (host-authority strip) \u2014 there is no host-held workspace secret on ${cloud}
   ownership is sha256(push password) bound in the chain; re-own by re-birthing via the upload lane
   with a new push password (see: githolon git remote ${ws} && git push nomos main)`
   );
   return 1;
 }
-var DEFAULT_CLOUD, DEFAULT_AUTH_URL, DEFAULT_AUTH_ANON_KEY, secretKey, out2, err2;
+var DEFAULT_CLOUD, DEFAULT_AUTH_URL, DEFAULT_AUTH_ANON_KEY, secretKey, out3, err3;
 var init_cloud = __esm({
   "src/cloud.ts"() {
     "use strict";
@@ -817,8 +1123,8 @@ var init_cloud = __esm({
     DEFAULT_AUTH_URL = "https://kjbcjkihxskuwwfdqklt.supabase.co";
     DEFAULT_AUTH_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImtqYmNqa2loeHNrdXd3ZmRxa2x0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTA3MDU2OTAsImV4cCI6MjA2NjI4MTY5MH0.V9e7XsuTlTOLqefOIedTqlBiTxUSn4O5FZSPWwAxiSI";
     secretKey = (cloud, ws) => `${cloud} ${ws}`;
-    out2 = (s) => void process.stdout.write(s + "\n");
-    err2 = (s) => void process.stderr.write("error: " + s + "\n");
+    out3 = (s) => void process.stdout.write(s + "\n");
+    err3 = (s) => void process.stderr.write("error: " + s + "\n");
   }
 });
 
@@ -939,13 +1245,13 @@ var init_tree = __esm({
 function concatBytes(chunks) {
   let n = 0;
   for (const c of chunks) n += c.length;
-  const out10 = new Uint8Array(n);
+  const out11 = new Uint8Array(n);
   let o = 0;
   for (const c of chunks) {
-    out10.set(c, o);
+    out11.set(c, o);
     o += c.length;
   }
-  return out10;
+  return out11;
 }
 function pkt(payload) {
   const body = typeof payload === "string" ? enc2.encode(payload) : payload;
@@ -1098,13 +1404,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 out10 = new Array(n), T = 2 ** 53;
+  const out11 = 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]);
-    out10[i] = Number(z >> 11n) / T;
+    out11[i] = Number(z >> 11n) / T;
   }
-  return out10;
+  return out11;
 }
 function stringifyBig(o) {
   return JSON.stringify(o, (_k, v) => typeof v === "bigint" ? `@@B:${v}@@` : v).replace(/"@@B:(\d+)@@"/g, "$1");
@@ -1328,7 +1634,7 @@ var init_engine = __esm({
 
 // src/local_holon.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname2, join as join4 } from "node:path";
 import { File as File2, Directory as Directory2 } from "@bjorn3/browser_wasi_shim";
 async function fetchJsonCached(url, cacheFile) {
@@ -1340,7 +1646,7 @@ async function fetchJsonCached(url, cacheFile) {
     writeFileSync4(cacheFile, text, "utf8");
     return JSON.parse(text);
   } catch (e) {
-    if (existsSync3(cacheFile)) return JSON.parse(readFileSync3(cacheFile, "utf8"));
+    if (existsSync3(cacheFile)) return JSON.parse(readFileSync4(cacheFile, "utf8"));
     throw e;
   }
 }
@@ -1350,7 +1656,7 @@ async function fetchRuntime(cloud) {
   const wasmCache = join4(cache, "holon.wasm");
   const localWasm = process.env["NOMOS_LOCAL_WASM"];
   if (localWasm) {
-    const bytes = readFileSync3(localWasm);
+    const bytes = readFileSync4(localWasm);
     const packages2 = await fetchJsonCached(`${cloud}/v1/runtime/packages`, join4(cache, "packages.json"));
     return { wasmBytes: bytes, packages: packages2 };
   }
@@ -1362,7 +1668,7 @@ async function fetchRuntime(cloud) {
     writeFileSync4(wasmCache, wasmBytes);
   } catch (e) {
     if (!existsSync3(wasmCache)) throw e;
-    wasmBytes = readFileSync3(wasmCache);
+    wasmBytes = readFileSync4(wasmCache);
   }
   const packages = await fetchJsonCached(`${cloud}/v1/runtime/packages`, join4(cache, "packages.json"));
   return { wasmBytes, packages };
@@ -1380,7 +1686,7 @@ function readTreeFromDisk(diskPath) {
   for (const name of readdirSync2(diskPath)) {
     const p = join4(diskPath, name);
     if (statSync(p).isDirectory()) contents.set(name, readTreeFromDisk(p));
-    else contents.set(name, new File2(readFileSync3(p)));
+    else contents.set(name, new File2(readFileSync4(p)));
   }
   return new Directory2(contents);
 }
@@ -1411,21 +1717,21 @@ function sealedIntentOf(eng, ws, res) {
 }
 function printVerdict(v) {
   if (v["valid"] === true) {
-    out3(`\u2713 chain VALID \u2014 head ${String(v["head"]).slice(0, 12)}\u2026, ${v["intents"]} intent(s), ${v["plansRerun"]} plan(s) re-run`);
-    out3(`  controller ${String(v["controllerHash"]).slice(0, 12)}\u2026 | installed: ${v["installedDomains"]?.map((h) => h.slice(0, 12) + "\u2026").join(", ") ?? "\u2014"}`);
+    out4(`\u2713 chain VALID \u2014 head ${String(v["head"]).slice(0, 12)}\u2026, ${v["intents"]} intent(s), ${v["plansRerun"]} plan(s) re-run`);
+    out4(`  controller ${String(v["controllerHash"]).slice(0, 12)}\u2026 | installed: ${v["installedDomains"]?.map((h) => h.slice(0, 12) + "\u2026").join(", ") ?? "\u2014"}`);
     return true;
   }
-  err3(`chain INVALID at ${v["check"]}${v["atIndex"] !== void 0 ? ` (intent ${v["atIndex"]})` : ""}: ${v["error"]}`);
+  err4(`chain INVALID at ${v["check"]}${v["atIndex"] !== void 0 ? ` (intent ${v["atIndex"]})` : ""}: ${v["error"]}`);
   return false;
 }
-var out3, err3;
+var out4, err4;
 var init_local_holon = __esm({
   "src/local_holon.ts"() {
     "use strict";
     init_engine();
     init_cloud();
-    out3 = (s) => void process.stdout.write(s + "\n");
-    err3 = (s) => void process.stderr.write("error: " + s + "\n");
+    out4 = (s) => void process.stdout.write(s + "\n");
+    err4 = (s) => void process.stderr.write("error: " + s + "\n");
   }
 });
 
@@ -1438,7 +1744,7 @@ __export(proof_offline_exports, {
   runOfflineProofStandalone: () => runOfflineProofStandalone,
   runRelationBootstrapLeg: () => runRelationBootstrapLeg
 });
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
 import { basename, dirname as dirname3, join as join6 } from "node:path";
 function parseOfflineLegs(proofSource) {
   if (!proofSource.includes("AUTO-GENERATED by nomos-compile")) {
@@ -1752,7 +2058,7 @@ function actorFromPayload(payload, field) {
   return typeof value === "string" && value.trim().length > 0 ? value : void 0;
 }
 async function runOfflineProofStandalone(proofPath, cloud, domain) {
-  const src = readFileSync4(proofPath, "utf8");
+  const src = readFileSync5(proofPath, "utf8");
   const packageName = basename(proofPath).replace(/\.proof\.mts$/, "");
   const deployFile = join6(dirname3(proofPath), `${packageName}.deploy.json`);
   if (!existsSync5(deployFile)) {
@@ -1761,7 +2067,7 @@ async function runOfflineProofStandalone(proofPath, cloud, domain) {
   let legs;
   const legsFile = join6(dirname3(proofPath), `${packageName}.proof-legs.json`);
   if (existsSync5(legsFile)) {
-    const index = JSON.parse(readFileSync4(legsFile, "utf8"));
+    const index = JSON.parse(readFileSync5(legsFile, "utf8"));
     const keys = Object.keys(index.domains);
     const chosen = domain ?? index.default;
     if (index.domains[chosen] === void 0) {
@@ -1779,7 +2085,7 @@ async function runOfflineProofStandalone(proofPath, cloud, domain) {
     if (domain !== void 0) throw new Error(`--domain needs a per-domain legs index (build/${packageName}.proof-legs.json) \u2014 recompile with \`githolon compile\` to emit it`);
     legs = parseOfflineLegs(src);
   }
-  const deployBody = JSON.parse(readFileSync4(deployFile, "utf8"));
+  const deployBody = JSON.parse(readFileSync5(deployFile, "utf8"));
   const lawHash = await sha256hex(deployBody.packageUsda);
   console.log(`githolon proof \u2014 OFFLINE legs on a local holon (the cloud loop: githolon proof --live)`);
   const { eng } = await holonEngine(cloud, deployBody, "githolon-proof");
@@ -1807,7 +2113,7 @@ var init_proof_offline = __esm({
 });
 
 // src/cli.ts
-import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync11 } from "node:fs";
 import { spawnSync as spawnSync4 } from "node:child_process";
 import { createRequire as createRequire2 } from "node:module";
 import { dirname as dirname5, join as join10, resolve as resolve2 } from "node:path";
@@ -2045,7 +2351,7 @@ function compileAsync(cwd, args = []) {
 // src/dev.ts
 init_engine();
 init_cloud();
-import { existsSync as existsSync6, readFileSync as readFileSync5, watch } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync6, watch } from "node:fs";
 import { createServer } from "node:http";
 import { dirname as dirname4, join as join7, resolve } from "node:path";
 import { pathToFileURL as pathToFileURL3 } from "node:url";
@@ -2138,8 +2444,8 @@ async function resolveWorkspace(explicit, cwd, target, usageHint) {
 
 // src/dev.ts
 init_proof_offline();
-var out4 = (s) => void process.stdout.write(s + "\n");
-var err4 = (s) => void process.stderr.write("error: " + s + "\n");
+var out5 = (s) => void process.stdout.write(s + "\n");
+var err5 = (s) => void process.stderr.write("error: " + s + "\n");
 var WS = "dev";
 var DEFAULT_PORT = 7700;
 var DEBOUNCE_MS = 200;
@@ -2222,12 +2528,12 @@ function startServer(s) {
     server.listen(s.port, "127.0.0.1", () => resolveSrv({ close: () => server.close() }));
   });
 }
-function readDeployBody(cwd, packageName) {
+function readDeployBody2(cwd, packageName) {
   const file = join7(cwd, "build", `${packageName}.deploy.json`);
   if (!existsSync6(file)) {
     throw new Error(`compile produced no ${file} \u2014 check the compile output above`);
   }
-  return JSON.parse(readFileSync5(file, "utf8"));
+  return JSON.parse(readFileSync6(file, "utf8"));
 }
 async function installLaw(s, deployBody, installedBy) {
   const newHash = await sha256hex(deployBody.packageUsda);
@@ -2247,7 +2553,7 @@ async function runProofCycle(s, cwd, deployBody, installedBy) {
   if (!existsSync6(proofPath)) return void 0;
   const scratch = `proof-${s.cycle}`;
   try {
-    const legs = parseOfflineLegs(readFileSync5(proofPath, "utf8"));
+    const legs = parseOfflineLegs(readFileSync6(proofPath, "utf8"));
     await mountFresh(s.eng, scratch);
     author(s.eng, scratch, "bootstrap", "installDomain", installPayload(s.eng.hashes.nomos, s.eng.nomosPkg, installedBy), "");
     author(s.eng, scratch, "nomos", "installDomain", installPayload(s.lawHash, deployBody.packageUsda, installedBy), s.eng.hashes.nomos);
@@ -2262,36 +2568,36 @@ async function dev(opts) {
   const cwd = process.cwd();
   const cloud = cloudBase(opts.cloud);
   const project = await loadProject(cwd).catch((e) => {
-    err4(e.message);
+    err5(e.message);
     return void 0;
   });
   if (project === void 0) {
     if (!existsSync6(join7(cwd, CONFIG_FILE))) {
-      err4(`no ${CONFIG_FILE} here (${cwd}) \u2014 \`githolon dev\` runs inside a project; scaffold one from examples/guestbook or \`githolon generate domain <name>\``);
+      err5(`no ${CONFIG_FILE} here (${cwd}) \u2014 \`githolon dev\` runs inside a project; scaffold one from examples/guestbook or \`githolon generate domain <name>\``);
     }
     return 1;
   }
   const creds = loadCreds();
   const installedBy = creds.session?.uid ?? creds.principal ?? "githolon-dev";
-  out4(`githolon dev \u2014 ${project.name}: compiling\u2026`);
+  out5(`githolon dev \u2014 ${project.name}: compiling\u2026`);
   const firstCompile = await compileAsync(cwd);
   if (!firstCompile.ok) {
-    err4(`compile failed \u2014 the dev loop needs one green compile to mint the holon:
+    err5(`compile failed \u2014 the dev loop needs one green compile to mint the holon:
 ${firstCompile.output}`);
     return 1;
   }
   let deployBody;
   try {
-    deployBody = readDeployBody(cwd, project.name);
+    deployBody = readDeployBody2(cwd, project.name);
   } catch (e) {
-    err4(e.message);
+    err5(e.message);
     return 1;
   }
   let engBoot;
   try {
     engBoot = await holonEngine(cloud, deployBody, installedBy);
   } catch (e) {
-    err4(`cannot boot the local holon: ${String(e.message ?? e)}
+    err5(`cannot boot the local holon: ${String(e.message ?? e)}
   the runtime rides ${cloud}/v1/runtime/* and is cached in ~/.holon/runtime after one fetch \u2014 connect once, then dev runs offline`);
     return 1;
   }
@@ -2314,19 +2620,19 @@ ${firstCompile.output}`);
   s.intents++;
   const installed = await installLaw(s, deployBody, installedBy);
   if (!installed.ok) {
-    err4(installed.error ?? "law install failed");
+    err5(installed.error ?? "law install failed");
     return 1;
   }
   s.proof = await runProofCycle(s, cwd, deployBody, installedBy);
   if (opts.once === true) {
-    out4(statusScreen({ ...s, watchRoots: ["(--once: no watch)"] }));
+    out5(statusScreen({ ...s, watchRoots: ["(--once: no watch)"] }));
     return s.proof === void 0 || s.proof.ok ? 0 : 1;
   }
   let server;
   try {
     server = await startServer(s);
   } catch (e) {
-    err4(e.message);
+    err5(e.message);
     return 1;
   }
   const moduleDirs = /* @__PURE__ */ new Set();
@@ -2354,25 +2660,25 @@ ${firstCompile.output}`);
     s.compileMs = run.ms;
     if (!run.ok) {
       s.lastError = run.output.trim() || "compile failed";
-      out4(`\u2717 cycle ${s.cycle}: compile failed \u2014 the previous law keeps serving
+      out5(`\u2717 cycle ${s.cycle}: compile failed \u2014 the previous law keeps serving
 ${run.output}`);
     } else {
       s.lastError = void 0;
       try {
-        const body = readDeployBody(cwd, s.packageName);
+        const body = readDeployBody2(cwd, s.packageName);
         const inst = await installLaw(s, body, installedBy);
         if (!inst.ok) {
           s.lastError = inst.error ?? "install failed";
-          out4(`\u2717 cycle ${s.cycle}: ${s.lastError}`);
+          out5(`\u2717 cycle ${s.cycle}: ${s.lastError}`);
         } else {
           s.proof = await runProofCycle(s, cwd, body, installedBy);
           const total = performance.now() - t0;
-          out4(statusScreen(s));
-          out4(`  cycle      edit \u2192 law-live \u2192 proof in ${total.toFixed(0)} ms total`);
+          out5(statusScreen(s));
+          out5(`  cycle      edit \u2192 law-live \u2192 proof in ${total.toFixed(0)} ms total`);
         }
       } catch (e) {
         s.lastError = String(e.message ?? e);
-        out4(`\u2717 cycle ${s.cycle}: ${s.lastError}`);
+        out5(`\u2717 cycle ${s.cycle}: ${s.lastError}`);
       }
     }
     cycling = false;
@@ -2398,8 +2704,8 @@ ${run.output}`);
     })
   );
   s.watchRoots.push(CONFIG_FILE);
-  out4(statusScreen(s));
-  out4("  (ctrl-c stops; edits in the watched paths recompile + re-prove automatically)");
+  out5(statusScreen(s));
+  out5("  (ctrl-c stops; edits in the watched paths recompile + re-prove automatically)");
   return new Promise((resolveExit) => {
     const stop = () => {
       for (const w of watchers) w.close();
@@ -2415,9 +2721,9 @@ ${run.output}`);
 init_cloud();
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { readFileSync as readFileSync6 } from "node:fs";
-var out5 = (s) => void process.stdout.write(s + "\n");
-var err5 = (s) => void process.stderr.write("error: " + s + "\n");
+import { readFileSync as readFileSync7 } from "node:fs";
+var out6 = (s) => void process.stdout.write(s + "\n");
+var err6 = (s) => void process.stderr.write("error: " + s + "\n");
 function git(args, opts = {}) {
   const r = spawnSync2("git", args, { stdio: opts.quiet === true ? "ignore" : "inherit" });
   return r.status ?? 1;
@@ -2444,36 +2750,36 @@ function workspaceFromPath(path) {
 }
 async function gitCredential(action) {
   if (action !== "get") return 0;
-  const kv = parseCredentialInput(readFileSync6(0, "utf8"));
+  const kv = parseCredentialInput(readFileSync7(0, "utf8"));
   const ws = workspaceFromPath(kv["path"]);
   if (kv["protocol"] !== "https" || ws === void 0) return 0;
   const cloud = `https://${kv["host"]}`;
   const token = await sessionToken().catch(() => void 0);
-  out5(`username=${token ?? "nomos"}`);
-  out5(`password=${ensureSecret(cloud, ws)}`);
-  out5("");
+  out6(`username=${token ?? "nomos"}`);
+  out6(`password=${ensureSecret(cloud, ws)}`);
+  out6("");
   return 0;
 }
 async function gitSetup(opts) {
   const cloud = cloudBase(opts.cloud);
   const self = process.argv[1];
   if (self === void 0) {
-    err5("cannot locate the githolon CLI entry to install as a credential helper");
+    err6("cannot locate the githolon CLI entry to install as a credential helper");
     return 1;
   }
   const helper = `!"${process.execPath}" "${self}" git-credential`;
   if (git(["config", "--global", `credential.${cloud}.helper`, helper]) !== 0 || git(["config", "--global", `credential.${cloud}.useHttpPath`, "true"]) !== 0) {
-    err5("git config failed \u2014 is git installed?");
+    err6("git config failed \u2014 is git installed?");
     return 1;
   }
-  out5(`\u2713 git credential helper installed for ${cloud} (global gitconfig)`);
-  out5(`  pushes/clones of ${cloud}/v2/workspaces/<ws>/git now authenticate from ~/.holon`);
+  out6(`\u2713 git credential helper installed for ${cloud} (global gitconfig)`);
+  out6(`  pushes/clones of ${cloud}/v2/workspaces/<ws>/git now authenticate from ~/.holon`);
   return 0;
 }
 async function gitRemote(ws, name, opts) {
   const cloud = cloudBase(opts.cloud);
   if (git(["rev-parse", "--git-dir"], { quiet: true }) !== 0) {
-    err5("not a git repository \u2014 run inside your repo (git init first)");
+    err6("not a git repository \u2014 run inside your repo (git init first)");
     return 1;
   }
   const setupRc = await gitSetup(opts);
@@ -2482,7 +2788,7 @@ async function gitRemote(ws, name, opts) {
   const url = `${cloud}/v2/workspaces/${ws}/git`;
   if (git(["remote", "add", name, url], { quiet: true }) !== 0) {
     if (git(["remote", "set-url", name, url], { quiet: true }) !== 0) {
-      err5(`could not add or update remote '${name}'`);
+      err6(`could not add or update remote '${name}'`);
       return 1;
     }
   }
@@ -2490,7 +2796,7 @@ async function gitRemote(ws, name, opts) {
   if (token === void 0) {
     const principal = loadCreds().principal;
     if (principal === void 0) {
-      err5(
+      err6(
         `remote '${name}' \u2192 ${url} is wired, but a BIRTH push needs a principal:
   githolon login --agent   (then just push)
   \u2014 or re-run after githolon ws create/login so a principal is on file`
@@ -2498,13 +2804,13 @@ async function gitRemote(ws, name, opts) {
       return 1;
     }
     if (git(["config", `http.${url}.extraHeader`, `x-nomos-principal: ${principal}`]) !== 0) {
-      err5("git config failed setting the principal header");
+      err6("git config failed setting the principal header");
       return 1;
     }
   }
-  out5(`\u2713 remote '${name}' \u2192 ${url}`);
-  out5(`  workspace secret on file; ${token !== void 0 ? "births ride your session (verified)" : "births ride x-nomos-principal (bare uid)"}`);
-  out5(`  birth/deploy by push:  git push ${name} main`);
+  out6(`\u2713 remote '${name}' \u2192 ${url}`);
+  out6(`  workspace secret on file; ${token !== void 0 ? "births ride your session (verified)" : "births ride x-nomos-principal (bare uid)"}`);
+  out6(`  birth/deploy by push:  git push ${name} main`);
   return 0;
 }
 
@@ -2662,15 +2968,28 @@ var HELP = {
     examples: ["githolon revoke creation 32c7100e-\u2026", "githolon revoke admin 32c7100e-\u2026"]
   },
   deploy: {
-    usage: "githolon deploy [<ws>] [--as <uid>] [--file <deploy.json>] [--cloud <url>] [--target <name>]",
-    what: "Deploy build/*.deploy.json \u2014 kernel-gated, no host secret. TWO lanes, picked automatically:\n\u2022 SIGNED (a WARRANTED ws, or when --as / the active `githolon use` principal has a signing key on\n  file): signs a `nomos/installDomain` offer with that key and relays it; the kernel re-verifies the\n  signature + judges the installDomain relation. Required for warranted platforms (co2, tbx) \u2014 an\n  unsigned install is refused there.\n\u2022 OPEN (unwarranted ws / no key): the open POST /domains, still kernel-judged.\nAfter the POST it re-reads the workspace and CONFIRMS the deployed hash is the CURRENT serving law\n(exit 2 if committed-but-not-current). Prints what MOVED (old \u2192 new law hash). With no <ws>, the\nproject's `workspace` binding in nomos.package.mjs resolves it.",
+    usage: "githolon deploy [<ws>] [--as <uid>] [--keep-beside] [--retire-replaced] [--file <deploy.json>] [--cloud <url>] [--target <name>]",
+    what: "Deploy build/*.deploy.json \u2014 kernel-gated, no host secret. DEFAULT = REPLACE-CURRENT: for each domain\nkey in the package it resolves the workspace's CURRENT served install (the holon's `currentLaw` frontier\nmap) and passes it as installDomain's `replaces`, so the new law SUPERSEDES the old per key (the prior\ndrops out of the served frontier). Re-deploying the SAME hash stays idempotent (never self-superseded).\nTWO lanes, picked automatically:\n\u2022 SIGNED (a WARRANTED ws, or when --as / the active `githolon use` principal has a signing key on\n  file): signs a `nomos/installDomain` offer (carrying `replaces`) with that key and relays it; the\n  kernel re-verifies the signature + judges the installDomain relation. Required for warranted platforms.\n\u2022 OPEN (unwarranted ws / no key): the open POST /domains \u2014 installs BESIDE (the host-authored lane does\n  not thread `replaces`; the newest-Active frontier still serves the deploy). Sign with --as to supersede.\nAfter the POST it CONFIRMS the deployed hash is the CURRENT serving law (exit 2 if committed-but-not-\ncurrent) and prints what MOVED, per key. With no <ws>, the project's `workspace` binding resolves it.",
     flags: [
       ["--as <uid>", "deploy as this principal via the SIGNED lane (needs its key \u2014 githolon key import; else githolon use)"],
+      ["--keep-beside", "install BESIDE the prior law (the old multi-version default; no supersession)"],
+      ["--retire-replaced", "supersede via Retired (not just Superseded) \u2014 the prior install is explicitly retired"],
       ["--file <path>", "an explicit deploy body (default: the one build/*.deploy.json)"],
       ["--target <name>", "pick among named targets (workspace: { dev: \u2026, prod: \u2026 })"],
       ["--cloud <url>", "target cloud"]
     ],
-    examples: ["githolon deploy", "githolon deploy my-guestbook", "githolon use <admin-uid> && githolon deploy co2-platform", "githolon deploy tbx --as <admin-uid>"]
+    examples: ["githolon deploy", "githolon deploy my-guestbook", "githolon deploy co2-platform --as <admin-uid>", "githolon deploy my-ws --keep-beside", "githolon deploy my-ws --retire-replaced"]
+  },
+  domains: {
+    usage: "githolon domains <status <ws> [--explain-current-interface] | retire <ws> <hashOrKey> [--with <hashOrKey>]>",
+    what: "The INSTALL-LIFECYCLE lane over a workspace's law.\n\u2022 status: per domain KEY, the current SERVED hash + phase, then the superseded/retired lineage behind it\n  (replayable installs the frontier excludes). --explain-current-interface spells out WHY the current\n  interface is what it is \u2014 the frontier resolves the newest Active-not-superseded/-retired install per\n  key, so old installs never pollute the current interface.\n\u2022 retire: mark an install Retired (replayable, no longer served) via a signed installDomain offer. The\n  framework retires only as the consequence of installing a SUCCESSOR \u2014 by default the local compiled\n  package (build/*.deploy.json), or --with <hashOrKey> names an already-installed successor. A key the\n  successor does not cover is left with NO served law \u2014 WARNED loudly, never blocked. A key resolves to\n  its current served hash; a 64-hex arg is taken as the install hash.",
+    flags: [
+      ["--explain-current-interface", "status: also explain the frontier resolution (why the interface is what it is)"],
+      ["--with <hashOrKey>", "retire: the retiring successor package \u2014 an already-installed hash or served key"],
+      ["--as <uid>", "retire as this principal (installing law is kernel-judged; needs a signing key)"],
+      ["--cloud <url>", "target cloud"]
+    ],
+    examples: ["githolon domains status co2-platform", "githolon domains status co2-platform --explain-current-interface", "githolon domains retire my-ws <oldHash> --as <admin-uid>"]
   },
   secret: {
     usage: "githolon secret <set <ws> <push-password> | rotate <ws>> [--cloud <url>]",
@@ -2709,33 +3028,33 @@ init_engine();
 init_cloud();
 init_local_holon();
 import { spawnSync as spawnSync3 } from "node:child_process";
-import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join8 } from "node:path";
-var out6 = (s) => void process.stdout.write(s + "\n");
-var err6 = (s) => void process.stderr.write("error: " + s + "\n");
+var out7 = (s) => void process.stdout.write(s + "\n");
+var err7 = (s) => void process.stderr.write("error: " + s + "\n");
 var WS2 = "local";
 async function ledgerInit(dir, opts) {
   const cloud = cloudBase(opts.cloud);
   if (existsSync7(dir) && readdirSync3(dir).length > 0) {
-    err6(`refusing to mint into non-empty directory: ${dir}`);
+    err7(`refusing to mint into non-empty directory: ${dir}`);
     return 1;
   }
   let deployFile;
   try {
     deployFile = discoverDeployJson(process.cwd(), opts.file);
   } catch (e) {
-    err6(e.message);
+    err7(e.message);
     return 1;
   }
-  const deployBody = JSON.parse(readFileSync7(deployFile, "utf8"));
+  const deployBody = JSON.parse(readFileSync8(deployFile, "utf8"));
   const domainHash = await sha256hex(deployBody.packageUsda);
   const c = loadCreds();
   const principal = await sessionToken().catch(() => void 0) !== void 0 ? c.session.uid : c.principal;
   if (principal === void 0) {
-    err6("a holon is born OF someone \u2014 githolon login --agent first (or githolon ws create --principal <uid> once)");
+    err7("a holon is born OF someone \u2014 githolon login --agent first (or githolon ws create --principal <uid> once)");
     return 1;
   }
-  out6(`minting a holon locally (law ${domainHash.slice(0, 12)}\u2026, installedBy ${principal})`);
+  out7(`minting a holon locally (law ${domainHash.slice(0, 12)}\u2026, installedBy ${principal})`);
   const { eng } = await holonEngine(cloud, deployBody, principal);
   await mountFresh(eng, WS2);
   author(eng, WS2, "bootstrap", "installDomain", installPayload(eng.hashes.nomos, eng.nomosPkg, principal), "");
@@ -2746,18 +3065,18 @@ async function ledgerInit(dir, opts) {
   const gitDir = join8(dir, ".git");
   writeTreeToDisk(gitTree, gitDir);
   const cfgPath = join8(gitDir, "config");
-  writeFileSync5(cfgPath, readFileSync7(cfgPath, "utf8").replace(/bare = true/, "bare = false"), "utf8");
+  writeFileSync5(cfgPath, readFileSync8(cfgPath, "utf8").replace(/bare = true/, "bare = false"), "utf8");
   spawnSync3("git", ["-C", dir, "reset", "--hard", "main"], { stdio: "ignore" });
-  out6(`\u2713 holon written \u2192 ${dir} (a normal git repo; git log IS the audit trail)`);
-  out6(`
+  out7(`\u2713 holon written \u2192 ${dir} (a normal git repo; git log IS the audit trail)`);
+  out7(`
 Birth it on Nomos Cloud (the cloud re-derives this exact verdict):`);
-  out6(`  cd ${dir} && npx githolon git remote <ws> && git push nomos main`);
+  out7(`  cd ${dir} && npx githolon git remote <ws> && git push nomos main`);
   return 0;
 }
 async function ledgerVerify(dir, opts) {
   const gitDir = existsSync7(join8(dir, ".git")) ? join8(dir, ".git") : dir;
   if (!existsSync7(join8(gitDir, "HEAD"))) {
-    err6(`${dir} is not a git repo (no HEAD)`);
+    err7(`${dir} is not a git repo (no HEAD)`);
     return 1;
   }
   const { eng } = await holonEngine(cloudBase(opts.cloud), void 0, "verify");
@@ -2775,8 +3094,8 @@ init_local_holon();
 import { existsSync as existsSync8 } from "node:fs";
 import { join as join9 } from "node:path";
 import git2 from "isomorphic-git";
-var out7 = (s) => void process.stdout.write(s + "\n");
-var err7 = (s) => void process.stderr.write("error: " + s + "\n");
+var out8 = (s) => void process.stdout.write(s + "\n");
+var err8 = (s) => void process.stderr.write("error: " + s + "\n");
 var SOURCE = "source";
 var REPLAY = "replay";
 function summarizePayload(payload, max = 100) {
@@ -2812,9 +3131,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 out10 = {};
-    for (const [k, x] of Object.entries(v)) out10[k] = capJsonStrings(x, max);
-    return out10;
+    const out11 = {};
+    for (const [k, x] of Object.entries(v)) out11[k] = capJsonStrings(x, max);
+    return out11;
   }
   return v;
 }
@@ -2861,12 +3180,12 @@ function readKey() {
 async function replay(target, opts) {
   const cloud = cloudBase(opts.cloud);
   const json = opts.json === true;
-  const emit = (o) => out7(JSON.stringify(o));
+  const emit = (o) => out8(JSON.stringify(o));
   let eng;
   try {
     ({ eng } = await holonEngine(cloud, void 0, "githolon-replay"));
   } catch (e) {
-    err7(`cannot boot the local holon: ${String(e.message ?? e)}
+    err8(`cannot boot the local holon: ${String(e.message ?? e)}
   the runtime rides ${cloud}/v1/runtime/* (cached in ~/.holon/runtime after one fetch)`);
     return 1;
   }
@@ -2874,7 +3193,7 @@ async function replay(target, opts) {
   if (isDir) {
     const gitDir = existsSync8(join9(target, ".git")) ? join9(target, ".git") : target;
     if (!existsSync8(join9(gitDir, "HEAD"))) {
-      err7(`${target} is not a git repo (no HEAD) \u2014 pass a holon directory (githolon ledger init <dir>) or a workspace name`);
+      err8(`${target} is not a git repo (no HEAD) \u2014 pass a holon directory (githolon ledger init <dir>) or a workspace name`);
       return 1;
     }
     await mountFresh(eng, SOURCE);
@@ -2882,7 +3201,7 @@ async function replay(target, opts) {
   } else {
     const m = await mountWorkspace(eng, SOURCE, { remote: `${cloud}/v2/workspaces/${target}/git`, headers: {} });
     if (m.restored !== true) {
-      err7(
+      err8(
         `workspace '${target}' has no refs/heads/main on ${cloud} \u2014 nothing to replay` + (m.restoreError ? ` (${String(m.restoreError).split(" | ")[0]})` : "") + `
   check the name (githolon ws status ${target}), or pass a local holon directory instead`
       );
@@ -2891,7 +3210,7 @@ async function replay(target, opts) {
   }
   const chain = await walkChain(eng, SOURCE);
   if (chain.length === 0) {
-    err7(`the chain on '${target}' carries no intents \u2014 nothing to replay`);
+    err8(`the chain on '${target}' carries no intents \u2014 nothing to replay`);
     return 1;
   }
   await mountFresh(eng, REPLAY);
@@ -2900,8 +3219,8 @@ async function replay(target, opts) {
   const tallies = /* @__PURE__ */ new Map();
   let autoRun = !interactive;
   if (!json) {
-    out7(`replaying ${chain.length} intent(s) from ${isDir ? target : `${cloud} :: ${target}`} \u2014 every step re-admitted through the wasm gate`);
-    if (interactive) out7("  keys: enter = next intent \xB7 a = run to the end \xB7 q = quit\n");
+    out8(`replaying ${chain.length} intent(s) from ${isDir ? target : `${cloud} :: ${target}`} \u2014 every step re-admitted through the wasm gate`);
+    if (interactive) out8("  keys: enter = next intent \xB7 a = run to the end \xB7 q = quit\n");
   }
   for (let i = 0; i < chain.length; i++) {
     const { oid, bytes, doc } = chain[i];
@@ -2915,8 +3234,8 @@ async function replay(target, opts) {
     if (res.ok === false) {
       const msg = `replay REFUSED at intent ${i} (${domain}/${directive}, ${oid.slice(0, 10)}): ${res.error ?? "unknown"}`;
       if (json) emit({ step: i, oid, domain, directive, refused: true, error: res.error ?? "unknown" });
-      else err7(msg);
-      err7("the chain's own gate rejects this entry on a fresh fold \u2014 the source it came from would refuse it too (verify below names the check)");
+      else err8(msg);
+      err8("the chain's own gate rejects this entry on a fresh fold \u2014 the source it came from would refuse it too (verify below names the check)");
       printVerdict(verifyChainLocal(eng, SOURCE));
       return 1;
     }
@@ -2937,31 +3256,31 @@ async function replay(target, opts) {
         tallies: Object.fromEntries(tallies)
       });
     } else {
-      out7(`[${String(i + 1).padStart(String(chain.length).length)}/${chain.length}] ${domain}/${directive}  (${oid.slice(0, 10)}, ${ms.toFixed(0)} ms)`);
-      out7(`      payload  ${summarizePayload(doc.payload?.payload)}`);
+      out8(`[${String(i + 1).padStart(String(chain.length).length)}/${chain.length}] ${domain}/${directive}  (${oid.slice(0, 10)}, ${ms.toFixed(0)} ms)`);
+      out8(`      payload  ${summarizePayload(doc.payload?.payload)}`);
       for (const ev of doc.events ?? []) {
         const id = ev.aggregate ?? "?";
         const was = before.get(id);
         const verb = ev.marker === "Create" ? "+ created" : ev.marker === "Delete" ? "- deleted" : was === void 0 ? "~ touched" : "~ updated";
-        out7(`      ${verb}  ${id}`);
+        out8(`      ${verb}  ${id}`);
         const ops = summarizeOps(ev);
-        if (ops.length > 0) out7(`                ${ops}`);
+        if (ops.length > 0) out8(`                ${ops}`);
       }
       const tallyLine = [...tallies.entries()].map(([t, n]) => `${t}:${n}`).join("  ");
       const showTally = stepEvery > 0 ? (i + 1) % stepEvery === 0 || i === chain.length - 1 : true;
-      if (showTally && tallyLine.length > 0) out7(`      rows     ${tallyLine}`);
+      if (showTally && tallyLine.length > 0) out8(`      rows     ${tallyLine}`);
     }
     if (interactive && !autoRun && i < chain.length - 1) {
       const key = await readKey();
       if (key === "quit") {
-        out7(`
+        out8(`
 stopped at intent ${i + 1}/${chain.length} \u2014 the verify verdict below covers the WHOLE chain as delivered`);
         break;
       }
       if (key === "all") autoRun = true;
     }
   }
-  if (!json) out7("");
+  if (!json) out8("");
   const verdict = verifyChainLocal(eng, SOURCE);
   if (json) {
     emit({ finale: true, verdict });
@@ -2975,32 +3294,32 @@ init_local_holon();
 init_cloud();
 init_engine();
 var SOURCE2 = "source";
-var out8 = (s) => {
+var out9 = (s) => {
   process.stdout.write(s + "\n");
 };
-var err8 = (s) => {
+var err9 = (s) => {
   process.stderr.write(`error: ${s}
 `);
 };
 async function decrypt(ws, opts) {
   const cloud = cloudBase(opts.cloud);
   if (!opts.as) {
-    err8("--as <principal> is required (who to decrypt as)");
+    err9("--as <principal> is required (who to decrypt as)");
     return 1;
   }
   if (!opts.secret) {
-    err8("--secret <base64 X25519 device secret> is required");
+    err9("--secret <base64 X25519 device secret> is required");
     return 1;
   }
   if (!opts.query) {
-    err8("--query <queryId> is required (the read to decrypt)");
+    err9("--query <queryId> is required (the read to decrypt)");
     return 1;
   }
   let eng;
   try {
     ({ eng } = await holonEngine(cloud, opts.overlay, "githolon-decrypt"));
   } catch (e) {
-    err8(`cannot boot the local holon: ${String(e.message ?? e)}`);
+    err9(`cannot boot the local holon: ${String(e.message ?? e)}`);
     return 1;
   }
   const m = await mountWorkspace(eng, SOURCE2, {
@@ -3008,7 +3327,7 @@ async function decrypt(ws, opts) {
     headers: { "x-nomos-principal": opts.as }
   });
   if (m.restored !== true) {
-    err8(`workspace '${ws}' has no main on ${cloud}, or its clone was refused for '${opts.as}'` + (m.restoreError ? ` (${String(m.restoreError).split(" | ")[0]})` : ""));
+    err9(`workspace '${ws}' has no main on ${cloud}, or its clone was refused for '${opts.as}'` + (m.restoreError ? ` (${String(m.restoreError).split(" | ")[0]})` : ""));
     return 1;
   }
   const wraps = query(eng, SOURCE2, "wrappedKeysByRecipient", JSON.stringify({ recipientPrincipal: opts.as }), opts.as);
@@ -3023,23 +3342,23 @@ async function decrypt(ws, opts) {
       }
     }
   }
-  if (opts.json !== true) out8(`# resolved ${keys.length} scope key(s) for '${opts.as}': ${keys.map((k) => `${k.scope}@${k.epoch}`).join(", ") || "(none)"}`);
+  if (opts.json !== true) out9(`# resolved ${keys.length} scope key(s) for '${opts.as}': ${keys.map((k) => `${k.scope}@${k.epoch}`).join(", ") || "(none)"}`);
   const rows = query(eng, SOURCE2, opts.query, JSON.stringify(opts.params ?? {}), opts.as, keys);
   if (rows && !Array.isArray(rows) && rows.ok === false) {
-    err8(`the read was refused: ${rows.error}` + (String(rows.error).startsWith("read-forbidden") ? `
+    err9(`the read was refused: ${rows.error}` + (String(rows.error).startsWith("read-forbidden") ? `
   '${opts.as}' is not granted this scope's read capability` : ""));
     return 1;
   }
-  out8(JSON.stringify(rows, null, opts.json === true ? 0 : 2));
+  out9(JSON.stringify(rows, null, opts.json === true ? 0 : 2));
   return 0;
 }
 
 // src/status.ts
 init_engine();
 init_cloud();
-import { readFileSync as readFileSync9 } from "node:fs";
-var out9 = (s) => void process.stdout.write(s + "\n");
-var err9 = (s) => void process.stderr.write("error: " + s + "\n");
+import { readFileSync as readFileSync10 } from "node:fs";
+var out10 = (s) => void process.stdout.write(s + "\n");
+var err10 = (s) => void process.stderr.write("error: " + s + "\n");
 function lawDiffVerdict(localHash, installed, ws, hasCurrencyData) {
   const active = installed.filter((d) => d.phase === "Active" && typeof d.domainHash === "string");
   const currents = active.filter((d) => d.current === true);
@@ -3087,48 +3406,48 @@ async function status(wsArg, opts) {
   try {
     ws = await resolveWorkspace(wsArg, process.cwd(), opts.target, "githolon status <ws>");
   } catch (e) {
-    err9(e.message);
+    err10(e.message);
     return 1;
   }
   let localHash;
   try {
-    const body = JSON.parse(readFileSync9(discoverDeployJson(process.cwd(), opts.file), "utf8"));
+    const body = JSON.parse(readFileSync10(discoverDeployJson(process.cwd(), opts.file), "utf8"));
     if (typeof body.packageUsda === "string") localHash = await sha256hex(body.packageUsda);
   } catch {
     localHash = void 0;
   }
   const r = await fetch(`${cloud}/v2/workspaces/${ws}/domains`).catch(() => void 0);
   if (r === void 0) {
-    err9(`cannot reach ${cloud} \u2014 githolon status compares against the DEPLOYED law and needs the cloud (local-only: githolon dev)`);
+    err10(`cannot reach ${cloud} \u2014 githolon status compares against the DEPLOYED law and needs the cloud (local-only: githolon dev)`);
     return 1;
   }
   const d = await r.json().catch(() => void 0);
   if (!r.ok || d?.ok !== true) {
-    err9(`status '${ws}' failed (${r.status}): ${d ? JSON.stringify(d) : "no body"}
+    err10(`status '${ws}' failed (${r.status}): ${d ? JSON.stringify(d) : "no body"}
   is the workspace born? githolon ws create ${ws}`);
     return 1;
   }
-  out9(`workspace  ${ws} on ${cloud}`);
+  out10(`workspace  ${ws} on ${cloud}`);
   const allDomains = d.domains ?? [];
   const controlPlaneHashes = new Set(CONTROL_PLANE_KEYS.map((k) => d.currentLaw?.[k]).filter(Boolean));
   const domains = allDomains.filter((dm) => !controlPlaneHashes.has(dm.domainHash));
   const controllerCount = allDomains.length - domains.length;
-  if (allDomains.length === 0) out9(`installed  (none \u2014 not even the controller; the workspace may be unborn)`);
+  if (allDomains.length === 0) out10(`installed  (none \u2014 not even the controller; the workspace may be unborn)`);
   for (const dom of domains) {
     const mark = dom.current === true ? "  \u2190 current (the holon resolves dispatch here)" : "";
-    out9(`installed  ${(dom.domainHash ?? "?").slice(0, 16)}\u2026  ${dom.phase ?? "?"}  by ${dom.installedBy ?? "?"}${mark}`);
+    out10(`installed  ${(dom.domainHash ?? "?").slice(0, 16)}\u2026  ${dom.phase ?? "?"}  by ${dom.installedBy ?? "?"}${mark}`);
   }
-  if (controllerCount > 0) out9(`           (+ ${controllerCount} control-plane install(s) \u2014 the nomos lifecycle controller; not tenant law)`);
+  if (controllerCount > 0) out10(`           (+ ${controllerCount} control-plane install(s) \u2014 the nomos lifecycle controller; not tenant law)`);
   const tenantActive = domains.filter((dm) => dm.phase === "Active").length;
-  if (tenantActive > 1) out9(`           (${tenantActive} active tenant installs \u2014 install-beside keeps every prior deploy Active; the holon serves the current one per domain)`);
+  if (tenantActive > 1) out10(`           (${tenantActive} active tenant installs \u2014 install-beside keeps every prior deploy Active; the holon serves the current one per domain)`);
   if (localHash === void 0) {
-    out9(`local      (no build/*.deploy.json here \u2014 run \`githolon compile\` to build the law this project authors)`);
+    out10(`local      (no build/*.deploy.json here \u2014 run \`githolon compile\` to build the law this project authors)`);
     return 0;
   }
-  out9(`local      ${localHash.slice(0, 16)}\u2026  (build/*.deploy.json)`);
+  out10(`local      ${localHash.slice(0, 16)}\u2026  (build/*.deploy.json)`);
   const hasCurrencyData = Object.keys(d.currentLaw ?? {}).length > 0;
   const verdict = lawDiffVerdict(localHash, domains, ws, hasCurrencyData);
-  for (const line of verdict.lines) out9(line);
+  for (const line of verdict.lines) out10(line);
   return verdict.inSync ? 0 : 2;
 }
 
@@ -3188,8 +3507,14 @@ deploy is OPEN + kernel-gated \u2014 births return no host secret, ownership is
                                                        quota freed; data retained; reads keep serving
   githolon ws reclaim <name> [--parent <ws>]              lawful custody discard via a SIGNED governance offer
                                                        (only a retired workspace; never root)
-  githolon deploy [<ws>] [--file <deploy.json>]           POST build/*.deploy.json (open deploy lane);
-                                                       prints what moved (old \u2192 new law hash)
+  githolon deploy [<ws>] [--file <deploy.json>]           deploy build/*.deploy.json \u2014 DEFAULT replace-current:
+            [--keep-beside] [--retire-replaced]           the new law SUPERSEDES the prior install per domain
+                                                       key (prints what moved). --keep-beside installs
+                                                       beside; --retire-replaced supersedes via Retired
+  githolon domains status <ws>                            per domain key: the current served law + phase +
+            [--explain-current-interface]                superseded/retired lineage (the served frontier)
+  githolon domains retire <ws> <hashOrKey>                retire an install (marks it Retired \u2014 replayable,
+            [--with <hashOrKey>]                          no longer served) via a signed installDomain offer
   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)
 
@@ -3214,14 +3539,17 @@ 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"];
-  const BOOL_FLAGS = ["--sha256", "--stamp", "--yes", "--clear"];
+  const VALUE_FLAGS = ["--cloud", "--principal", "--as", "--file", "--target", "--parent", "--via", "--max", "--label", "--secret", "--payload", "--payload-file", "--save", "--format", "--with"];
+  const BOOL_FLAGS = ["--sha256", "--stamp", "--yes", "--clear", "--keep-beside", "--retire-replaced", "--explain-current-interface"];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (BOOL_FLAGS.includes(a)) {
       if (a === "--sha256") opts.sha256 = true;
       else if (a === "--stamp") opts.stamp = true;
       else if (a === "--clear") opts.clear = true;
+      else if (a === "--keep-beside") opts.keepBeside = true;
+      else if (a === "--retire-replaced") opts.retireReplaced = true;
+      else if (a === "--explain-current-interface") opts.explain = true;
       else opts.yes = true;
     } else if (VALUE_FLAGS.includes(a)) {
       const v = rest[++i];
@@ -3237,6 +3565,7 @@ function cloudArgs(rest) {
       else if (a === "--payload-file") opts.payloadFile = v;
       else if (a === "--save") opts.save = v;
       else if (a === "--format") opts.format = v;
+      else if (a === "--with") opts.with = v;
       else if (a === "--max") {
         const n = Number(v);
         if (!Number.isInteger(n) || n <= 0) return { pos, opts, bad: `--max requires a positive integer` };
@@ -3366,7 +3695,7 @@ async function runProof(args) {
   if (tsxDir === void 0) {
     return refuse("tsx not found \u2014 add @githolon/dsl to your project's dependencies (tsx rides along) and npm install");
   }
-  const tsxPkg = JSON.parse(readFileSync10(join10(tsxDir, "package.json"), "utf8"));
+  const tsxPkg = JSON.parse(readFileSync11(join10(tsxDir, "package.json"), "utf8"));
   const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.["tsx"];
   const tsxCli = join10(tsxDir, tsxBinRel ?? "dist/cli.mjs");
   console.log("githolon proof --live \u2014 the full cloud loop (throwaway workspace, retired on exit" + (keep ? "; --keep: kept, secret printed once" : "") + ")");
@@ -3381,7 +3710,7 @@ function parseArgs(argv) {
   const [command, ...rest] = argv;
   if (command !== "generate" && command !== "g") {
     throw new Error(
-      `Unknown command '${command ?? "(none)"}'. Expected dev | compile | proof | replay | status | generate | ws | deploy | secret.`
+      `Unknown command '${command ?? "(none)"}'. Expected dev | compile | proof | replay | status | generate | ws | deploy | domains | secret.`
     );
   }
   let outDir = DEFAULT_OUT;
@@ -3547,6 +3876,41 @@ ${commandHelp("status")}`);
   if (argv[0] === "ws" || argv[0] === "deploy" || argv[0] === "secret") {
     return runCloud(argv);
   }
+  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));
+    if (bad !== void 0) {
+      process.stderr.write(`error: ${bad}
+
+${commandHelp("domains") ?? USAGE}`);
+      return 1;
+    }
+    const [sub, ...tail] = pos;
+    const boundWs = async (explicit, hint) => resolveWorkspace(explicit, process.cwd(), opts.target, hint);
+    try {
+      if (sub === "retire") {
+        const [ws, target] = tail;
+        if (ws === void 0 || target === void 0) {
+          process.stderr.write(`error: expected: githolon domains retire <ws> <domainHashOrKey> [--with <hashOrKey>]
+
+${commandHelp("domains") ?? USAGE}`);
+          return 1;
+        }
+        return await domainsRetire2(await boundWs(ws, "githolon domains retire <ws> <hashOrKey>"), target, opts);
+      }
+      if (sub === "status") {
+        return await domainsStatus2(await boundWs(tail[0], "githolon domains status <ws>"), opts);
+      }
+    } catch (e) {
+      process.stderr.write(`error: ${e.message}
+`);
+      return 1;
+    }
+    process.stderr.write(`error: expected: githolon domains <status <ws> [--explain-current-interface] | retire <ws> <hashOrKey>>
+
+${commandHelp("domains") ?? USAGE}`);
+    return 1;
+  }
   if (argv[0] === "key") {
     const { keyEnroll: keyEnroll2, keyExport: keyExport2, keyImport: keyImport2, keyShow: keyShow2 } = await Promise.resolve().then(() => (init_governance(), governance_exports));
     const { pos, opts, bad } = cloudArgs(argv.slice(1));
@@ -3679,8 +4043,8 @@ ${USAGE}`);
   let parsed;
   try {
     parsed = parseArgs(argv);
-  } catch (err10) {
-    process.stderr.write(`error: ${err10.message}
+  } catch (err11) {
+    process.stderr.write(`error: ${err11.message}
 
 ${USAGE}`);
     return 1;
@@ -3699,8 +4063,8 @@ ${USAGE}`);
     process.stdout.write(`created ${path}
 `);
     return 0;
-  } catch (err10) {
-    process.stderr.write(`error: ${err10.message}
+  } catch (err11) {
+    process.stderr.write(`error: ${err11.message}
 `);
     return 1;
   }