run402 4.40.0 → 4.42.0

package/README.md

@@ -52,7 +52,9 @@ For app manifests with `verify.http[]`, `up` runs HTTP checks after deploy. Fres
 
 For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeScript/JavaScript configs execute local code. Use `--check` for local-only import/normalize/file validation, `--print-spec` to inspect the normalized `ReleaseSpec`, `--plan` for a gateway-reviewed non-deploying plan, and `--require-plan <plan_id>` to apply only that reviewed intent. Warning flags are not used with `--require-plan`; the reviewed plan binds the exact warning/destructive set. Run402 Core skips Cloud allowance/tier prerequisites and fails closed when no Core project is selected.
 
-### Vault-only repos (zero deploy ceremony)
+### repos — host-blind encrypted git repos (zero deploy ceremony)
+
+One noun, twelve verbs (`repo` singular resolves identically). `run402 gitvault <verb>` answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
 
 ```bash
 run402 init                                   # once per machine
@@ -61,13 +63,14 @@ git push -u origin main                       # allocates the vault on first pus
 
 # or, one call: provision + allocate + scaffold, nothing deployed
 run402 repos create my-notes
+run402 repos view --human
 run402 repos list --org org_1a2b3c
-run402 repos delete prj_xyz --force           # refuses without --force while the vault holds generations
+run402 repos delete --project prj_xyz --force # refuses without --force while the vault holds generations
 ```
 
-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. `repos create|list|delete|name` and `gitvault`'s mutating verbs (`init`, `snapshot`, `policy`, `compact`, `prune`) are CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete). See `run402 gitvault --help` and `run402 repos --help` for the full surface, and the CLI reference's `gitvault` / `repos` sections for the terminal-loss statement and the progressive backup warning.
+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 name <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.
+**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/cli.mjs

@@ -32,7 +32,7 @@ SET UP — get an agent funded and entitled
 BUILD & SHIP — the app and everything it serves
   up          Provision/link/deploy the current app with SDK orchestration
   projects    Manage projects (provision, list, get, sql, delete)
-  repos       Vault-only hosted encrypted repos, zero deploy ceremony (create, list, delete)
+  repos       Host-blind encrypted git repos: create/view/list, snapshot/mirror/recover, fsck/gc/access/policy (repo aliases repos)
   deploy      Unified deploy operations (requires active tier)
   apply       Alias for deploy apply; supports --rehearse for migration rehearsal
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
@@ -84,7 +84,7 @@ PLATFORM — everything else, and the things still finding a home
   transfer    Two-party project transfer (init, preview, list, accept, cancel)
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
-  gitvault    Host-blind encrypted Git remote (init/status/push/policy/compact/prune/verify/mirror/recover)
+  gitvault    RETIRED — moved to repos (repo-surface-consolidation); every spelling answers COMMAND_MOVED/COMMAND_REMOVED
   buzz        Buzz human/community/agent control-plane workflows
   apps        Browse and manage the app marketplace
   ai          AI translation and moderation tools
@@ -227,6 +227,14 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  // `repo` singular resolves identically to `repos` (design D1 — agents type
+  // what `gh repo` already taught them). Its own case block, not a
+  // fall-through, so cli-conventions-gate's per-line family scanner sees it.
+  case "repo": {
+    const { run } = await import("./lib/repos.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "apply": {
     const { runDeployV2 } = await import("./lib/deploy-v2.mjs");
     await runDeployV2("apply", [sub, ...rest].filter(Boolean));

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,52 +255,36 @@ 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 (host-blind encrypted Git remote) ───────────────────────────
-  // Every verb needs a real principal keystore, an allocated vault, and (for
-  // all but `status`) a local git working tree, so the gate runs structural
-  // checks only — an in-process behavioral run would either no-op against the
+  // ── 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 (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
   // universal `{}` fetch mock or touch the gate's own checkout.
-  { path: ["gitvault", "init"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "allocates a vault: mints key material on this machine and runs the six-stage creation journal" },
-  { path: ["gitvault", "status"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the local principal keystore and the live vault record" },
-  { path: ["gitvault", "snapshot"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "captures the cwd git working tree and publishes a signed head" },
-  // D5 (repo-first-onramp task 2.5): `push` is a deprecation-warning alias
-  // for `snapshot`, retained for exactly one release — same structural
-  // shape, same skip reason, so it stays covered by this gate too.
-  { path: ["gitvault", "push"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "deprecated alias for `snapshot` — captures the cwd git working tree and publishes a signed head" },
-  { path: ["gitvault", "policy"], positionals: [p("gitvault_policy")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["required"], runStyle: "sub", skipBehavioral: "owner + step-up mutation of the live project's activation policy" },
-  { path: ["gitvault", "compact"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "takes a maintenance lease and builds a checkpoint from the local repository" },
-  { path: ["gitvault", "prune"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "materializes the live vault head to enumerate retention roots" },
-  { path: ["gitvault", "verify"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "walks the live head chain against the keystore's authenticated pin" },
-  { path: ["gitvault", "reconcile"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the live org encryption-key directory + vault envelope recipients, and may publish new key_envelope objects" },
-
-  // ── gitvault mirror (gitvault-mirror-and-recover) ────────────────────────
-  // The customer-owned ciphertext mirror — client-side only, never a server
-  // call except `sync` (lists the live vault's objects) and `status`/`verify`
-  // (a keyless read against the mirror + one live vault-record read). All
-  // five need a real keystore + (for anything but `remove`) a configured
-  // mirror destination, so — same as the gitvault family above — the gate
-  // runs structural checks only.
-  { path: ["gitvault", "mirror", "set"], positionals: [p("destination")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket"], runStyle: "sub", skipBehavioral: "writes mirror destination config beside the keystore (client-side only)" },
-  { path: ["gitvault", "mirror", "remove"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "removes mirror destination config beside the keystore (client-side only)" },
-  { path: ["gitvault", "mirror", "status"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the configured mirror + the live vault record's newest_generation" },
-  { path: ["gitvault", "mirror", "sync"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "lists the live vault's stored objects and reconciles them against the configured mirror" },
-  { path: ["gitvault", "mirror", "verify"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "keyless discovery + chain verification against the configured mirror; touches no key material" },
-
-  // ── gitvault recover (gitvault-mirror-and-recover, design D4) ────────────
-  // `r402s-recover`: offline, no server call at all — reads only from the
-  // mirror source named on the command line. Not project-scoped (the source
-  // URL, not the active project, addresses the vault to recover).
-  { path: ["gitvault", "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" },
-
-  // ── repos (vault-only porcelain, repo-first-onramp D8, task 2.6) ────────
-  // `create` writes real git state into cwd and allocates a vault; `list`
-  // and `delete` read/mutate the live gitvault record — same structural-
-  // checks-only rationale as the gitvault family just above.
-  { path: ["repos", "create"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "provisions a project, allocates a vault, and scaffolds a real git remote into cwd" },
-  { path: ["repos", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "cross-references live projects against their live gitvault status, one call per project" },
-  { path: ["repos", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [], runStyle: "sub", skipBehavioral: "irreversibly deletes a project after reading its live vault generation count" },
-  // repo-first-onramp task 4.2 (design D6): explicit address-form name claim.
-  { path: ["repos", "name"], positionals: [p("name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "claims a per-org-unique repo name against a live project" },
+  { 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" },
+  // (`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" },
+  { 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" },
+  // 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 — two manifest entries,
+  // one dispatched `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", "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" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────
@@ -453,7 +437,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.
@@ -475,6 +459,15 @@ 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",
+  // 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` — same
+  // module, same case block in cli.mjs, so it needs no manifest of its own.
+  "repo": "alias for `repos`, resolves identically (design D1)",
 };
 
 /**
@@ -486,8 +479,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",
@@ -500,4 +493,20 @@ 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",
+  // 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
+  // with no permanent replacement, only a read at `repos access`).
+  "gitvault:init": "moved to `repos create --project <id>`",
+  "gitvault:status": "moved to `repos view`",
+  "gitvault:snapshot": "moved to `repos snapshot`",
+  "gitvault:policy": "moved to `repos policy`",
+  "gitvault:compact": "moved to `repos gc`",
+  "gitvault:prune": "moved to `repos gc`",
+  "gitvault:verify": "moved to `repos fsck`",
+  "gitvault:mirror": "moved to `repos mirror`",
+  "gitvault:recover": "moved to `repos recover`",
+  "gitvault:push": "removed — its one-release deprecation-alias window is over; `git push` / `repos snapshot`",
+  "gitvault:reconcile": "removed — a workaround with no permanent successor; read `repos access` instead",
 };

package/lib/deploy-v2.mjs

@@ -1400,16 +1400,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
@@ -575,13 +580,13 @@ export async function run(sub, args = []) {
         if (gv.gitvault_policy === "required" && !gv.keystore.holds_repo_key) {
           gaps.push(
             "gitvault_policy is 'required' but this machine holds no key for the vault — a deploy from here is refused with GITVAULT_CLIENT_UPGRADE_REQUIRED. " +
-            "Run 'run402 gitvault init' (idempotent; resolves to the existing vault), or 'run402 gitvault policy grandfathered --reason <why>' to un-gate the project.",
+            "Run 'run402 repos create --project <id>' (idempotent; resolves to the existing repo), or 'run402 repos policy grandfathered --reason <why>' to un-gate the project.",
           );
         } else if (gv.gitvault_policy === "required" && !gv.keystore.can_sign) {
           gaps.push("gitvault_policy is 'required' and this keystore is read-only (no signing key) — it can verify but cannot publish the capture a deploy needs");
         }
         if (gv.pending_overrides > 0) {
-          gaps.push(`${gv.pending_overrides} unvaulted-override journal(s) are still open — run 'run402 gitvault push' to drain them`);
+          gaps.push(`${gv.pending_overrides} unvaulted-override journal(s) are still open — run 'run402 repos snapshot' to drain them`);
         }
         // `matches` is a TRI-STATE (kychee-com/run402#562): `false` alone is
         // a real mismatch. `null` (a slug-form remote not yet resolved on
@@ -616,7 +621,7 @@ export async function run(sub, args = []) {
               keystore_still_required: mirrorStatus.keystore_still_required,
             };
             if (!mirrorStatus.configured) {
-              value.gitvault_mirror.advisory = "no ciphertext mirror is configured for this vault — the exit ramp is opt-in; 'run402 gitvault mirror set <destination>' to configure one.";
+              value.gitvault_mirror.advisory = "no ciphertext mirror is configured for this vault — the exit ramp is opt-in; 'run402 repos mirror <destination>' to configure one.";
             } else if (mirrorStatus.is_current === false) {
               gaps.push(`the ciphertext mirror at ${mirrorStatus.destination} is STALE (mirrored generation ${mirrorStatus.mirrored_generation ?? "(none)"}, vault newest ${mirrorStatus.newest_generation ?? "(none)"}) — ${mirrorStatus.closing_command}`);
             }
@@ -631,8 +636,10 @@ export async function run(sub, args = []) {
           status: gaps.length > 0 ? "warning" : "ok",
           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 gitvault init'. Keystore: ${gv.keystore.root}`
-            : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`,
+            ? `No vault for this project (that is a normal shape). Allocate one with 'run402 repos create --project <id>'. Keystore: ${gv.keystore.root}`
+            : 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-scaffold.mjs

@@ -49,7 +49,7 @@ export async function scaffoldGitvaultRemote({ repoDir = process.cwd(), projectI
     const remote = await getSdk().gitvault.scaffoldRemote({ repo_dir: repoDir, org_id: resolvedOrgId, project_id: projectId });
     // `allocated: false` is stated, not left to be inferred: this is local
     // git only — no vault exists for the project yet (allocation happens
-    // lazily on first push, or explicitly via `run402 gitvault init`).
+    // lazily on first push, or explicitly via `run402 repos create --project <id>`).
     out.gitvault = { ...remote, allocated: false };
   } catch (err) {
     out.gitvault = null;

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