run402 4.36.0 → 4.37.0

package/README.md

@@ -52,6 +52,21 @@ 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)
+
+```bash
+run402 init                                   # once per machine
+git remote add origin run402::<org_id>/<project_id>
+git push -u origin main                       # allocates the vault on first push, publishes
+
+# or, one call: provision + allocate + scaffold, nothing deployed
+run402 repos create my-notes
+run402 repos list --org org_1a2b3c
+run402 repos delete 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` 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.
+
 ### Allowance
 
 ```bash

package/cli.mjs

@@ -32,6 +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)
   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)
@@ -221,6 +222,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "repos": {
+    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/git-remote-run402.mjs

@@ -19,6 +19,15 @@
  *   push [+]<src>:<dst>     → publish one atomic ref transaction
  *   option <name> <value>   → ok / unsupported, never a silent lie
  *
+ * LAZY ALLOCATION ON FIRST PUSH (design D2). `list` never creates anything —
+ * an unallocated vault reports as an empty ref set, exactly what a fresh
+ * repository looks like — but `push` does: `git push origin main` against a
+ * project whose vault does not exist yet runs the six-stage creation journal
+ * inline (`r.gitvault.openOrCreate`, the SDK-owned primitive), prints the
+ * one-shot recovery receipt and the keystore path to stderr, and then
+ * completes the push. One command, no prior `gitvault init`. `git ls-remote`
+ * / `fetch` stay pure reads and allocate nothing.
+ *
  * WHICH REPOSITORY (the fail-closed rule). `process.cwd()` is NOT the
  * repository. git identifies the repository with `GIT_DIR`, and during
  * `git clone` cwd is the directory clone was RUN FROM — routinely some other,
@@ -120,7 +129,11 @@ async function main(argv) {
     return 1;
   }
 
-  const target = { project_id: address.project_id };
+  // `org_id` rides in the parsed address (`run402::<org_id>/<project_id>`),
+  // so it costs nothing extra to carry — it is exactly what D2's lazy
+  // creation needs to allocate an unresolved vault from `runPush` below, with
+  // no separate lookup.
+  const target = { project_id: address.project_id, org_id: address.org_id };
   let verbosity = 1;
 
   /**
@@ -150,8 +163,61 @@ async function main(argv) {
   /** Open the vault lazily — `capabilities` and `option` must never touch the network. */
   const openVault = async (repoDir) => (await getSdk().gitvault.open(repoDir ? { ...target, repo_dir: repoDir } : target)).vault;
 
+  /** A 404/absent-vault refusal — the "nothing here yet" shape, never a genuine failure to mask. */
+  function isVaultNotFound(err) {
+    return err?.status === 404 || err?.code === "RESOURCE_NOT_FOUND" || err?.code === "ROUTE_NOT_FOUND";
+  }
+
+  /**
+   * Open the vault, allocating it first when it does not exist yet (D2). Used
+   * ONLY by `runPush` — `list`/`fetch` stay pure reads and never create
+   * anything (see `runList`'s own not-found handling below).
+   *
+   * Prints the one-shot recovery receipt and the keystore path to stderr the
+   * moment allocation happens, per the client-surface spec: an agent reads
+   * stderr, and the receipt is worth exactly as many copies as get kept.
+   */
+  async function openOrCreateVault(repoDir) {
+    const result = await getSdk().gitvault.openOrCreate({ ...target, repo_dir: repoDir });
+    if (!result.found && result.created) {
+      note("");
+      note(`vault ${result.handle.repo_id} allocated (genesis ${result.created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
+      note(JSON.stringify(result.created.recovery_receipt));
+      try {
+        const { getGitvaultKeystoreRoot } = await import("#sdk/node");
+        note(`keystore: ${getGitvaultKeystoreRoot()} — back this up; whole-machine or whole-keystore loss is terminal for vault history until human envelopes ship`);
+      } catch {
+        // Never let a diagnostic line fail a push that already allocated successfully.
+      }
+      try {
+        const { GITVAULT_ALLOCATION_POLICY_ADVISORY } = await import("./lib/gitvault-scaffold.mjs");
+        note(GITVAULT_ALLOCATION_POLICY_ADVISORY);
+      } catch {
+        // Same rule: advisory only, never fatal.
+      }
+      note("");
+    }
+    return result.handle.vault;
+  }
+
   async function runList() {
-    const state = await (await openVault()).materialize();
+    let state;
+    try {
+      state = await (await openVault()).materialize();
+    } catch (err) {
+      // An unallocated vault is not an error here: `list` is the read half of
+      // the protocol dance and must never create anything on its own (D2
+      // scopes lazy creation to `push`). Reporting it as an EMPTY ref set is
+      // exactly what a fresh repository looks like to git, and `push` still
+      // runs `list` first either way — this is what lets a first push land in
+      // one command instead of `list` failing the whole exchange before
+      // `push` ever gets a turn.
+      if (isVaultNotFound(err)) {
+        endBlock();
+        return;
+      }
+      throw err;
+    }
     const refs = state.refs ?? {};
     for (const ref of Object.keys(refs).sort()) out(`${refs[ref]} ${ref}`);
     const head = state.head_target;
@@ -198,7 +264,7 @@ async function main(argv) {
           ? null
           : (await hardenedGit(repoDir, ["rev-parse", "--verify", "--end-of-options", spec.src])).text().trim());
       }
-      const vault = await openVault(repoDir);
+      const vault = await openOrCreateVault(repoDir);
       const base = await vault.materialize();
       const updates = [];
       for (const spec of specs) {

package/lib/command-manifest.mjs

@@ -257,11 +257,23 @@ export const COMMAND_MANIFEST = [
   // 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", "push"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "captures the cwd git working tree and publishes a signed head" },
+  { 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" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────

package/lib/functions.mjs

@@ -842,6 +842,8 @@ async function rebuild(projectId, args = []) {
   const positionals = [];
   for (const arg of args) {
     if (arg === "--all") { all = true; continue; }
+    // Same rule as assertNoExtraPositionals: a flag is not a positional.
+    if (typeof arg === "string" && arg.startsWith("-")) continue;
     positionals.push(arg);
   }
   if (positionals.length > 1) {
@@ -957,12 +959,18 @@ function parseDepsFlag(value) {
 }
 
 function assertNoExtraPositionals(args, usage) {
-  if (args.length > 0) {
+  // Only POSITIONALS count. A flag-shaped argument that survived
+  // assertKnownFlags is an accepted convention flag (`--json`), not a stray
+  // positional — reporting it as one made `functions list --json` fail with
+  // "Unexpected argument: --json" while the same command without it worked.
+  // Its sibling assertNoUnexpectedPositionals already skips these.
+  const extra = args.filter((a) => !(typeof a === "string" && a.startsWith("-")));
+  if (extra.length > 0) {
     fail({
       code: "BAD_USAGE",
-      message: `Unexpected argument: ${args[0]}`,
+      message: `Unexpected argument: ${extra[0]}`,
       hint: usage,
-      details: { argument: args[0] },
+      details: { argument: extra[0] },
     });
   }
 }

package/lib/gitvault-scaffold.mjs

@@ -0,0 +1,73 @@
+/**
+ * Shared git-remote-scaffold fold-in (repo-first-onramp D4, task 2.4).
+ *
+ * `run402 init`'s 5b block pioneered this pattern; this module is the same
+ * additive-only, non-fatal-in-every-branch scaffold factored out so
+ * `projects provision`, `run402 up`, and `run402 repos create` all report
+ * through the IDENTICAL `gitvault` / `gitvault_skipped` / `gitvault_error`
+ * summary keys `init` already uses, instead of three near-copies drifting
+ * apart. `init.mjs` itself is left untouched — its own scaffold block is
+ * shipped and tested; this module exists for the NEW callers task 2.4 adds.
+ *
+ * Never creates a repository on its own unless `createRepoIfMissing` is
+ * explicit (mirrors `init`'s `--git-remote` opt-in): a directory the caller
+ * did not ask to turn into a repository is left alone. `origin` is never
+ * touched or reclaimed (D1, via `gitvault.scaffoldRemote` itself). Every
+ * branch is non-fatal — a missing git, an unresolvable org, or an
+ * unreachable gateway all report and return, never throw.
+ */
+import { getSdk } from "./sdk.mjs";
+import { resolveOwningOrgId } from "./org-context.mjs";
+
+/**
+ * The interim allocation→policy advisory (repo-first-onramp D3, stated as an
+ * interim). TODAY the platform sets `gitvault_policy: required` at allocation
+ * — the decoupling (allocation leaving the policy unset) is design D3's
+ * gateway half and ships in a later release (task 3.1). Until it does, every
+ * client-side path that allocates a vault prints this line so the policy flip
+ * is never a silent side effect of a push or a create. Faithful over flattering:
+ * documenting the designed future as the present is the breach; this line is
+ * the truth. DELETE this export (and its four call sites) when the gateway
+ * decoupling ships.
+ */
+export const GITVAULT_ALLOCATION_POLICY_ADVISORY =
+  "note: allocation currently sets gitvault_policy to 'required' — from now on a deploy must present a vaulted capture (produced automatically by `run402 deploy apply` on any machine holding this keystore). Opt out with `run402 gitvault policy grandfathered --reason \"<why>\"`. A later release decouples allocation from the deploy gate (design D3).";
+
+/**
+ * @param {object} options
+ * @param {string} [options.repoDir] Working tree to scaffold. Defaults to `process.cwd()`.
+ * @param {string} options.projectId The project the remote should point at.
+ * @param {string} [options.orgId] Explicit owning org. Resolved via `resolveOwningOrgId` when omitted.
+ * @param {boolean} [options.createRepoIfMissing] Opt into `git init`-ing `repoDir` when it is not a repository yet.
+ * @returns {Promise<{gitvault: object|null, gitvault_skipped?: string, gitvault_error?: {code: string, message: string}}>}
+ */
+export async function scaffoldGitvaultRemote({ repoDir = process.cwd(), projectId, orgId, createRepoIfMissing = false } = {}) {
+  const out = { gitvault: null };
+  try {
+    const { hardenedGit } = await import("#sdk/node");
+    let insideRepo = true;
+    try {
+      await hardenedGit(repoDir, ["rev-parse", "--git-dir"]);
+    } catch {
+      insideRepo = false;
+    }
+    if (!insideRepo && !createRepoIfMissing) {
+      out.gitvault_skipped = "not a git repository — re-run with --git-remote to create one and add the remote";
+      return out;
+    }
+    const resolvedOrgId = orgId ?? (await resolveOwningOrgId(projectId));
+    if (!resolvedOrgId) {
+      out.gitvault_skipped = `could not resolve the owning org for ${projectId} — the run402 remote was not added`;
+      return out;
+    }
+    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`).
+    out.gitvault = { ...remote, allocated: false };
+  } catch (err) {
+    out.gitvault = null;
+    out.gitvault_error = { code: err?.body?.code ?? err?.code ?? "GITVAULT_SCAFFOLD_FAILED", message: err?.message ?? String(err) };
+  }
+  return out;
+}

package/lib/gitvault.mjs

@@ -19,6 +19,7 @@
 import { readFileSync } from "node:fs";
 import { resolveProjectId } from "./config.mjs";
 import { resolveOwningOrgId } from "./org-context.mjs";
+import { GITVAULT_ALLOCATION_POLICY_ADVISORY } from "./gitvault-scaffold.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import {
@@ -37,15 +38,15 @@ const COMMON_VALUE_FLAGS = ["--project", "--repo"];
 export const HELP = `run402 gitvault — your source, encrypted before it leaves the machine
 
 Usage:
-  run402 gitvault init    [--project <id>] [--org <org_id>] [--git-remote] [--no-remote]
-  run402 gitvault status  [--project <id>] [--repo <repo_id>] [--refs]
-  run402 gitvault push    [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint]
-  run402 gitvault policy  <required|grandfathered> [--project <id>] [--repo <repo_id>]
-                          [--reason <why>]
-  run402 gitvault compact [--project <id>] [--repo <repo_id>]
-  run402 gitvault prune   [--project <id>] [--repo <repo_id>]
-                          [--submit --intent-core <path> --verifier-receipt <path> [--wait]]
-  run402 gitvault verify  [--project <id>] [--repo <repo_id>] [--budget <n>]
+  run402 gitvault init     [--project <id>] [--org <org_id>] [--git-remote] [--no-remote]
+  run402 gitvault status   [--project <id>] [--repo <repo_id>] [--refs]
+  run402 gitvault snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint]
+  run402 gitvault policy   <required|grandfathered> [--project <id>] [--repo <repo_id>]
+                           [--reason <why>]
+  run402 gitvault compact  [--project <id>] [--repo <repo_id>]
+  run402 gitvault prune    [--project <id>] [--repo <repo_id>]
+                           [--submit --intent-core <path> --verifier-receipt <path> [--wait]]
+  run402 gitvault verify   [--project <id>] [--repo <repo_id>] [--budget <n>]
 
 Subcommands:
   init      ALLOCATE the project's vault. This is the one step that mints key
@@ -65,11 +66,20 @@ Subcommands:
             audited. \`grandfathered\` is the documented way out of a deploy
             blocked by GITVAULT_CLIENT_UPGRADE_REQUIRED, and leaves a
             doctor-persistent warning until the project returns to \`required\`.
-  push      Capture the working tree and publish it. This is NOT gated on a
-            deploy — a vault-only project pushes for months without one.
-            Before reporting a push as landed the SDK compares finalization
+  snapshot  Capture the working tree and publish it. This is NOT gated on a
+            deploy — a vault-only project snapshots for months without one.
+            Against a project with no vault yet, this ALLOCATES one inline
+            (the six-stage creation, same as \`init\`) before publishing — one
+            command, no prior \`gitvault init\`. The one-shot recovery receipt
+            and keystore path print to stderr the moment that happens.
+            Before reporting a snapshot as landed the SDK compares finalization
             receipts against the expected manifest and reads the admitted head
-            back from storage; a 200 alone is never enough.
+            back from storage; a 200 alone is never enough. \`push\` is a
+            deprecation-warning alias for one release — it will be removed
+            next release. Once \`gitvault\` was the only publish verb; \`git
+            push\` is now the actual publish path (via the remote helper),
+            so \`push\` here was renamed to name what it does: one verb per
+            operation.
   compact   Publish a checkpoint covering the canonical refs, every root
             unexpired at the cutoff, and the HEAD target, under a maintenance
             lease so a concurrent cycle cannot race it.
@@ -97,9 +107,9 @@ Options:
                     chain and advances the local materialized pin), which is
                     why plain \`status\` — an observation — does not do it.
   --repo <repo_id>  Address the vault directly by id, skipping project lookup
-  --message <text>  push: commit message for the synthetic commit a dirty tree
+  --message <text>  snapshot: commit message for the synthetic commit a dirty tree
                     produces (a clean tree pushes HEAD itself, no message used)
-  --checkpoint      push: force the checkpoint-bearing form regardless of delta size
+  --checkpoint      snapshot: force the checkpoint-bearing form regardless of delta size
   --budget <n>      verify: heads to verify in this call. The verified prefix is
                     persisted, so a budget-exceeded run resumes where it stopped
                     instead of restarting.
@@ -190,8 +200,12 @@ function printTerminalLoss(status) {
   console.error("");
 }
 
-/** Where the keystore lives — for verbs whose payload is not a `status`. */
-async function printKeystoreLocation() {
+/**
+ * Where the keystore lives — for verbs whose payload is not a `status`.
+ * Exported: `repos create` (repo-first-onramp task 2.6) prints the same
+ * line after allocating a vault, and must not restate this logic.
+ */
+export async function printKeystoreLocation() {
   try {
     const { getGitvaultKeystoreRoot } = await import("#sdk/node");
     console.error(`keystore: ${getGitvaultKeystoreRoot()} — back this up; whole-keystore loss is terminal for vault history`);
@@ -268,8 +282,9 @@ async function init(args) {
         ? `vault ${result.repo_id} already existed — nothing was re-allocated and no new key material was minted`
         : `allocated vault ${result.repo_id} (genesis ${result.genesis_sha256})`,
     );
-    if (result.remote) console.error(`remote '${result.remote.name}' -> ${result.remote.url}`);
+    if (result.remote) console.error(`remote '${result.remote.name}' -> ${result.remote.url} (${result.remote.reason})`);
     if (remoteSkipped) console.error(`remote not added: ${remoteSkipped}`);
+    if (!result.deduplicated) console.error(GITVAULT_ALLOCATION_POLICY_ADVISORY);
     // The recovery receipt is integrity data, not a secret, and it is worth
     // exactly as much as the number of copies you keep. It is persisted into
     // the keystore automatically; say where, because "keep many copies" is
@@ -376,20 +391,46 @@ async function status(args) {
   }
 }
 
-async function push(args) {
+/**
+ * D5 (repo-first-onramp task 2.5): one verb per operation. Renamed from
+ * `push` — `push` now means exactly one thing everywhere: `git push`. The
+ * capture lane keeps its old function name internally to minimize churn;
+ * only the dispatched SUBCOMMAND name changed (see `run()` below, where
+ * `gitvault push` survives one release as a deprecation-warning alias).
+ */
+async function snapshot(args) {
   const a = normalizeArgv(args);
   const valueFlags = [...COMMON_VALUE_FLAGS, "--message"];
   assertKnownFlags(a, [...valueFlags, "--checkpoint", "--help", "-h"], valueFlags);
   requirePositionalCount(a, valueFlags, {
-    min: 0, max: 0, command: "run402 gitvault push", missing: "",
+    min: 0, max: 0, command: "run402 gitvault snapshot", missing: "",
   });
   const message = flagValue(a, "--message");
+  const target = vaultTarget(a);
+  // D2: lazily allocate the vault on first push when there is a project to
+  // resolve the owning org from — the same resolution `gitvault init` uses.
+  // `--repo`-only addressing has nothing to create FROM (no project_id), so
+  // it is skipped there, matching `open()`'s own precedence.
+  const orgId = target.project_id ? await resolveOwningOrgId(target.project_id) : null;
   const opts = {
-    ...vaultTarget(a),
+    ...target,
+    ...(orgId ? { org_id: orgId } : {}),
     // The gitvault_commit line is progress, not payload: print it the moment
     // the snapshot exists, well before the publication round-trips finish, so
     // a human watching a slow push sees what is being pushed.
     onCommitLine: (line) => console.error(line),
+    // Fires synchronously, BEFORE the capture/publish that follows — printed
+    // here rather than deferred past `push()`'s return so the receipt is
+    // never lost if a later step in the SAME push fails after allocation
+    // already landed on the server.
+    onVaultCreated: async (created) => {
+      console.error("");
+      console.error(`vault allocated (genesis ${created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
+      console.error(JSON.stringify(created.recovery_receipt));
+      await printKeystoreLocation();
+      console.error(GITVAULT_ALLOCATION_POLICY_ADVISORY);
+      console.error("");
+    },
   };
   // The message rides on `snapshot`, which is what `captureSnapshot` reads —
   // and, since 5.12b removed the dead top-level `push({ message })` field, is
@@ -558,8 +599,17 @@ export async function run(sub, args) {
       await status(argv);
       break;
     }
+    case "snapshot": {
+      await snapshot(argv);
+      break;
+    }
     case "push": {
-      await push(argv);
+      // D5: one verb per operation — "push" now means exactly one thing,
+      // `git push`. Retained as a deprecation-warning alias for ONE release
+      // (pre-launch, the benchmark gate prefers the rename now over an
+      // alias forever); it will be removed next release.
+      console.error("`run402 gitvault push` is deprecated and will be removed in the next release — use `run402 gitvault snapshot` instead.");
+      await snapshot(argv);
       break;
     }
     case "compact": {

package/lib/init.mjs

@@ -557,7 +557,10 @@ export async function run(args = []) {
   // Purely LOCAL git. No vault is allocated and no key material is written
   // here — the spec is explicit that neither exists until first capture, so the
   // cold-start path gains no prompt and no new failure mode. Allocation happens
-  // on the first `run402 gitvault push` (or deploy).
+  // on the first `git push origin <branch>` or `run402 gitvault snapshot` (D2,
+  // repo-first-onramp) — NOT on deploy: `applyWithGitvault` only ever reads an
+  // EXISTING vault's policy (D3) and never allocates one that does not exist,
+  // so a project with no vault deploys exactly as it always did.
   //
   // Adding the remote is the DEFAULT inside a repository that already exists,
   // because it is pure addition: `origin` is never modified or claimed, no file
@@ -608,11 +611,13 @@ export async function run(args = []) {
           if (remote.already_present && remote.existing_url !== remote.url) {
             // Left exactly as it was. Name the URL that is actually in place
             // rather than implying the remote now points at this project.
-            line("Gitvault", `remote '${remote.name}' already points at ${remote.existing_url} — left unchanged`);
+            line("Gitvault", `remote '${remote.name}' already points at ${remote.existing_url} — left unchanged (${remote.reason})`);
           } else if (remote.already_present) {
             line("Gitvault", `remote '${remote.name}' already set (${remote.url})`);
           } else {
-            line("Gitvault", `${remote.created_repository ? "initialized a repository and added" : "added"} remote '${remote.name}' -> ${remote.url}`);
+            // D1: `origin` when it was free, `run402` when it was already
+            // taken by something else — `remote.reason` says which happened.
+            line("Gitvault", `${remote.created_repository ? "initialized a repository and added" : "added"} remote '${remote.name}' -> ${remote.url} (${remote.reason})`);
           }
         }
       }

package/lib/projects.mjs

@@ -6,6 +6,7 @@ import { withAutoApprove } from "./operator.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 import { stampOrgFromProject } from "./org-context.mjs";
+import { scaffoldGitvaultRemote } from "./gitvault-scaffold.mjs";
 import { assertKnownFlags, failBadProjectId, flagValue, hasHelp, normalizeArgv, positionalArgs, resolveProjectSelector, validateRegularFile, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
@@ -299,6 +300,20 @@ async function quote() {
   }
 }
 
+/**
+ * D4 (repo-first-onramp task 2.4): `projects provision` already knows the
+ * project and (usually) the org, and just set the active project —
+ * scaffolding the git remote here is a pure Anticipatory fold, zero extra
+ * round-trips beyond the one org lookup provision needed anyway when `--org`
+ * was not given explicitly. `provision` has no `--git-remote` opt-in, so a
+ * directory that is not already a repository is left untouched, exactly like
+ * `run402 init`'s own scaffold (shared via `gitvault-scaffold.mjs`, which
+ * emits the SAME `gitvault` / `gitvault_skipped` / `gitvault_error` keys).
+ */
+async function foldGitvaultScaffold(out, projectId, explicitOrgId) {
+  Object.assign(out, await scaffoldGitvaultRemote({ repoDir: process.cwd(), projectId, orgId: explicitOrgId }));
+}
+
 async function provision(args) {
   const opts = { tier: "prototype", name: undefined, orgId: undefined, idempotencyKey: undefined };
   for (let i = 0; i < args.length; i++) {
@@ -373,6 +388,7 @@ async function provision(args) {
       out.note = `active project changed: ${activeBefore} -> ${activeAfter}`;
       out.previous_active_project_id = activeBefore;
     }
+    await foldGitvaultScaffold(out, data.project_id, opts.orgId);
     console.log(JSON.stringify(out, null, 2));
   } catch (err) {
     reportSdkError(err);