run402 4.24.0 → 4.25.0

package/lib/gitvault.mjs

@@ -0,0 +1,370 @@
+/**
+ * `run402 gitvault` — the host-blind encrypted Git remote (wire tag `r402s/v0`).
+ *
+ * ARCHITECTURAL LAW (gitvault-client-surface, "All protocol logic lives in the
+ * SDK"): every piece of vault protocol behaviour — crypto core, keystore,
+ * creation journal, snapshot + capture, publication state machines, ref
+ * transactions, verification budget, token exchange, repair — lives ONCE in
+ * `@run402/sdk` under `r.gitvault`. This module is a THIN ADAPTER: argument
+ * parsing, TTY output, exit codes, local file I/O. It adds zero protocol
+ * behaviour, and imports only the SDK (via `./sdk.mjs`) plus the CLI's own
+ * argument/error helpers — never a crypto, HTTP, or git library.
+ *
+ * Pipe contract (docs/style.md): the payload is JSON on stdout; every human
+ * line — progress, the terminal-loss statement, advisories — goes to stderr, so
+ * `run402 gitvault status | jq` stays clean.
+ *
+ * Run these from inside the git working tree: `repo_dir` is `process.cwd()`.
+ */
+import { readFileSync } from "node:fs";
+import { resolveProjectId } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+import {
+  normalizeArgv,
+  hasHelp,
+  assertKnownFlags,
+  parseIntegerFlag,
+  flagValue,
+  requirePositionalCount,
+  failUnknownSubcommand,
+} from "./argparse.mjs";
+
+/** Value-taking flags every gitvault subcommand accepts. */
+const COMMON_VALUE_FLAGS = ["--project", "--repo"];
+
+export const HELP = `run402 gitvault — your source, encrypted before it leaves the machine
+
+Usage:
+  run402 gitvault status  [--project <id>] [--repo <repo_id>]
+  run402 gitvault push    [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint]
+  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:
+  status    What this machine and the control plane each believe about the
+            vault: allocation, policy, whether this keystore can sign, the
+            authenticated and materialized pins, and any pending
+            unvaulted-override journals. Never reports key material.
+  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
+            receipts against the expected manifest and reads the admitted head
+            back from storage; a 200 alone is never enough.
+  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.
+  prune     Plan a prune, and — with both verifier receipts — submit it.
+            Two phases, because the protocol is two-phase; see below.
+  verify    Verify the head chain from the authenticated pin up to the newest
+            listed generation. Fails closed on a regression, a gap, or a
+            transition descriptor this client cannot validate.
+
+Options:
+  --project <id>    Project whose vault to act on (defaults to the active project)
+  --repo <repo_id>  Address the vault directly by id, skipping project lookup
+  --message <text>  push: 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
+  --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.
+  --submit          prune: submit the planned intent. Requires --intent-core and
+                    --verifier-receipt.
+  --intent-core <path>
+                    prune: the plan's \`intent_core\`, saved verbatim from a prior
+                    planning run. A rebuilt core carries a different nonce, so
+                    the r402s-verify receipt would no longer bind to it.
+  --verifier-receipt <path>
+                    prune: r402s-verify's \`verifier_receipt\` over that core.
+  --wait            prune: poll the submitted intent until the control-plane-
+                    signed completion appears, instead of returning immediately.
+  --json            No-op: stdout is already JSON.
+
+prune is TWO PHASES, because the protocol is:
+  1. \`run402 gitvault prune\` plans. It walks the verified chain, computes the GC
+     root set, subtracts it, and prints a SIGNED \`intent_core\` plus its
+     \`intent_core_sha256\`. Nothing is submitted and nothing is deleted.
+  2. Run \`r402s-verify\` against that core, then re-run with
+     \`--submit --intent-core <core.json> --verifier-receipt <receipt.json>\`.
+     The intent carries TWO receipts over the same core, one per implementation:
+     this CLI produces the \`run402-cli\` half by restoring the latest checkpoint
+     and recomputing its commitments, and \`r402s-verify\` produces the other.
+     A second receipt from this lineage would prove nothing, so it is never
+     synthesized here.
+  Only the control-plane-signed completion says what was deleted, and only its
+  \`deleted\` result means the bytes are gone — \`present_after_attempt\` is a
+  FAILED deletion, never counted as a success. There is deliberately no purge
+  verb in V0 at all. Retention is an operational promise of the platform, not a
+  cryptographic guarantee against it.
+
+Expiry is permissive, by design:
+  A retention root whose \`effective_admitted_at\` this client cannot resolve is
+  RETAINED, and a compact that cannot obtain a retention-cutoff ticket keeps
+  every root. That costs storage, never history.
+
+Terminal loss (protocol §0):
+  In V0-A, whole-machine or whole-keystore loss is terminal for vault history
+  until human envelopes ship. \`status\` prints the full statement verbatim on
+  stderr and carries it in its JSON — read it before you rely on this.
+
+Examples:
+  run402 gitvault status
+  run402 gitvault push --message "wip: refactor the parser"
+  run402 gitvault verify --budget 500
+  run402 gitvault prune --project prj_1a2b3c
+`;
+
+/**
+ * Resolve which vault to act on, plus the local git tree.
+ *
+ * `--repo` addresses the vault directly (the cold-restart path: an agent that
+ * knows its repo_id needs no project lookup). Otherwise the project is
+ * resolved the CLI-wide way — `--project`, then RUN402_PROJECT_ID, then the
+ * active project — and the SDK resolves the vault from it.
+ */
+function vaultTarget(a) {
+  const repoId = flagValue(a, "--repo");
+  const project = flagValue(a, "--project");
+  const target = { repo_dir: process.cwd() };
+  if (repoId != null) target.repo_id = repoId;
+  // Only demand a project when one is actually needed: `--repo` alone is a
+  // complete address, and requiring an active project on top of it would make
+  // the cold-restart path fail for no reason.
+  if (repoId == null || project != null) target.project_id = resolveProjectId(project);
+  return target;
+}
+
+/**
+ * Print the protocol §0 terminal-loss statement.
+ *
+ * NORMATIVE COPY, printed verbatim straight from the SDK's own constants and
+ * never paraphrased, summarized, or reassembled here. Both lines also ride in
+ * the JSON payload on stdout.
+ */
+function printTerminalLoss(status) {
+  console.error("");
+  console.error(status.terminal_loss_statement);
+  console.error(status.terminal_loss_detail);
+  console.error("");
+}
+
+async function status(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--help", "-h"], COMMON_VALUE_FLAGS);
+  requirePositionalCount(a, COMMON_VALUE_FLAGS, {
+    min: 0, max: 0, command: "run402 gitvault status", missing: "",
+  });
+  try {
+    const s = await getSdk().gitvault.status(vaultTarget(a));
+    console.log(JSON.stringify(s, null, 2));
+    printTerminalLoss(s);
+    // Advisories are echoed EXACTLY as the SDK reported them. Nothing is
+    // synthesized here — in particular a project that has never deployed gets
+    // no deploy-related warning, because a vault-only project is a first-class
+    // shape (protocol D183), not a half-configured deploy.
+    for (const w of s.warnings) console.error(`warning (${w.kind}): ${w.message}`);
+    for (const n of s.next_actions) console.error(`next: ${n.action}${n.command ? ` — ${n.command}` : ""}`);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function push(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: "",
+  });
+  const message = flagValue(a, "--message");
+  const opts = {
+    ...vaultTarget(a),
+    // 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),
+  };
+  // The message rides on `snapshot`, which is what `captureSnapshot` reads —
+  // and, since 5.12b removed the dead top-level `push({ message })` field, is
+  // the ONE place it can ride.
+  if (message != null) opts.snapshot = { message };
+  if (a.includes("--checkpoint")) opts.checkpoint = true;
+  try {
+    const result = await getSdk().gitvault.push(opts);
+    console.log(JSON.stringify(result, null, 2));
+    console.error(`published generation ${result.generation} (${result.form})`);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function compact(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--help", "-h"], COMMON_VALUE_FLAGS);
+  requirePositionalCount(a, COMMON_VALUE_FLAGS, {
+    min: 0, max: 0, command: "run402 gitvault compact", missing: "",
+  });
+  try {
+    const result = await getSdk().gitvault.compact(vaultTarget(a));
+    console.log(JSON.stringify(result, null, 2));
+    console.error(
+      `checkpoint published at generation ${result.generation}: ` +
+      `${result.covered_refs} ref(s), ${result.covered_roots} retention root(s).`,
+    );
+    if (!result.cutoff_bound) {
+      // Say what actually happened rather than reporting a clean compaction:
+      // without a ticket no root can leave the map, so this run reclaimed
+      // nothing from expiry.
+      console.error(
+        "no retention-cutoff ticket was obtained, so roots were RETAINED — expiry is permissive. " +
+        "The checkpoint published, but no expired root left the map; re-run compact once the ticket route answers.",
+      );
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+/** Read a protocol object a prior planning run (or r402s-verify) wrote to disk. */
+function readJsonFile(flag, path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    fail({
+      code: "BAD_USAGE",
+      message: `${flag} ${path} could not be read: ${err?.message ?? String(err)}`,
+      hint: "Point it at the file a prior `run402 gitvault prune` (or r402s-verify) wrote.",
+    });
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    fail({
+      code: "BAD_USAGE",
+      message: `${flag} ${path} is not valid JSON: ${err?.message ?? String(err)}`,
+      hint: "Pass the file verbatim; do not reformat or re-serialize it.",
+    });
+  }
+}
+
+async function prune(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...COMMON_VALUE_FLAGS, "--intent-core", "--verifier-receipt"];
+  assertKnownFlags(a, [...valueFlags, "--submit", "--wait", "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, {
+    min: 0, max: 0, command: "run402 gitvault prune", missing: "",
+  });
+  const submitting = a.includes("--submit");
+  const corePath = flagValue(a, "--intent-core");
+  const receiptPath = flagValue(a, "--verifier-receipt");
+  // Refuse the half-specified submit here rather than planning and silently
+  // discarding the flags — an agent that typed --submit meant to submit.
+  if (submitting && (corePath == null || receiptPath == null)) {
+    fail({
+      code: "BAD_USAGE",
+      message: "run402 gitvault prune --submit needs both --intent-core and --verifier-receipt.",
+      hint: "Plan first (`run402 gitvault prune`), save its `intent_core`, run r402s-verify against it, then submit both.",
+    });
+  }
+  if (!submitting && (corePath != null || receiptPath != null)) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--intent-core / --verifier-receipt only apply with --submit.",
+      hint: "Add --submit, or drop the flags to plan.",
+    });
+  }
+  const opts = vaultTarget(a);
+  if (submitting) {
+    opts.submit = {
+      core: readJsonFile("--intent-core", corePath),
+      verifier_receipt: readJsonFile("--verifier-receipt", receiptPath),
+    };
+    if (a.includes("--wait")) opts.submit.wait = {};
+  }
+  try {
+    const result = await getSdk().gitvault.prune(opts);
+    console.log(JSON.stringify(result, null, 2));
+    // Never imply a deletion. State what actually happened, then reproduce the
+    // SDK's own note verbatim rather than summarizing it.
+    if (!result.submitted) {
+      console.error(
+        result.blocked_reason
+          ? `planned — nothing to submit: ${result.blocked_reason}`
+          : `planned — nothing submitted. ${result.object_candidates.length} object(s) proposed for deletion` +
+            `${result.deferred_object_count > 0 ? ` (${result.deferred_object_count} more deferred to a later intent)` : ""}` +
+            `; ${result.eligible_count} retention root(s) past their window, ${result.retained_count} retained.`,
+      );
+      if (result.intent_core_sha256) {
+        console.error(`intent_core_sha256: ${result.intent_core_sha256} — run r402s-verify against this core, then re-run with --submit.`);
+      }
+    } else if (result.confirmation?.outcome) {
+      console.error(
+        `submitted — the signed completion reports ${result.confirmation.deleted.length} deleted, ` +
+        `${result.confirmation.present.length} still present` +
+        `${result.confirmation.unadjudicated.length > 0 ? `, ${result.confirmation.unadjudicated.length} unadjudicated` : ""}.`,
+      );
+    } else {
+      console.error("submitted — no completion yet. Nothing is deleted until the control-plane-signed completion says so; re-run with --wait or poll the intent.");
+    }
+    console.error(result.note);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function verify(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...COMMON_VALUE_FLAGS, "--budget"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, {
+    min: 0, max: 0, command: "run402 gitvault verify", missing: "",
+  });
+  const target = vaultTarget(a);
+  const budget = flagValue(a, "--budget");
+  if (budget != null) target.verification_budget = parseIntegerFlag("--budget", budget, { min: 1 });
+  try {
+    const state = await getSdk().gitvault.verify(target);
+    console.log(JSON.stringify(state, null, 2));
+    console.error(`verified through generation ${state.generation}`);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+export async function run(sub, args) {
+  const argv = Array.isArray(args) ? args : [];
+  if (!sub || hasHelp([sub, ...argv])) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "status": {
+      await status(argv);
+      break;
+    }
+    case "push": {
+      await push(argv);
+      break;
+    }
+    case "compact": {
+      await compact(argv);
+      break;
+    }
+    case "prune": {
+      await prune(argv);
+      break;
+    }
+    case "verify": {
+      await verify(argv);
+      break;
+    }
+    default:
+      failUnknownSubcommand("gitvault", sub, {
+        hint: "Run `run402 gitvault --help` for usage.",
+      });
+  }
+}

package/lib/init.mjs

@@ -1,4 +1,4 @@
-import { readAllowance, saveAllowance, loadKeyStore, configDir, configureApiBase } from "./config.mjs";
+import { readAllowance, saveAllowance, loadKeyStore, configDir, configureApiBase, getActiveProjectId, getProject, updateProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { setTierAction, deployAction } from "./next-actions.mjs";
@@ -37,12 +37,20 @@ Options:
   --switch-rail   Confirm switching the persisted payment rail. Re-running
                   init with the SAME rail as the existing allowance is always
                   idempotent and does not need this flag.
+  --git-remote    Also 'git init' the current directory when it is not a
+                  repository yet, so the gitvault remote can be added there.
+                  Opt-in on purpose: init is often run outside a project
+                  directory and must never create a repository somewhere you
+                  did not ask it to. Inside an EXISTING repository the remote
+                  is added without this flag (see below).
 
 Output:
   Stdout is a JSON summary { config_dir, wallet, rail, network, balances,
   tier, projects_saved, next_step }. Progress lines (Config / Allowance /
   Balance / Tier / Next) go to stderr so a human re-running interactively
   sees what's happening while a script piping stdout to jq stays clean.
+  With --git-remote the summary also carries { gitvault } (the scaffolded
+  remote) or { gitvault: null, gitvault_error } when it could not be added.
 
 Steps (idempotent when re-run with the same rail; pass --switch-rail to change rails):
   1. Creates config directory (~/.config/run402)
@@ -123,6 +131,17 @@ function parseVoucherFlag(args) {
   return { value: null, args };
 }
 
+/**
+ * Pull the boolean `--git-remote` out of argv before the rail/positional logic
+ * runs, so `run402 init --git-remote mpp` still selects the mpp rail (the same
+ * reason `--voucher` is stripped first).
+ */
+function parseGitRemoteFlag(args) {
+  const idx = args.indexOf("--git-remote");
+  if (idx === -1) return { value: false, args };
+  return { value: true, args: [...args.slice(0, idx), ...args.slice(idx + 1)] };
+}
+
 function sameOrigin(a, b) {
   try {
     return new URL(a).origin === new URL(b).origin;
@@ -154,6 +173,45 @@ function errorMessage(err) {
   return err?.message || String(err);
 }
 
+/**
+ * The owning org of the locally-active project — from the KEYSTORE first, and
+ * only then from the named inventory.
+ *
+ * Why the cache exists (task 5.12c): the gitvault scaffold is the one part of
+ * `run402 init` the client-surface spec says adds no network dependency to the
+ * cold-start path, and resolving the org through `projects.list()` quietly made
+ * that untrue. `org_id` is a non-secret routing identifier the control plane
+ * already hands back with every listing, so the honest fix is to remember it:
+ * the FIRST init on a machine still asks, every RETURNING init reads it locally
+ * and the scaffold really is network-free.
+ *
+ * Best-effort by construction — the caller treats `null` as "do not scaffold" —
+ * and an EXACT id match is required: a near-miss must never make init add a
+ * remote pointing at somebody else's project. `updateProject` is a no-op for a
+ * project this machine holds no credentials for, so such a project asks again
+ * next time rather than being silently mis-cached.
+ */
+async function resolveOwningOrgId(projectId) {
+  const cached = getProject(projectId)?.org_id;
+  if (typeof cached === "string" && cached.length > 0) return cached;
+  try {
+    const listed = await getSdk().projects.list();
+    const rows = Array.isArray(listed?.projects) ? listed.projects : [];
+    const row = rows.find((p) => (p?.id ?? p?.project_id) === projectId);
+    const orgId = row?.org_id;
+    if (typeof orgId !== "string" || orgId.length === 0) return null;
+    try {
+      updateProject(projectId, { org_id: orgId });
+    } catch {
+      // Caching is an optimization; a read-only or contended keystore costs a
+      // round trip next time and must never fail the scaffold.
+    }
+    return orgId;
+  } catch {
+    return null;
+  }
+}
+
 export async function run(args = []) {
   // Capability `astro-ssr-runtime` (v1.52): scaffold an Astro project.
   // Sub-routes when first positional is 'astro'. Handle BEFORE the
@@ -177,6 +235,10 @@ export async function run(args = []) {
   args = parsedVoucher.args;
   const voucherCode = parsedVoucher.value;
 
+  const parsedGitRemote = parseGitRemoteFlag(args);
+  args = parsedGitRemote.args;
+  const scaffoldGitRemote = parsedGitRemote.value;
+
   const parsedApiBase = parseApiBaseFlag(args);
   if (parsedApiBase.value) {
     if (parsedApiBase.args.some((arg) => typeof arg === "string" && !arg.startsWith("--"))) {
@@ -197,6 +259,16 @@ export async function run(args = []) {
         hint: "Configure the target first (`run402 init --api-base=…`), then redeem against Run402 Cloud with `run402 redeem <code>`.",
       });
     }
+    // Same reasoning as --voucher: this branch configures a target and returns
+    // without an active project, so a git scaffold has nothing to point at.
+    // Say so rather than accepting the flag and silently dropping it.
+    if (scaffoldGitRemote) {
+      fail({
+        code: "BAD_USAGE",
+        message: "run402 init --api-base cannot be combined with --git-remote.",
+        hint: "Configure the target first (`run402 init --api-base=…`), provision a project, then run `run402 init --git-remote` from the project directory.",
+      });
+    }
     const CONFIG_DIR = configDir();
     const detected = await detectTarget(parsedApiBase.value);
     const config = configureApiBase(parsedApiBase.value, {
@@ -479,6 +551,76 @@ export async function run(args = []) {
   summary.projects_saved = Object.keys(store.projects).length;
   line("Projects", `${summary.projects_saved} saved`);
 
+  // 5b. gitvault git remote (gitvault-client-surface, task 5.7).
+  //
+  // 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).
+  //
+  // 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
+  // is created, nothing is rewritten. CREATING a repository is NOT the default
+  // — `run402 init` is routinely run outside a project directory, and
+  // `git init`-ing whatever directory the user happened to be in would be a
+  // genuinely bad surprise. `--git-remote` opts into that one step.
+  //
+  // NON-FATAL in every branch: a missing git, a directory that is not a
+  // repository, an unreachable gateway, or a `run402` remote already pointing
+  // somewhere else must warn and let setup finish.
+  const activeProjectId = getActiveProjectId();
+  if (activeProjectId) {
+    summary.gitvault = null;
+    try {
+      // Dynamic import: the scaffold is the only thing here that needs the
+      // Node SDK's hardened git runner, and a top-level import would drag it
+      // into every init invocation (and every test that mocks ./sdk.mjs).
+      const { hardenedGit } = await import("#sdk/node");
+      let insideRepo = true;
+      try {
+        await hardenedGit(process.cwd(), ["rev-parse", "--git-dir"]);
+      } catch {
+        insideRepo = false;
+      }
+      if (!insideRepo && !scaffoldGitRemote) {
+        summary.gitvault_skipped = "not a git repository — re-run with --git-remote to create one and add the remote";
+        line("Gitvault", "skipped — not a git repository (--git-remote creates one)");
+      } else {
+        const orgId = await resolveOwningOrgId(activeProjectId);
+        if (!orgId) {
+          summary.gitvault_skipped = `could not resolve the owning org for ${activeProjectId} — the run402 remote was not added`;
+          line("Gitvault", "skipped — owning org unresolved");
+        } else {
+          const remote = await getSdk().gitvault.scaffoldRemote({
+            repo_dir: process.cwd(),
+            org_id: orgId,
+            project_id: activeProjectId,
+          });
+          // `allocated: false` is stated, not left to be inferred: this was
+          // local git only, and no vault exists for the project yet.
+          summary.gitvault = { ...remote, allocated: false };
+          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`);
+          } 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}`);
+          }
+        }
+      }
+    } catch (err) {
+      const reason = errorMessage(err);
+      summary.gitvault = null;
+      summary.gitvault_error = {
+        code: err?.body?.code ?? err?.code ?? "GITVAULT_SCAFFOLD_FAILED",
+        message: reason,
+      };
+      line("Gitvault", `remote not added: ${reason}`);
+    }
+  }
+
   // 6. Next step — canonical typed action(s); `next_step` is the back-compat
   // string mirror of the first action's command (one spelling, surface-wide).
   write("");

package/lib/pay.test.mjs

@@ -53,11 +53,7 @@ describe("run402 pay", () => {
                 headers: { "content-type": "application/json" },
               }),
               payment: {
-                amount_usd_micros: 10_000,
-                pay_to: "0xseller",
                 network: "eip155:8453",
-                tx_ref: "0xtx",
-                url,
                 paymentId: "txp_cli_1",
                 amountUsdMicros: 10_000,
                 asset: "USDC",

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "run402",
-  "version": "4.24.0",
+  "version": "4.25.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {
-    "run402": "cli.mjs"
+    "run402": "cli.mjs",
+    "git-remote-run402": "git-remote-run402.mjs"
   },
   "imports": {
+    "#sdk": "./sdk/dist/index.js",
     "#sdk/node": "./sdk/dist/node/index.js"
   },
   "scripts": {
@@ -14,13 +16,17 @@
   },
   "files": [
     "cli.mjs",
+    "git-remote-run402.mjs",
     "lib/",
     "fixtures/",
     "core-dist/",
     "sdk/"
   ],
   "dependencies": {
+    "@hpke/chacha20poly1305": "^1.8.0",
+    "@hpke/core": "^1.9.0",
     "@humanwhocodes/momoa": "3.3.10",
+    "@noble/ciphers": "^2.3.0",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
     "@scure/base": "1.2.6",

package/sdk/dist/index.d.ts

@@ -20,7 +20,6 @@ import { Tier } from "./namespaces/tier.js";
 import { Allowance } from "./namespaces/allowance.js";
 import { Ai } from "./namespaces/ai.js";
 import { Auth } from "./namespaces/auth.js";
-import { SenderDomain } from "./namespaces/sender-domain.js";
 import { Billing } from "./namespaces/billing.js";
 import { Vouchers } from "./namespaces/vouchers.js";
 import { Wallets, ScopedWallet } from "./namespaces/wallets.js";
@@ -46,6 +45,7 @@ import { Errors } from "./namespaces/errors.js";
 import { Pay, type PayExecutor } from "./namespaces/pay.js";
 import { IdentityLinks } from "./namespaces/identity-links.js";
 import { Buzz } from "./namespaces/buzz.js";
+import { Gitvault } from "./namespaces/gitvault.js";
 import type { ContentSource, FileSet } from "./namespaces/deploy.types.js";
 import { ScopedRun402 } from "./scoped.js";
 export interface Run402Options {
@@ -86,7 +86,6 @@ export declare class Run402 {
     readonly ai: Ai;
     readonly image: Ai;
     readonly auth: Auth;
-    readonly senderDomain: SenderDomain;
     readonly billing: Billing;
     readonly vouchers: Vouchers;
     readonly wallets: Wallets;
@@ -164,6 +163,20 @@ export declare class Run402 {
     readonly identityLinks: IdentityLinks;
     /** Buzz human adoption, community installation, and bounded agent enrollment workflows. */
     readonly buzz: Buzz;
+    /**
+     * gitvault — the host-blind encrypted Git remote (`r402s/v0`). Vault reads
+     * (record, heads listing, policy) run anywhere; the verbs that touch a git
+     * tree or the on-disk keystore (`init`, `push`, `compact`, `verify`,
+     * `deploy`, `restore`) are Node-only and load `@run402/sdk/node` lazily.
+     *
+     * This namespace is where ALL vault protocol logic lives: the CLI's
+     * `run402 gitvault …`, `git-remote-run402`, and the MCP tools are adapters
+     * over it and add no behaviour of their own.
+     *
+     * Durability is keystore-qualified: the vault protects source history from
+     * host-side loss while a principal keystore survives.
+     */
+    readonly gitvault: Gitvault;
     readonly idempotency: {
         fromParts: typeof fromParts;
     };
@@ -341,11 +354,15 @@ export { Buzz, BuzzHumanAdoptions, BuzzHumanAdoptionOffers, BuzzCommunityInstall
 export type * from "./namespaces/buzz.types.js";
 export type * from "./namespaces/buzz-notifications.types.js";
 export type * from "./namespaces/secrets.js";
-export type * from "./namespaces/sender-domain.js";
 export type * from "./namespaces/service.js";
 export type * from "./namespaces/sites.js";
 export type * from "./namespaces/subdomains.js";
 export type * from "./namespaces/tier.js";
 export { ScopedWallet } from "./namespaces/wallets.js";
 export type * from "./namespaces/wallets.js";
+export * from "./namespaces/gitvault.crypto.js";
+export type * from "./namespaces/gitvault.crypto.js";
+export type * from "./namespaces/gitvault.types.js";
+export { Gitvault, gitvaultRemoteUrl, parseGitvaultRemoteUrl } from "./namespaces/gitvault.js";
+export type * from "./namespaces/gitvault.js";
 //# sourceMappingURL=index.d.ts.map