run402 4.24.1 → 4.26.0

package/cli.mjs

@@ -49,6 +49,7 @@ Commands:
   rooms       Coordinate with the other agents on your project (who/send/ack)
   escalations Page a human when you judge you need one (raise/list/ack)
   claims      Say what you're working on before you collide (advisory)
+  gitvault    Host-blind encrypted Git remote (init/status/push/policy/compact/prune/verify)
   errors      Grouped error fingerprints + a promote/revert verdict (release-baselined)
   jobs        Submit and inspect platform-managed jobs
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
@@ -64,7 +65,6 @@ Commands:
   email       Send template-based emails from your project
   message     Send messages to Run402 developers
   auth        Manage project user authentication (magic link, passwords, settings)
-  sender-domain  Removed; use domains connect/status/repair
   billing     Email organizations, Stripe tier checkout, email packs
   contracts   KMS signers ($0.04/day rental + $0.000005/sign)
   agent       Manage agent identity (contact info)
@@ -292,6 +292,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "gitvault": {
+    const { run } = await import("./lib/gitvault.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "escalations": {
     const { run } = await import("./lib/escalations.mjs");
     await run(sub, rest);
@@ -382,11 +387,6 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  case "sender-domain": {
-    const { run } = await import("./lib/sender-domain.mjs");
-    await run(sub, rest);
-    break;
-  }
   case "billing": {
     const { run } = await import("./lib/billing.mjs");
     await run(sub, rest);

package/git-remote-run402.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * `git-remote-run402` — the git remote helper for gitvault, so plain
+ * `git clone|fetch|push run402::<org_id>/<project_id>` speaks to a host-blind
+ * encrypted vault with no run402-specific git ceremony.
+ *
+ * ARCHITECTURAL LAW (gitvault-client-surface, "All protocol logic lives in the
+ * SDK"): this file is a THIN ADAPTER over `r.gitvault`. It translates git's
+ * remote-helper wire protocol into SDK calls and back, and does nothing else.
+ * No crypto, no HTTP, no ref-policy decisions, no pack building — those live
+ * once in `@run402/sdk`. Even git itself is invoked only through the SDK's own
+ * `hardenedGit` (hooks, fsmonitor, replace-refs and filter autodetection are
+ * neutralized there), so this helper hand-rolls no git behaviour either.
+ *
+ * PROTOCOL SURFACE (gitremote-helpers(1)). Implemented:
+ *   capabilities            → advertises fetch, push, option
+ *   list [for-push]         → the vault's canonical ref map + the HEAD target
+ *   fetch <sha1> <name>     → restore the vault's object database into this repo
+ *   push [+]<src>:<dst>     → publish one atomic ref transaction
+ *   option <name> <value>   → ok / unsupported, never a silent lie
+ *
+ * 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,
+ * unrelated repository. Discovering the repository from cwd therefore wrote a
+ * vault's DECRYPTED objects into a repository the user never named, silently,
+ * on every clone (dogfood #1). Every repository-touching command now resolves
+ * through the SDK's `resolveGitInvocationRepo`, which proves `GIT_DIR` names a
+ * real repository and refuses otherwise; a refusal writes nothing at all.
+ * `capabilities`, `option` and `list` need no repository and are unaffected,
+ * so a repository-free `git ls-remote run402::<org>/<project>` still works.
+ *
+ * NOT advertised, deliberately: `list` is a COMMAND in this protocol, not a
+ * capability keyword — git's capability vocabulary is fetch/push/import/export/
+ * connect/stateless-connect/option/refspec/check-connectivity/object-format/
+ * signed-tags/bidi-import/get. Advertising `list` would be a line git silently
+ * discards; the command itself is implemented above. `connect`,
+ * `stateless-connect`, `import`, and `export` are NOT implemented: the vault is
+ * not a git-protocol endpoint you can tunnel to, and pretending otherwise would
+ * hand git a transport that cannot answer.
+ *
+ * KNOWN LIMITS, stated rather than papered over:
+ *   - `fetch` restores the vault's object database WHOLESALE. The SDK exposes
+ *     no per-ref object selection, so one batch = one full restore. That is a
+ *     superset of what git asked for (git writes the refs itself from `list`),
+ *     never a subset — but it is not incremental.
+ *   - `push` never changes the vault's HEAD target; the SDK carries it forward.
+ *     A fresh vault defaults to `refs/heads/main`, so a first push of some
+ *     other branch leaves HEAD naming a ref that does not exist yet. Use
+ *     `run402 gitvault push`, which sets the HEAD target from the local HEAD.
+ *   - `option dry-run` is `unsupported`: this helper cannot rehearse a
+ *     publication, and reporting a fake success would be worse than refusing.
+ *   - `fetch` and `push` REQUIRE the `GIT_DIR` git sets when it drives a
+ *     helper against a repository, so running this binary by hand from a shell
+ *     is refused rather than silently pointed at the current directory. Only
+ *     `capabilities`, `option` and `list` work without one, which is exactly
+ *     the set `git ls-remote <url>` outside a checkout needs.
+ */
+
+import { createInterface } from "node:readline";
+import { getSdk } from "./lib/sdk.mjs";
+import { parseGitvaultRemoteUrl } from "#sdk";
+import { hardenedGit, resolveGitInvocationRepo } from "#sdk/node";
+
+const out = (line) => process.stdout.write(`${line}\n`);
+/** Every helper response block is terminated by a blank line. */
+const endBlock = () => process.stdout.write("\n");
+const note = (line) => process.stderr.write(`git-remote-run402: ${line}\n`);
+
+/** Protocol lines are single-line: collapse anything that could break framing. */
+function oneLine(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
+}
+
+function describeError(err) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  const message = err?.message ?? err?.body?.message ?? String(err);
+  return oneLine(code ? `${code}: ${message}` : message);
+}
+
+/**
+ * Resolve the vault address from git's argv.
+ *
+ * Git invokes `git-remote-<transport> <remote> <url>`, and for a
+ * `<transport>::<address>` URL it passes the BARE `<address>` as the second
+ * argument — the `run402::` prefix is already stripped. The SDK's parser is the
+ * only thing that understands the address grammar, so both spellings are handed
+ * to it rather than re-implemented here.
+ */
+function resolveRemoteAddress(argv) {
+  for (const raw of [argv[1], argv[0]]) {
+    if (typeof raw !== "string" || raw.length === 0) continue;
+    const direct = parseGitvaultRemoteUrl(raw);
+    if (direct) return direct;
+    // Re-add the prefix ONLY for a bare, colon-free address. Without this
+    // guard `https://example.com/x` parses as org `https:` / project
+    // `/example.com/x`, and `git@github.com:x/y.git` as org `git@github.com:x`
+    // — a confidently wrong answer is worse than no answer here. The colon is
+    // git's own URL punctuation, never part of a bare `<org_id>/<project_id>`.
+    if (raw.includes(":")) continue;
+    const prefixed = parseGitvaultRemoteUrl(`run402::${raw}`);
+    if (prefixed) return prefixed;
+  }
+  return null;
+}
+
+/** `[+]<src>:<dst>` — an empty `<src>` is a deletion. */
+function parsePushSpec(spec) {
+  const forced = spec.startsWith("+");
+  const body = forced ? spec.slice(1) : spec;
+  const colon = body.indexOf(":");
+  if (colon === -1) return { src: body, dst: body, force: forced };
+  return { src: body.slice(0, colon), dst: body.slice(colon + 1), force: forced };
+}
+
+async function main(argv) {
+  const address = resolveRemoteAddress(argv);
+  if (!address) {
+    note(`could not read a run402 remote address from ${JSON.stringify(argv.join(" "))} — expected run402::<org_id>/<project_id>`);
+    return 1;
+  }
+
+  const target = { project_id: address.project_id };
+  let verbosity = 1;
+
+  /**
+   * The repository git invoked us for, resolved once and PROVEN.
+   *
+   * Deliberately lazy: `list` needs no repository, so `git ls-remote` outside
+   * any checkout keeps working. Deliberately not cached across a failure
+   * either — a refusal is terminal for the command that asked, and there is
+   * nothing to retry.
+   */
+  let resolvedRepo = null;
+  async function requireRepo() {
+    if (!resolvedRepo) resolvedRepo = await resolveGitInvocationRepo(process.env, process.cwd());
+    return resolvedRepo.repo_dir;
+  }
+
+  /**
+   * What to tell a human when we refuse. `git clone` is the case that used to
+   * fail; naming the working alternative beats a bare error.
+   */
+  function repoRefusalNote(err) {
+    note(describeError(err));
+    note("refusing to touch a repository git did not name — nothing was read or written.");
+    note(`if you meant to restore this vault: git init --bare <dir> && git -C <dir> remote add run402 run402::${address.org_id}/${address.project_id} && git -C <dir> fetch run402 '+refs/heads/*:refs/heads/*'`);
+  }
+
+  /** 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;
+
+  async function runList() {
+    const state = await (await openVault()).materialize();
+    const refs = state.refs ?? {};
+    for (const ref of Object.keys(refs).sort()) out(`${refs[ref]} ${ref}`);
+    const head = state.head_target;
+    // A symref is only advertised when its target is actually present:
+    // pointing HEAD at a ref that does not exist is what an empty repository
+    // looks like, and git reads the empty list correctly on its own.
+    if (head?.kind === "symref" && Object.prototype.hasOwnProperty.call(refs, head.ref)) out(`@${head.ref} HEAD`);
+    else if (head?.kind === "detached") out(`${head.oid} HEAD`);
+    endBlock();
+  }
+
+  async function runFetch(batch) {
+    // Resolve the target repository BEFORE a single byte is decrypted: a
+    // refusal here must leave no objects anywhere. This is what makes `clone`
+    // work (git names the fresh repo in `GIT_DIR`) and what stops a clone run
+    // from inside an unrelated checkout from writing into that checkout.
+    let repoDir;
+    try {
+      repoDir = await requireRepo();
+    } catch (err) {
+      repoRefusalNote(err);
+      return 1;
+    }
+    if (verbosity >= 1) note(`restoring the vault object database for ${batch.length} ref(s) into ${repoDir}`);
+    const restored = await getSdk().gitvault.restore({ ...target, repo_dir: repoDir, target_dir: repoDir });
+    if (verbosity >= 1) note(`restored generation ${restored.generation}`);
+    endBlock();
+    return 0;
+  }
+
+  async function runPush(batch) {
+    const specs = batch.map(parsePushSpec);
+    try {
+      // Repository first, then every source revision, and only then the
+      // network: a push that names a ref this repository does not have must
+      // fail locally rather than after opening the vault.
+      const repoDir = await requireRepo();
+      const newOids = new Map();
+      for (const spec of specs) {
+        // A deletion carries an empty <src>. Everything else is resolved by
+        // git itself; `--end-of-options` keeps a hostile refname from being
+        // read as a flag.
+        newOids.set(spec, spec.src === ""
+          ? null
+          : (await hardenedGit(repoDir, ["rev-parse", "--verify", "--end-of-options", spec.src])).text().trim());
+      }
+      const vault = await openVault(repoDir);
+      const base = await vault.materialize();
+      const updates = [];
+      for (const spec of specs) {
+        const expectedOld = base.refs?.[spec.dst] ?? null;
+        updates.push({
+          ref: spec.dst,
+          expected_old_oid: expectedOld,
+          new_oid: newOids.get(spec),
+          // Force-with-lease still requires a lease, so a CREATE is never
+          // forced. The SDK owns what force actually permits.
+          force: spec.force && expectedOld !== null,
+        });
+      }
+      // ONE transaction for the whole batch: the SDK evaluates fast-forward,
+      // tag immutability, protocol-ref refusal and retention roots, builds the
+      // packs, and publishes — all or nothing.
+      const published = await vault.push({ transaction: { updates } });
+      if (verbosity >= 1) note(`published generation ${published.generation} (${published.form})`);
+      for (const spec of specs) out(`ok ${spec.dst}`);
+    } catch (err) {
+      // The transaction is atomic, so a failure failed every ref in it. Report
+      // it against each one rather than letting some look like they landed.
+      if (err?.code === "GIT_INVOCATION_REPO_UNRESOLVED") repoRefusalNote(err);
+      const reason = describeError(err);
+      for (const spec of specs) out(`error ${spec.dst} ${reason}`);
+    }
+    endBlock();
+    return 0;
+  }
+
+  function handleOption(name, value) {
+    switch (name) {
+      case "verbosity": {
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsed)) { out("error expected an integer verbosity"); return; }
+        verbosity = parsed;
+        out("ok");
+        return;
+      }
+      case "progress":
+        // Progress is stderr chatter, which `verbosity` already governs.
+        out("ok");
+        return;
+      case "atomic":
+        // Every push here is a single ref transaction, so the guarantee holds
+        // whichever way git asked for it.
+        out("ok");
+        return;
+      default:
+        // Includes dry-run, object-format, depth, cloning, check-connectivity,
+        // followtags, pushcert: honestly unsupported rather than acknowledged.
+        out("unsupported");
+    }
+  }
+
+  let fetchBatch = [];
+  let pushBatch = [];
+
+  /** Returns the process exit code the flushed batch demands (0 = keep going). */
+  async function flushBatches() {
+    if (fetchBatch.length > 0) {
+      const batch = fetchBatch;
+      fetchBatch = [];
+      return await runFetch(batch);
+    }
+    if (pushBatch.length > 0) {
+      const batch = pushBatch;
+      pushBatch = [];
+      return await runPush(batch);
+    }
+    return 0;
+  }
+
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  try {
+    for await (const raw of rl) {
+      const line = raw.replace(/\r$/, "");
+      if (line === "") {
+        const code = await flushBatches();
+        if (code !== 0) return code;
+        continue;
+      }
+      const space = line.indexOf(" ");
+      const command = space === -1 ? line : line.slice(0, space);
+      const rest = space === -1 ? "" : line.slice(space + 1);
+      switch (command) {
+        case "capabilities":
+          out("fetch");
+          out("push");
+          out("option");
+          endBlock();
+          break;
+        case "list":
+          await runList();
+          break;
+        case "option": {
+          const optSpace = rest.indexOf(" ");
+          handleOption(optSpace === -1 ? rest : rest.slice(0, optSpace), optSpace === -1 ? "" : rest.slice(optSpace + 1));
+          break;
+        }
+        case "fetch":
+          fetchBatch.push(rest);
+          break;
+        case "push":
+          pushBatch.push(rest);
+          break;
+        default:
+          note(`unknown command: ${oneLine(line)}`);
+          return 1;
+      }
+    }
+    // EOF. Git always terminates a batch with a blank line, but flushing here
+    // means a truncated stream still does the work it already asked for
+    // instead of silently dropping it.
+    return await flushBatches();
+  } finally {
+    rl.close();
+  }
+}
+
+// Never `process.exit()` mid-stream: that can truncate a pending stdout write
+// on a pipe, which git reads as a protocol violation. Set the code and let Node
+// flush and exit on its own.
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (err) => { note(describeError(err)); process.exitCode = 1; },
+);

package/lib/command-manifest.mjs

@@ -232,6 +232,19 @@ export const COMMAND_MANIFEST = [
   { path: ["claims", "create"], positionals: [p("resource")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["deploy"], runStyle: "sub" },
   { 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
+  // 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", "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: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────
@@ -403,6 +416,5 @@ export const COMMAND_MANIFEST = [
 // completeness check against cli.mjs's dispatch switch.
 export const SKIPPED_FAMILIES = {
   "apply": "pure alias for `deploy apply` (covered by the deploy family)",
-  "sender-domain": "removed command — every subcommand errors with COMMAND_REMOVED",
   "dev": "interactive wrapper that spawns `astro dev`",
 };

package/lib/credentials.mjs

@@ -324,6 +324,10 @@ async function importKey(args) {
     site_url: existing?.site_url,
     deployed_at: existing?.deployed_at,
     last_deployment_id: existing?.last_deployment_id,
+    // Carried, not re-derived: a key import says nothing about which org owns
+    // the project, and dropping the cache here would make `run402 init` reach
+    // for the control plane again on a machine that already knew.
+    org_id: existing?.org_id,
     source: "manual_import",
     cached_at: new Date().toISOString(),
   });

package/lib/deploy-v2.mjs

@@ -1349,11 +1349,88 @@ const CI_DEPLOY_ERROR_GUIDANCE = {
 };
 
 function reportDeployApplyError(err, useGithubActionsOidc) {
-  const warningEnhanced = enhanceDeployWarningError(err);
+  const warningEnhanced = enhanceGitvaultDeployError(enhanceDeployWarningError(err));
   if (!useGithubActionsOidc) return reportSdkError(warningEnhanced);
   return reportSdkError(enhanceCiDeployError(warningEnhanced));
 }
 
+/**
+ * Whether THIS client's deploy lane speaks the gitvault protocol.
+ *
+ * `"unsupported"` is a statement of fact about the code in this file: it
+ * declares no capture at plan time and sends no gitvault block on commit, so a
+ * project with `gitvault_policy: required` refuses its commits. The vault
+ * itself works — `run402 gitvault push` and `git push run402` publish captures
+ * — it is the DEPLOY lane that has no capture wiring.
+ *
+ * RETIREMENT CONDITION: flip this to `"supported"` in the same change that
+ * makes `applyCmd` declare `{capture_id, snapshot_oid_hmac}` on
+ * `POST /apply/v1/plans` and present an activation token on
+ * `POST /apply/v1/plans/:id/commit` (protocol §6.5). Doing that faithfully also
+ * means building the deploy artifacts from an isolated materialization of the
+ * snapshot commit, which is why it is a design change and not a wiring one:
+ * build output is normally gitignored, so it is not in the snapshot at all.
+ * `cli-deploy-gitvault-advisory.test.mjs` fails if the flag and the advisory
+ * ever disagree.
+ */
+export const GITVAULT_DEPLOY_LANE = "unsupported";
+
+/**
+ * Tell the truth about a deploy the vault gate refused.
+ *
+ * The gateway's `GITVAULT_CLIENT_UPGRADE_REQUIRED` envelope leads with
+ * `upgrade_client` / `npm i -g run402@latest`, which is correct in principle
+ * and WRONG right now: no published `run402` has a gitvault-capable deploy
+ * lane, so upgrading changes nothing about this refusal (dogfood #1, finding
+ * C). Relaying it unedited sends an agent into an upgrade loop. The gateway's
+ * SECOND action — grandfather the policy — is real and reachable, and this
+ * client now has the verb for it.
+ *
+ * The gateway's own actions are PRESERVED, never dropped: they are re-ordered
+ * behind an honest one, and the upgrade action keeps its place with its
+ * promise corrected. When the lane ships, the flag above retires this whole
+ * function's rewrite and the envelope passes through untouched.
+ */
+export function enhanceGitvaultDeployError(err) {
+  const body = err?.body && typeof err.body === "object" && !Array.isArray(err.body) ? err.body : {};
+  const code = body.code || err?.code || null;
+  if (code !== "GITVAULT_CLIENT_UPGRADE_REQUIRED") return err;
+  if (GITVAULT_DEPLOY_LANE === "supported") return err;
+
+  const gatewayActions = Array.isArray(body.next_actions) ? body.next_actions : [];
+  const enhanced = Object.assign(new Error(err?.message || body.message || code), err);
+  enhanced.body = {
+    ...body,
+    hint:
+      "This project requires a vaulted capture on deploy, and this run402 CLI's deploy lane does not produce one — " +
+      "upgrading the CLI does not currently fix it. Either grandfather the policy (owner + step-up) and deploy, or " +
+      "keep the project vaulted and deploy later. Your source can still be vaulted today: `run402 gitvault push` and " +
+      "`git push run402 <branch>` are not gated on a deploy.",
+    next_actions: [
+      editRequestAction(
+        "run402 gitvault policy grandfathered --reason \"<why>\"",
+        "Un-gate this project so deploys activate without a vaulted capture. Owner + step-up, audited, and it leaves a doctor-persistent warning until you return the project to `required`.",
+      ),
+      editRequestAction(
+        "run402 gitvault push",
+        "Capture and publish your source into the vault. Independent of deploy — a vault-only project pushes for months without one.",
+      ),
+      editRequestAction(
+        "run402 gitvault policy required",
+        "Restore the gate once a gitvault-capable deploy lane is available.",
+      ),
+      // Preserved verbatim in shape, with the promise corrected: the gateway
+      // is describing the eventual client, not one you can install today.
+      ...gatewayActions.map((action) =>
+        action?.type === "upgrade_client"
+          ? { ...action, why: "Tracks the eventual gitvault-capable deploy lane. No published run402 has one yet, so this does not resolve the refusal today." }
+          : action,
+      ),
+    ],
+  };
+  return enhanced;
+}
+
 function enhanceDeployWarningError(err) {
   const existingBody = err?.body && typeof err.body === "object" && !Array.isArray(err.body)
     ? err.body

package/lib/doctor.mjs

@@ -12,7 +12,7 @@
  */
 
 import { existsSync, statSync } from "node:fs";
-import { configDir, readAllowance, loadKeyStore } from "./config.mjs";
+import { configDir, readAllowance, loadKeyStore, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import {
   resolveScanRoot,
@@ -58,6 +58,10 @@ Checks performed:
   - Function runtime staleness: deployed functions running an older platform
     runtime than the current gateway build (refresh with 'run402 functions
     rebuild --all'; re-bundles from your stored source, no source change)
+  - gitvault: the active project's vault — activation policy, whether THIS
+    machine can produce the capture a 'required' policy demands, open
+    unvaulted-override journals, and where the keystore lives (back it up:
+    whole-keystore loss is terminal for vault history)
   - Source scan: hallucinated SDK auth names (R402_AUTH_UNKNOWN_EXPORT),
     state-changing GET handlers (R402_AUTH_STATE_CHANGING_GET),
     auth.* calls in prerendered pages (R402_AUTH_PRERENDERED),
@@ -392,6 +396,81 @@ export async function run(sub, args = []) {
     });
   }
 
+  // 6c. gitvault (add-gitvault). Doctor was completely silent about the vault
+  // even when `gitvault_policy: required` was the single thing that would break
+  // the project's next deploy (dogfood #1, finding D1) — and doctor is where a
+  // user looks when something is wrong. It also prints WHERE the keystore is:
+  // "whole-keystore loss is terminal" was stated three times across this
+  // surface while the directory to back up was stated nowhere (finding D2).
+  //
+  // Read-only and best-effort in every branch: no project, no vault, or a
+  // gateway that does not know gitvault are all ordinary and report `skipped`
+  // or `ok`, never a doctor failure. A vault-only project that has never
+  // deployed is a first-class shape (protocol D183), so its mere absence of a
+  // deploy raises nothing.
+  {
+    const projectId = (process.env.RUN402_PROJECT_ID || "").trim() || getActiveProjectId() || null;
+    if (!projectId) {
+      checks.push({
+        name: "gitvault",
+        status: "skipped",
+        ...(verbose && { hint: "no active project — run 'run402 projects use <project_id>' to check its vault." }),
+      });
+    } else {
+      try {
+        const gv = await getSdk().gitvault.status({ project_id: projectId, repo_dir: process.cwd() });
+        const value = {
+          project_id: projectId,
+          repo_id: gv.repo_id,
+          vault: gv.vault === null ? null : "allocated",
+          gitvault_policy: gv.gitvault_policy,
+          keystore_root: gv.keystore.root,
+          can_sign: gv.keystore.can_sign,
+          holds_repo_key: gv.keystore.holds_repo_key,
+          pending_overrides: gv.pending_overrides,
+          pins: gv.pins,
+          remote: gv.remote,
+        };
+        const gaps = [];
+        // The one that actually breaks the next deploy: the project demands a
+        // vaulted capture and THIS machine cannot produce one.
+        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.",
+          );
+        } 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`);
+        }
+        if (gv.remote && !gv.remote.matches) {
+          gaps.push(`the '${gv.remote.name}' git remote points at a different project than ${projectId} (${gv.remote.url})`);
+        }
+        // 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}`);
+        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}`
+            : `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
+        // wallet cannot see. None of those is a local health problem.
+        checks.push({
+          name: "gitvault",
+          status: "skipped",
+          message: describeCheckFailure("gitvault status check", err),
+        });
+      }
+    }
+  }
+
   // 7. Source-tree scan (auth-aware-ssr Section 9). Detects hallucinated
   // SDK names, state-changing GETs, auth.* in prerendered pages, and
   // direct mutation of internal.sessions.authz_version. Hits with severity

package/lib/domains.mjs

@@ -20,9 +20,6 @@ Subcommands:
   wait         <domain> [--project <id>] [--until active|safe|receive-active] [--timeout-ms <n>] [--interval-ms <n>]
   activate     <domain> [--project <id>]
   disconnect   <domain> --confirm [--project <id>]
-
-Removed:
-  add, delete. Use connect/disconnect.
 `;
 
 const SUB_HELP = {
@@ -135,15 +132,6 @@ function printHandoff(data) {
   console.error(lines.join("\n"));
 }
 
-function removed(command, replacement) {
-  fail({
-    code: "COMMAND_REMOVED",
-    message: `${command} has been removed. Use ${replacement}.`,
-    details: { command, replacement },
-    next_actions: [{ type: "use_replacement_command", command: replacement }],
-  });
-}
-
 function parseCommon(args, extraKnown = [], valueFlags = COMMON_VALUE_FLAGS) {
   const parsed = normalizeArgv(args);
   assertKnownFlags(parsed, [...valueFlags, ...extraKnown, "--help", "-h"], valueFlags);
@@ -447,8 +435,6 @@ export async function run(sub, args) {
     case "wait": await action("wait", args); break;
     case "activate": await action("activate", args); break;
     case "disconnect": await disconnect(args); break;
-    case "add": removed("run402 domains add", "run402 domains connect <domain> --project <id> --web"); break;
-    case "delete": removed("run402 domains delete", "run402 domains disconnect <domain> --project <id> --confirm"); break;
     default:
       failUnknownSubcommand("domains", sub);
   }