run402 4.39.1 → 4.41.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-surface-consolidation; `repo` singular resolves identically). `run402 gitvault <verb>` is RETIRED — every old spelling now 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 (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.
 
 ### 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)
+  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/assets.mjs

@@ -28,7 +28,7 @@ import {
 import { basename, dirname, resolve as resolvePath } from "node:path";
 import { pipeline } from "node:stream/promises";
 
-import { resolveProjectId } from "./config.mjs";
+import { resolveProjectIdAllowingLegacyEnv } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, failUnknownSubcommand } from "./argparse.mjs";
@@ -472,10 +472,9 @@ function computeDestKey(filePath, keyOpt) {
   return keyOpt;
 }
 
-async function put(projectId, argv) {
+async function put(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
 
   if (opts.positional.length === 0) die("At least one file path is required");
   if (opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
@@ -499,10 +498,9 @@ async function put(projectId, argv) {
 // get
 // ---------------------------------------------------------------------------
 
-async function get(projectId, argv) {
+async function get(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob get expects exactly one key");
   if (!opts.output) die("--output <file> required");
@@ -526,10 +524,9 @@ async function get(projectId, argv) {
 // ls
 // ---------------------------------------------------------------------------
 
-async function ls(projectId, argv) {
+async function ls(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
 
   try {
     const data = await getSdk().assets.ls(resolvedId, {
@@ -552,10 +549,9 @@ async function ls(projectId, argv) {
 // rm
 // ---------------------------------------------------------------------------
 
-async function rm(projectId, argv) {
+async function rm(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob rm expects exactly one key");
   const key = opts.positional[0];
@@ -572,10 +568,9 @@ async function rm(projectId, argv) {
 // sign
 // ---------------------------------------------------------------------------
 
-async function diagnose(projectId, argv) {
+async function diagnose(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("URL required");
   if (opts.positional.length > 1) die("blob diagnose expects exactly one URL");
   const url = opts.positional[0];
@@ -623,10 +618,9 @@ function toCliDiagnoseEnvelope(env) {
   };
 }
 
-async function sign(projectId, argv) {
+async function sign(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob sign expects exactly one key");
   const key = opts.positional[0];
@@ -676,14 +670,13 @@ export async function run(sub, args) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
-  const defaultProject = process.env.RUN402_PROJECT ?? null;
   switch (sub) {
-    case "put":      await put(defaultProject, args); break;
-    case "get":      await get(defaultProject, args); break;
-    case "ls":       await ls(defaultProject, args); break;
-    case "rm":       await rm(defaultProject, args); break;
-    case "sign":     await sign(defaultProject, args); break;
-    case "diagnose": await diagnose(defaultProject, args); break;
+    case "put":      await put(args); break;
+    case "get":      await get(args); break;
+    case "ls":       await ls(args); break;
+    case "rm":       await rm(args); break;
+    case "sign":     await sign(args); break;
+    case "diagnose": await diagnose(args); break;
     default:
       failUnknownSubcommand("assets", sub);
   }

package/lib/cdn.mjs

@@ -13,7 +13,7 @@
  * are bound to a SHA at upload time and never previously cached.
  */
 
-import { resolveProjectId } from "./config.mjs";
+import { resolveProjectIdAllowingLegacyEnv } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
@@ -91,10 +91,9 @@ function parseArgs(args) {
   return opts;
 }
 
-async function waitFresh(projectId, argv) {
+async function waitFresh(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("URL required");
   const url = opts.positional[0];
   if (!opts.sha) die("--sha is required");
@@ -136,10 +135,9 @@ export async function run(sub, args) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
-  const defaultProject = process.env.RUN402_PROJECT ?? null;
   switch (sub) {
     case "wait-fresh":
-      await waitFresh(defaultProject, args);
+      await waitFresh(args);
       break;
     default:
       failUnknownSubcommand("cdn", sub);

package/lib/command-manifest.mjs

@@ -255,32 +255,38 @@ 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 — 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.
+
+  // ── repos (repo-surface-consolidation — 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" },
-
-  // ── 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" },
+  // repo-surface-consolidation D2 (`gh repo rename`): absorbs the old
+  // `repos name` — same claim/rename, `--repo`/`--project` addressing added.
+  { 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", "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.
+  { 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.
+  { 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 ─────────────────────────────────────────────────────────────────
@@ -455,6 +461,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",
+  // 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.
+  "gitvault": "retired; every subcommand answers COMMAND_MOVED/COMMAND_REMOVED naming its `repos`/git successor",
+  // `repo` singular resolves identically to `repos` (design D1) — same
+  // module, same case block in cli.mjs, so it needs no manifest of its own.
+  "repo": "alias for `repos`, resolves identically (design D1)",
 };
 
 /**
@@ -480,4 +495,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",
+  // repo-surface-consolidation D7: 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/config.mjs

@@ -139,6 +139,36 @@ export function resolveProjectId(id) {
   return projectId;
 }
 
+/**
+ * `resolveProjectId`, but also honors the deprecated `RUN402_PROJECT` alias
+ * as a last-resort fallback.
+ *
+ * `RUN402_PROJECT_ID` is the canonical env var everywhere in the CLI — it's
+ * what `resolveProjectId`, `run402 doctor`, `org-context.mjs`, and every
+ * other project-scoped command read. Two commands (`cdn wait-fresh` and
+ * every `assets` subcommand) historically read the DIFFERENT, undocumented
+ * `RUN402_PROJECT` instead, so exporting the canonical `RUN402_PROJECT_ID`
+ * and running one of those two commands was a silent no-op: the export did
+ * nothing, and resolution quietly fell through to the active project.
+ *
+ * Precedence, highest first: an explicit `id` (e.g. `--project`) >
+ * `RUN402_PROJECT_ID` > the deprecated `RUN402_PROJECT` alias > the active
+ * project. The alias is only ever consulted when `RUN402_PROJECT_ID` is
+ * unset AND no explicit id was given — so it never silently overrides the
+ * canonical var or a flag. When the alias is what actually resolves the
+ * project, exactly one deprecation line goes to stderr (never stdout — the
+ * pipe contract keeps stdout pure JSON).
+ */
+export function resolveProjectIdAllowingLegacyEnv(id) {
+  if (!id && !process.env.RUN402_PROJECT_ID && process.env.RUN402_PROJECT) {
+    process.stderr.write(
+      "warning: RUN402_PROJECT is deprecated and will be removed; set RUN402_PROJECT_ID instead.\n",
+    );
+    return resolveProjectId(process.env.RUN402_PROJECT);
+  }
+  return resolveProjectId(id);
+}
+
 // Re-export core keystore functions for direct use
 export {
   configureApiBase,

package/lib/deploy-v2.mjs

@@ -1281,9 +1281,24 @@ async function applyCmd(args) {
       ...("generation" in vaulted ? { generation: vaulted.generation } : {}),
       ...("push_error" in vaulted ? { push_error: vaulted.push_error } : {}),
       ...("deploy_error" in vaulted ? { deploy_error: vaulted.deploy_error } : {}),
+      // Design D5/D6 (gitvault-human-envelopes task 4.1 + gitvault-mirror):
+      // present only when this deploy landed a new generation — the SDK
+      // omits both fields entirely on the other three outcomes rather than
+      // faking a `skipped_*` value for something that never had a chance to
+      // run. See `Gitvault.deploy`'s doc comment (sdk/src/namespaces/gitvault.ts).
+      ...("mirror_push" in vaulted ? { mirror_push: vaulted.mirror_push } : {}),
+      ...("reconcile_recipients" in vaulted ? { reconcile_recipients: vaulted.reconcile_recipients } : {}),
       next_actions: vaulted.next_actions,
       deploy: outcome.deploy,
     }, 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
+    // deploy (mirrors `run402 gitvault snapshot`'s reporting).
+    if (vaulted.mirror_push?.outcome === "pushed") {
+      console.error(`mirror: pushed generation ${vaulted.generation} (${vaulted.mirror_push.summary?.objects_copied ?? 0} object(s) copied)`);
+    } 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"}`);
+    }
     // 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.

package/lib/doctor.mjs

@@ -575,13 +575,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
@@ -593,12 +593,45 @@ export async function run(sub, args = []) {
         // Echoed exactly as the SDK reported them — including the
         // doctor-persistent `grandfathered` advisory it owns.
         for (const w of gv.warnings ?? []) gaps.push(`${w.kind}: ${w.message}`);
+
+        // gitvault-mirror-and-recover task 4.3: mirror currency, reported
+        // ALONGSIDE (never in place of) the deploy-related gaps above, and
+        // never blocking `run402 deploy`'s own gate — the vault lane's
+        // outcome is unaffected regardless of mirror state (design D6).
+        // `mirror_currency` mirrors `mirror status`'s own tri-state:
+        // `current` / `stale` / `unknown` (mirror unreachable or vault
+        // unread) only STALE is actionable enough to become a warning; NO
+        // mirror configured is a purely informational, ungated advisory —
+        // most vaults have never opted in, and that is a normal shape.
+        if (gv.vault !== null && value.repo_id) {
+          try {
+            const mirrorStatus = await getSdk().gitvault.mirrorStatus({ repo_id: value.repo_id });
+            value.gitvault_mirror = {
+              configured: mirrorStatus.configured,
+              destination: mirrorStatus.destination,
+              mirrored_generation: mirrorStatus.mirrored_generation,
+              newest_generation: mirrorStatus.newest_generation,
+              is_current: mirrorStatus.is_current,
+              validity_not_freshness: mirrorStatus.validity_not_freshness,
+              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 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}`);
+            }
+          } catch {
+            // Best-effort: a mirror status read failing is never a doctor
+            // failure, and never touches the deploy-related gaps above.
+          }
+        }
+
         checks.push({
           name: "gitvault",
           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}`
+            ? `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.`,
         });
       } catch (err) {

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;