run402 4.25.0 → 4.26.0

package/cli.mjs

@@ -49,7 +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 (status/push/compact/prune/verify)
+  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)

package/git-remote-run402.mjs

@@ -19,6 +19,17 @@
  *   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/
@@ -39,15 +50,17 @@
  *     `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.
- *   - The repository is discovered from `process.cwd()` (git's own upward
- *     discovery). `hardenedGit` scrubs `GIT_DIR`/`GIT_WORK_TREE` on purpose, so
- *     an invocation from outside the work tree is not supported.
+ *   - `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 } from "#sdk/node";
+import { hardenedGit, resolveGitInvocationRepo } from "#sdk/node";
 
 const out = (line) => process.stdout.write(`${line}\n`);
 /** Every helper response block is terminated by a blank line. */
@@ -107,12 +120,35 @@ async function main(argv) {
     return 1;
   }
 
-  const repoDir = process.cwd();
-  const target = { project_id: address.project_id, repo_dir: repoDir };
+  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 () => (await getSdk().gitvault.open(target)).vault;
+  const openVault = async (repoDir) => (await getSdk().gitvault.open(repoDir ? { ...target, repo_dir: repoDir } : target)).vault;
 
   async function runList() {
     const state = await (await openVault()).materialize();
@@ -128,30 +164,49 @@ async function main(argv) {
   }
 
   async function runFetch(batch) {
-    if (verbosity >= 1) note(`restoring the vault object database for ${batch.length} ref(s)`);
-    const restored = await getSdk().gitvault.restore({ ...target, target_dir: repoDir });
+    // 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 {
-      const vault = await openVault();
-      const base = await vault.materialize();
-      const updates = [];
+      // 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) {
-        const expectedOld = base.refs?.[spec.dst] ?? null;
         // 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.
-        const newOid = spec.src === ""
+        newOids.set(spec, spec.src === ""
           ? null
-          : (await hardenedGit(repoDir, ["rev-parse", "--verify", "--end-of-options", spec.src])).text().trim();
+          : (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: newOid,
+          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,
@@ -166,10 +221,12 @@ async function main(argv) {
     } 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) {
@@ -200,18 +257,19 @@ async function main(argv) {
   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 = [];
-      await runFetch(batch);
-      return;
+      return await runFetch(batch);
     }
     if (pushBatch.length > 0) {
       const batch = pushBatch;
       pushBatch = [];
-      await runPush(batch);
+      return await runPush(batch);
     }
+    return 0;
   }
 
   const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
@@ -219,7 +277,8 @@ async function main(argv) {
     for await (const raw of rl) {
       const line = raw.replace(/\r$/, "");
       if (line === "") {
-        await flushBatches();
+        const code = await flushBatches();
+        if (code !== 0) return code;
         continue;
       }
       const space = line.indexOf(" ");
@@ -254,8 +313,7 @@ async function main(argv) {
     // 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.
-    await flushBatches();
-    return 0;
+    return await flushBatches();
   } finally {
     rl.close();
   }

package/lib/command-manifest.mjs

@@ -238,8 +238,10 @@ export const COMMAND_MANIFEST = [
   // 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" },

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