run402 4.41.0 → 4.43.0

package/README.md

@@ -54,7 +54,7 @@ For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeS
 
 ### repos — host-blind encrypted git repos (zero deploy ceremony)
 
-One noun, twelve verbs (repo-surface-consolidation; `repo` singular resolves identically). `run402 gitvault <verb>` is RETIRED — every old spelling now answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
+One noun, twelve verbs (`repo` singular resolves identically). `run402 gitvault <verb>` answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
 
 ```bash
 run402 init                                   # once per machine
@@ -70,7 +70,7 @@ run402 repos delete --project prj_xyz --force # refuses without --force while th
 
 A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. Every mutating `repos` verb (`create`, `rename`, `delete`, `snapshot`, `policy`, `mirror`, `gc`) is CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete). Three READ-ONLY tools do exist — `repos_view`, `repos_list_heads`, `repos_fsck` — teaching only `repos` spellings. See `run402 repos --help` for the full tiered surface (common: `create`/`view`/`list`; occasional: `snapshot`/`mirror`/`recover`; lifecycle: `rename`/`delete`; maintenance: `fsck`/`gc`/`access`/`policy`), and the CLI reference's `repos` section for the terminal-loss statement and the progressive backup warning.
 
-**Named addressing (design D6).** `run402 org slug <slug>` (owner-only, small one-time fee) claims an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos rename <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee, absorbs the old `repos name`); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
+**Named addressing.** `run402 org slug <slug>` (owner-only, small one-time fee) claims an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos rename <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
 
 ### Allowance
 

package/lib/argparse.mjs

@@ -272,7 +272,7 @@ export function requirePositionalCount(args = [], flagsWithValues = [], opts = {
   return pos;
 }
 
-// Resolve a positional project_id argument with active-project fallback (GH-102, GH-187).
+// Resolve a positional project_id argument with active-project fallback.
 // If the first positional starts with "prj_", treat it as the project id and
 // strip it from the rest. Otherwise, fall through to the active project from
 // the keystore. Callers can tighten the legacy shorthand when a bare non-prj

package/lib/assets.mjs

@@ -265,7 +265,7 @@ function parseArgs(rawArgs) {
     else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
     else if (a === "--ttl") out.ttl = parseIntegerFlag("--ttl", args[++i], { min: 60, max: 604800 });
-    // v1.50: repeatable --meta key=value (number-coerce on pure digits,
+    // Repeatable --meta key=value (number-coerce on pure digits,
     // comma-split into string[] when value contains ',', "true"/"false"
     // → boolean, else string). Multiple --meta flags accumulate into a
     // single flat metadata object.
@@ -274,7 +274,7 @@ function parseArgs(rawArgs) {
       applyMetaFlag(out.metadata, args[++i]);
     }
     else if (a === "--exif-policy") out.exifPolicy = parseExifPolicyFlag(args[++i]);
-    // v1.50: ls --sort and repeatable --filter k=v.
+    // ls --sort and repeatable --filter k=v.
     else if (a === "--sort") out.sort = parseSortFlag(args[++i]);
     else if (a === "--filter") {
       if (out.filter === null) out.filter = {};
@@ -285,7 +285,7 @@ function parseArgs(rawArgs) {
   return out;
 }
 
-/** v1.50: parse a single `--meta key=value` token. Coerces value:
+/** Parses a single `--meta key=value` token. Coerces value:
  *    - numeric digits (with optional leading `-` / decimal) → number
  *    - "true" / "false" → boolean
  *    - commas → string[] (each segment stays a string; agents wanting
@@ -436,23 +436,19 @@ async function putOne(projectId, filePath, opts) {
   }
   const destKey = computeDestKey(filePath, opts.key);
 
-  // v2.1.0: the legacy /storage/v1/uploads* session API is gone. The CLI
-  // now delegates to `sdk.assets.put`, which routes through the
+  // The CLI delegates to `sdk.assets.put`, which routes through the
   // unified-apply hero (apply/v1/plans -> content/v1/plans -> S3 PUT ->
-  // commit).
-  //
-  // Trade-off vs v2.0.x: resumable uploads via persisted state under
-  // ~/.run402/uploads/ are no longer supported. Resume semantics now live
-  // at the apply-plan level (24h plan TTL); a future CLI redesign can
-  // expose that. The --concurrency and --no-resume flags are accepted but
-  // ignored — the SDK upload paths handle parallelism internally.
+  // commit). Resume semantics live at the apply-plan level (24h plan TTL);
+  // a future CLI redesign can expose that. The --concurrency and --no-resume
+  // flags are accepted but ignored — the SDK upload paths handle parallelism
+  // internally.
   log(opts, { event: "start", key: destKey, size_bytes: stat.size });
   const bytes = new Uint8Array(readFileSync(filePath));
   const result = await getSdk().assets.put(projectId, destKey, { bytes }, {
     contentType: opts.contentType ?? guessContentType(destKey),
     visibility: opts.private ? "private" : "public",
     immutable: opts.immutable,
-    // v1.50: thread caller-supplied metadata + EXIF policy through. The
+    // Threads caller-supplied metadata + EXIF policy through. The
     // SDK validates each value with the same error code (INVALID_ASSET_
     // METADATA / INVALID_EXIF_POLICY) the gateway returns, so a bad
     // --meta / --exif-policy fails fast without an HTTP roundtrip.
@@ -532,7 +528,7 @@ async function ls(argv) {
     const data = await getSdk().assets.ls(resolvedId, {
       prefix: opts.prefix ?? undefined,
       limit: opts.limit ?? undefined,
-      // v1.50: forward sort + filter to the SDK. Cursor stays absent for
+      // Forward sort + filter to the SDK. Cursor stays absent for
       // first-page calls; agents pass `--cursor` for follow-ups but the
       // cursor is sort-pinned by the gateway so it doesn't accept a
       // separate `--cursor` flag here yet.

package/lib/command-manifest.mjs

@@ -197,7 +197,7 @@ export const COMMAND_MANIFEST = [
   { path: ["org", "get"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "rename"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--name", "Gate"] },
   { path: ["org", "payout-wallet"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
-  // repo-first-onramp task 4.1 (design D6). `--org` (not a positional org_id
+  // `--org` (not a positional org_id
   // like rename/payout-wallet above) goes through resolveOrg's SHAPE
   // validation (a real UUID) — "org_gate1" fails that locally, so this needs
   // the same UUID-shaped fixture `org use` below already established.
@@ -255,13 +255,13 @@ export const COMMAND_MANIFEST = [
   { path: ["claims", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["claims", "release"], positionals: [p("claim_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["clm_1"], runStyle: "sub" },
 
-  // ── gitvault — RETIRED (repo-surface-consolidation, design D7) ──────────
-  // No manifest entries: `cli/lib/gitvault.mjs`'s dispatcher retired, and
-  // every `gitvault <verb>` now answers a structural COMMAND_MOVED (or, for
-  // `push`/`reconcile`, COMMAND_REMOVED) redirect that dispatches nothing —
-  // see RESERVED_SUBCOMMANDS below, and "gitvault" in SKIPPED_FAMILIES.
+  // ── gitvault — no manifest entries ──────────────────────
+  // `cli/lib/gitvault.mjs`'s dispatcher handles every `gitvault <verb>` and
+  // answers a structural COMMAND_MOVED (or, for `push`/`reconcile`,
+  // COMMAND_REMOVED) redirect that dispatches nothing — see
+  // RESERVED_SUBCOMMANDS below, and "gitvault" in SKIPPED_FAMILIES.
 
-  // ── repos (repo-surface-consolidation — the consolidated 12-verb family) ─
+  // ── repos (the consolidated 12-verb family) ─
   // Every verb needs a real principal keystore and, for most, an allocated
   // repo and a local git working tree, so the gate runs structural checks
   // only — an in-process behavioral run would either no-op against the
@@ -269,23 +269,24 @@ export const COMMAND_MANIFEST = [
   { path: ["repos", "create"], positionals: [p("name", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "provisions a project, allocates a repo, and scaffolds a real git remote into cwd" },
   { path: ["repos", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the live bulk vaults-by-org route, or falls back to a live per-project walk" },
   { path: ["repos", "view"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the local principal keystore and the live repo record" },
-  // repo-surface-consolidation D2 (`gh repo rename`): absorbs the old
-  // `repos name` — same claim/rename, `--repo`/`--project` addressing added.
+  // (`gh repo rename`): claims/renames the per-org-unique address-form
+  // name, with `--repo`/`--project` addressing.
   { path: ["repos", "rename"], positionals: [p("new_name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "claims a per-org-unique repo name against a live project" },
-  { path: ["repos", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [], runStyle: "sub", skipBehavioral: "irreversibly deletes a project after reading its live non-repo-resource state and vault generation count (design D9)" },
+  { path: ["repos", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [], runStyle: "sub", skipBehavioral: "irreversibly deletes a project after reading its live non-repo-resource state and vault generation count" },
   { path: ["repos", "snapshot"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "captures the cwd git working tree and publishes a signed head" },
   { path: ["repos", "policy"], positionals: [p("repos_policy")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["required"], runStyle: "sub", skipBehavioral: "owner + step-up mutation of the live project's activation policy" },
-  // design D4 — ONE flag-driven verb; `<destination>` is a real attribute
-  // (not a sub-verb literal like the old `mirror set/remove/...`), so this
-  // stays a single manifest entry.
+  // ONE flag-driven verb; `<destination>` is a real attribute (not a
+  // sub-verb literal), so this stays a single manifest entry.
   { path: ["repos", "mirror"], positionals: [p("destination", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads/writes mirror destination config beside the keystore and may move real bytes into a customer-owned bucket" },
   { path: ["repos", "fsck"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "walks the live head chain and materializes the ref map against the keystore's local pins" },
   { path: ["repos", "gc"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "publishes a checkpoint under a maintenance lease and materializes the live vault head to enumerate retention roots" },
-  // `access repair` is a nested sub-verb literal (same shape the old
-  // `gitvault mirror set/remove/...` used) — two manifest entries, one
-  // dispatched `run("access", ...)` case in repos.mjs, matching precedent.
+  // `access repair`/`revoke-key`/`declare-exposure` are nested sub-verb
+  // literals — one manifest entry each, all dispatched through the ONE
+  // `run("access", ...)` case in repos.mjs.
   { path: ["repos", "access"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the live org encryption-key directory + vault envelope recipients" },
-  { path: ["repos", "access", "repair"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "always refuses — gated on gitvault-human-envelopes' epoch-rotation work, not shipped yet" },
+  { path: ["repos", "access", "repair"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--recipient-state-version", "0", "--recipient-revocation-version", "0"], runStyle: "sub", skipBehavioral: "owner+step-up-gated epoch rotation (D193-D203, rev 42) — samples a fresh epoch key and re-seals a live vault's recipients" },
+  { path: ["repos", "access", "revoke-key"], positionals: [p("principal_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["prin_00000000000000000000000000000000"], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares a recipient's key revoked (org-scoped watermark) and drives a real epoch rotation off it" },
+  { path: ["repos", "access", "declare-exposure"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "owner+step-up-gated: declares this vault's epoch secret exposed, forcing every subsequent ordinary push to refuse until a rotation lands" },
   { path: ["repos", "recover"], positionals: [p("source")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket", "--out", "__SCRATCH_DIR__/recover-out"], runStyle: "sub", skipBehavioral: "materializes a git repository from a mirror source, offline, with no server call" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
@@ -439,7 +440,7 @@ export const COMMAND_MANIFEST = [
   { path: ["service", "health"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["cache", "inspect"], positionals: [p("url")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["https://example.com/"] },
   { path: ["cache", "invalidate"], positionals: [p("url", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--all", "--host", "example.com"] },
-  // projectScoped (kychee-com/run402#566): --project targets the gitvault
+  // projectScoped: --project targets the gitvault
   // check only (see doctor.mjs's own HELP) — every other check stays
   // wallet/machine-wide, but the gate's contract is "accepts --project
   // without rejecting it," which this satisfies.
@@ -461,13 +462,13 @@ export const SKIPPED_FAMILIES = {
   // Split into `deliveries` / `contacts` / `subscriptions`; every subcommand
   // answers COMMAND_REMOVED naming its successor.
   "notifications": "reserved group; split by legible-cli-surface",
-  // repo-surface-consolidation D7: the dispatcher retired. Every
-  // `gitvault <verb>` answers COMMAND_MOVED/COMMAND_REMOVED (see
-  // RESERVED_SUBCOMMANDS below for the per-verb list) — the family stays
-  // dispatched in cli.mjs (so the redirect fires instead of UNKNOWN_COMMAND)
-  // but has zero manifest entries, since a redirect dispatches nothing.
+  // The gitvault dispatcher answers COMMAND_MOVED/COMMAND_REMOVED for every
+  // `gitvault <verb>` (see RESERVED_SUBCOMMANDS below for the per-verb list)
+  // — the family stays dispatched in cli.mjs (so the redirect fires instead
+  // of UNKNOWN_COMMAND) but has zero manifest entries, since a redirect
+  // dispatches nothing.
   "gitvault": "retired; every subcommand answers COMMAND_MOVED/COMMAND_REMOVED naming its `repos`/git successor",
-  // `repo` singular resolves identically to `repos` (design D1) — same
+  // `repo` singular resolves identically to `repos` — same
   // module, same case block in cli.mjs, so it needs no manifest of its own.
   "repo": "alias for `repos`, resolves identically (design D1)",
 };
@@ -481,8 +482,8 @@ export const SKIPPED_FAMILIES = {
  * belongs in no capability mapping, so the inventory gate must not demand one.
  *
  * The family-level equivalent is SKIPPED_FAMILIES above. This exists because
- * legible-cli-surface retired four spellings INSIDE a family rather than a
- * whole family, which the family list could not express.
+ * some spellings are retired INSIDE a family rather than as a whole family,
+ * which the family list cannot express.
  */
 export const RESERVED_SUBCOMMANDS = {
   "rooms:who": "renamed to `rooms join` — an interrogative must not name a write",
@@ -495,7 +496,7 @@ export const RESERVED_SUBCOMMANDS = {
   "rooms:get": "moved to `messages get` — the verb acts on a message",
   "rooms:ack": "moved to `messages ack` — the verb acts on a message",
   "escalations:contacts": "merged into `contacts` — the ladder and Telegram channels are one question",
-  // repo-surface-consolidation D7: every `gitvault <verb>` spelling. Nine
+  // Every `gitvault <verb>` spelling. Nine
   // answer COMMAND_MOVED naming their `repos` successor; `push` and
   // `reconcile` answer COMMAND_REMOVED (no equivalent successor for either —
   // `push`'s one-release alias window is over, `reconcile` was a workaround

package/lib/deploy-v2.mjs

@@ -41,6 +41,7 @@ import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.
 import { withAutoApprove } from "./operator.mjs";
 import { editRequestAction, nextAction, retryAction } from "./next-actions.mjs";
 import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
+import { sdkStats, printVerboseStats } from "./stats.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -106,9 +107,16 @@ Options:
   --final-only            Alias for --quiet; final success/error envelope is still preserved
   --allow-warning <code>  Continue past this reviewed warning code (repeatable)
   --allow-warnings        Continue past plan warnings that require confirmation
+  --allow-dirty           gitvault-required projects only: capture a dirty
+                          work tree as-is instead of refusing
+                          SNAPSHOT_DIRTY_TREE. The result discloses exactly
+                          what was swept in, printed to stderr too — even
+                          this override never captures silently.
+  -v, --verbose           Print one stderr summary line of this call's
+                          request stats (round trips, wire time, bytes)
 
 Output:
-  stdout: { "release_id": "rel_...", "operation_id": "op_...", "urls": {...}, "warnings": [...] }
+  stdout: { "release_id": "rel_...", "operation_id": "op_...", "urls": {...}, "warnings": [...], "stats": {...} }
   stderr: one JSON event per line (suppressed with --quiet or --final-only)
 
 Secrets:
@@ -654,8 +662,10 @@ function parseApplyArgs(args) {
     planFingerprint: null,
     rehearsalTeardown: "keep",
     commitAfterRehearse: false,
+    allowDirty: false,
+    verbose: false,
   };
-  const allowedFlags = ["--manifest", "--spec", "--dir", "--project", "--quiet", "--final-only", "--json", "--allow-warning", "--allow-warnings", "--check", "--print-spec", "--plan", "--rehearse", "--teardown", "--commit", "--require-plan", "--plan-fingerprint", "--help", "-h"];
+  const allowedFlags = ["--manifest", "--spec", "--dir", "--project", "--quiet", "--final-only", "--json", "--allow-warning", "--allow-warnings", "--check", "--print-spec", "--plan", "--rehearse", "--teardown", "--commit", "--require-plan", "--plan-fingerprint", "--allow-dirty", "-v", "--verbose", "--help", "-h"];
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -723,6 +733,8 @@ function parseApplyArgs(args) {
     if (arg === "--quiet" || arg === "--final-only") { opts.quiet = true; continue; }
     if (arg === "--json") { continue; }
     if (arg === "--allow-warnings") { opts.allowWarnings = true; continue; }
+    if (arg === "--allow-dirty") { opts.allowDirty = true; continue; }
+    if (arg === "-v" || arg === "--verbose") { opts.verbose = true; continue; }
     if (arg === "--check") { setApplyMode(opts, "check", "--check"); continue; }
     if (arg === "--print-spec") { setApplyMode(opts, "printSpec", "--print-spec"); continue; }
     if (arg === "--plan") { setApplyMode(opts, "plan", "--plan"); continue; }
@@ -1247,9 +1259,10 @@ async function applyCmd(args) {
     // not `required` runs the same `apply()` this line always ran, with the
     // same options object; a `required` one captures, publishes, mints an
     // activation token, and commits with it.
+    const sdk = getSdk(sdkOpts);
     const outcome = await withAutoApprove(() =>
       applyWithGitvault({
-        sdk: getSdk(sdkOpts),
+        sdk,
         spec: releaseSpec,
         apply: {
           onEvent: makeStderrEventWriter(opts.quiet),
@@ -1259,13 +1272,15 @@ async function applyCmd(args) {
           ...(requiredPlan ? { requiredPlan } : {}),
         },
         target: isCoreApiTarget() ? "core" : "cloud",
+        ...(opts.allowDirty ? { allowDirty: true } : {}),
         // The `gitvault_commit` line is printed ALWAYS, and to stderr, so
         // `run402 deploy apply | jq` stays clean (the pipe contract).
         onCommitLine: (line) => { if (!opts.quiet) process.stderr.write(`${line}\n`); },
       }),
     );
     if (!outcome.gitvault) {
-      console.log(JSON.stringify(outcome.deploy, null, 2));
+      console.log(JSON.stringify({ ...outcome.deploy, stats: sdkStats(sdk) }, null, 2));
+      printVerboseStats(opts.verbose, sdk);
       return;
     }
     const vaulted = outcome.gitvault;
@@ -1290,6 +1305,7 @@ async function applyCmd(args) {
       ...("reconcile_recipients" in vaulted ? { reconcile_recipients: vaulted.reconcile_recipients } : {}),
       next_actions: vaulted.next_actions,
       deploy: outcome.deploy,
+      stats: sdkStats(sdk),
     }, null, 2));
     // Design D6: the mirror result is reported BESIDE the vault outcome
     // above, on its own stderr line — a mirror failure never blocks the
@@ -1299,6 +1315,13 @@ async function applyCmd(args) {
     } else if (vaulted.mirror_push?.outcome === "failed") {
       console.error(`mirror: dual-push FAILED (deploy is unaffected) — ${vaulted.mirror_push.error ?? "see mirror_push.summary.errors"}`);
     }
+    // Dirty-tree disclosure (Tal's decision, "help people not make
+    // mistakes"): even an explicit --allow-dirty override never captures
+    // silently — name every modified/staged and untracked-not-ignored path
+    // that got swept into this deploy's capture.
+    for (const p of vaulted.snapshot?.modified_captured ?? []) console.error(`captured (modified): ${p}`);
+    for (const p of vaulted.snapshot?.untracked_captured ?? []) console.error(`captured (untracked): ${p}`);
+    printVerboseStats(opts.verbose, sdk);
     // A non-activating outcome is a failed deploy even though it resolved
     // rather than threw: the five outcomes are a result type, not an error
     // channel, so the exit code has to carry the verdict.
@@ -1400,16 +1423,13 @@ const CI_DEPLOY_ERROR_GUIDANCE = {
 };
 
 /**
- * The gitvault advisory rewrite is RETIRED (change `gitvault-deploy-lane`,
- * design D4). `GITVAULT_DEPLOY_LANE = "unsupported"` and the client-side
- * rewrite of `GITVAULT_CLIENT_UPGRADE_REQUIRED` existed only for as long as no
- * published client could satisfy `gitvault_policy: required`. This one can:
- * `applyCmd` deploys through `applyWithGitvault`, which declares
- * `{capture_id, snapshot_oid_hmac}` at plan time and presents an activation
- * token at commit. The gateway's envelope — `upgrade_client` first, then
- * `grandfather_policy` — is now TRUE as written, so it is relayed untouched;
- * re-authoring it here would be the client lying in the opposite direction.
- * `cli-deploy-gitvault-lane.test.mjs` is the successor gate.
+ * The gateway's envelope for gitvault deploy errors — `upgrade_client` first,
+ * then `grandfather_policy` — is relayed untouched: `applyCmd` deploys
+ * through `applyWithGitvault`, which declares `{capture_id,
+ * snapshot_oid_hmac}` at plan time and presents an activation token at
+ * commit, satisfying `gitvault_policy: required`, so no client-side rewrite
+ * of the envelope is needed. `cli-deploy-gitvault-lane.test.mjs` is the gate
+ * for this behavior.
  */
 function reportDeployApplyError(err, useGithubActionsOidc) {
   const warningEnhanced = enhanceDeployWarningError(err);

package/lib/doctor.mjs

@@ -568,6 +568,11 @@ export async function run(sub, args = []) {
           pending_overrides: gv.pending_overrides,
           pins: gv.pins,
           remote: gv.remote,
+          // dogfood item 2: `null` (unknown) or <= 1 means the single-principal
+          // V0-A terminal-loss statement below is honest; >= 2 means the SDK
+          // already proved a second covering recipient, so the hint switches
+          // to the durability sentence instead of the terminal-loss claim.
+          covering_recipients: gv.covering_recipients ?? null,
         };
         const gaps = [];
         // The one that actually breaks the next deploy: the project demands a
@@ -632,7 +637,9 @@ export async function run(sub, args = []) {
           value: gaps.length > 0 ? { ...value, gaps } : value,
           hint: gv.vault === null
             ? `No vault for this project (that is a normal shape). Allocate one with 'run402 repos create --project <id>'. Keystore: ${gv.keystore.root}`
-            : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`,
+            : gv.durability_statement
+              ? `Back up ${gv.keystore.root} anyway — ${gv.durability_statement} (covering_recipients: ${gv.covering_recipients})`
+              : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`,
         });
       } catch (err) {
         // A gateway without gitvault, an unreachable API, or a project this

package/lib/gitvault-target.mjs

@@ -1,19 +1,17 @@
 /**
  * Shared "which vault does this repo mean" resolution for `run402 gitvault`
- * and `run402 doctor`'s gitvault check (repo-first-onramp follow-up,
- * kychee-com/run402#559's design gap): gitvault verbs were purely
- * active-project-scoped even when run standing inside a repository that
- * already names its own vault via a pinned repo id or a run402/origin
- * remote — git muscle memory says a command run inside a repo acts on THAT
- * repo, and a stale active-project pointer silently targeted a DIFFERENT
- * one instead (GITVAULT_ACCESS_DENIED, or worse, a silently WRONG vault).
+ * and `run402 doctor`'s gitvault check. When a verb runs standing inside a
+ * repository that already names its own vault via a pinned repo id or a
+ * run402/origin remote, targeting prefers that repo over the active-project
+ * pointer — git muscle memory says a command run inside a repo acts on THAT
+ * repo.
  *
  * Targeting order for a verb run standing inside a git repository, highest
  * first:
  *   1. an explicit --repo/--project flag (owned by each call site — this
  *      module supplies only the fallback chain beneath it, plus the
  *      mismatch warning against tier 3)
- *   2. the 4.38.0 pin (`r402.repoId` in local git config) — addresses the
+ *   2. the pinned `r402.repoId` in local git config — addresses the
  *      vault by repo_id directly, no network read at all
  *   3. the repo's run402/origin remote address — id-form is parsed
  *      directly out of the address string (free, no network); slug-form is
@@ -24,7 +22,7 @@
  *   5. the profile's active project
  *
  * Outside a repository (or when repo detection itself fails), only tiers 4
- * and 5 apply — unchanged from before this module existed.
+ * and 5 apply.
  *
  * ARCHITECTURAL NOTE: this is CLI-edge policy (which flag/env/file wins),
  * not gitvault protocol behavior — the same class of concern

package/lib/gitvault.mjs

@@ -1,18 +1,17 @@
 /**
- * `run402 gitvault` — RETIRED (repo-surface-consolidation, design D7).
+ * `run402 gitvault` — retired from the CLI; every spelling answers a
+ * structured error naming its `repos`/git successor.
  *
- * The 19-command dispatcher this module used to hold is gone. Every old
- * spelling now answers a proper stderr JSON error envelope: typed
+ * Every spelling answers a proper stderr JSON error envelope: typed
  * `next_actions`, non-zero exit, EMPTY stdout — never silence, never new
  * behavior. Renamed verbs answer `COMMAND_MOVED` naming their `repos`
  * successor; verbs with no behavioral successor answer `COMMAND_REMOVED`
- * (never a `COMMAND_MOVED` that would lie about equivalence — design
- * D7/D10). The freed spellings are RESERVED for one release, never
- * re-pointed at different behavior — the `rooms`→`messages` precedent.
+ * (never a `COMMAND_MOVED` that would lie about equivalence). The freed
+ * spellings are never re-pointed at different behavior.
  *
  * `gitvault` itself survives only as protocol/infrastructure language: the
- * SDK keeps `r.gitvault.*` (design D1 — "gitvault is what the thing IS;
- * repos is what the user HAS"). This module's one surviving export,
+ * SDK keeps `r.gitvault.*` ("gitvault is what the thing IS; repos is what
+ * the user HAS"). This module's one surviving export,
  * `printKeystoreLocation`, is a shared print helper `cli/lib/repos.mjs`
  * still composes — moving it there instead would make repos.mjs restate
  * logic this file already owns for zero benefit.

package/lib/next-actions.mjs

@@ -70,12 +70,15 @@ export function deployAction() {
 /**
  * `repos create` (and `gitvault init`) on an org with no claimed slug: the
  * response's `address: null` had no pointer to WHY, or to the named-addressing
- * feature at all (kychee-com/run402#560). One-time $1 fee, owner-only.
+ * feature at all (kychee-com/run402#560). Owner-only. Wording deliberately
+ * omits a price: the first slug per org is free, and renames/re-claims cost
+ * $1 — a gateway change lands the fee separately, so this stays true under
+ * both the old and new pricing rule.
  */
 export function claimOrgSlugAction() {
   return nextAction("claim_org_slug", {
     command: "run402 org slug <slug>",
-    why: "This organization has no claimed slug yet, so its repos have no run402::<slug>/<name> address. One-time $1, owner-only.",
+    why: "This organization has no claimed slug yet, so its repos have no run402::<slug>/<name> address. Owner-only.",
   });
 }
 

package/lib/notifications.mjs

@@ -1,18 +1,14 @@
 /**
- * `run402 notifications` — RETIRED (legible-cli-surface).
- *
- * The group was two nouns in one coat: `list`/`get` read delivery RECORDS
- * while `preferences`/`channels`/`rules` were the CONFIGURATION producing
- * them. It has been split along that line:
+ * `run402 notifications` — tombstone dispatcher. Delivery RECORDS and the
+ * CONFIGURATION producing them live under separate nouns:
  *
  *   notifications list|get      -> deliveries list|get
  *   notifications channels      -> contacts        (merged with escalations contacts)
  *   notifications rules         -> subscriptions
  *   notifications preferences   -> contacts preferences
  *
- * Reserved, not aliased (design D3): each subcommand names its successor so
- * one failed call teaches the new model, where an alias would teach the old
- * one forever.
+ * Reserved, not aliased: each subcommand names its successor so one failed
+ * call teaches the new model, where an alias would teach the old one forever.
  */
 import { fail } from "./sdk-errors.mjs";
 import { hasHelp } from "./argparse.mjs";

package/lib/operator.mjs

@@ -14,7 +14,7 @@
  *
  * Agent-first: JSON to stdout. `login` additionally prints the verification URL
  * + user code to stderr (human-in-the-loop) and degrades gracefully when not a
- * TTY. Gated on the gateway device-auth bridge (kychee-com/run402-private#443).
+ * TTY. Gated on the gateway device-auth bridge.
  */
 
 import { setTimeout as sleep } from "node:timers/promises";

package/lib/org.mjs

@@ -438,9 +438,9 @@ async function payoutWallet(args) {
 }
 
 /**
- * `run402 org slug <slug>` — claim or rename the org's address-form slug
- * (repo-first-onramp design D6). Owner-only, and a genesis claim spends a
- * one-time claim fee — this is a PAID, side-effecting mutation, so it
+ * `run402 org slug <slug>` — claim or rename the org's address-form slug.
+ * Owner-only, and a genesis claim spends a one-time claim fee — this is a
+ * PAID, side-effecting mutation, so it
  * requires `Idempotency-Key`; the SDK generates one client-side when
  * `--idempotency-key` is omitted, so a retried call after a dropped response
  * can never double-bill.