run402 4.38.0 → 4.38.2

package/core-dist/keystore.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getLegacyProjectsPath, getProjectCredentialsPath } from "./config.js";
 import { clearActiveProjectId as clearProfileActiveProjectId, getActiveProjectId as getProfileActiveProjectId, recordMigration, setActiveProjectId as setProfileActiveProjectId, } from "./profile-state.js";
+import { readAllowance } from "./allowance.js";
 function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     const lockDir = path + ".lock";
     mkdirSync(dirname(path), { recursive: true });
@@ -95,7 +96,11 @@ function migrateLegacyProjectsJson(targetPath) {
     };
     saveKeyStore(cache, targetPath);
     if (legacy.active_project_id) {
-        setProfileActiveProjectId(legacy.active_project_id);
+        // Scoped the same way every other write in this module now is (see
+        // `currentPrincipal`'s doc comment) — an unscoped write here is exactly
+        // what poisons the "unknown"-principal bucket for good on a machine that
+        // migrates before its wallet allowance exists yet.
+        setProfileActiveProjectId(legacy.active_project_id, undefined, { principal: currentPrincipal() });
     }
     recordMigration("projects_json_import", {
         legacy_path: legacyPath,
@@ -165,12 +170,59 @@ export function removeProject(projectId, path) {
         saveKeyStore(store, p);
     });
     if (!path)
-        clearProfileActiveProjectId(projectId);
+        clearProfileActiveProjectId(projectId, undefined, { principal: currentPrincipal() });
+}
+/**
+ * The active-project scope's `principal`, derived from the CURRENT wallet's
+ * allowance — matching exactly what `NodeCredentialsProvider.setActiveProject`
+ * (sdk/src/node/credentials.ts) writes after `projects.provision` /
+ * `projects.use`. Without this, every reader here used the profile-state
+ * module's own default (empty) scope, which resolves to a FIXED
+ * "unknown"-principal bucket — the same bucket for every wallet in this
+ * profile.
+ *
+ * That mismatch is silent for a brand-new profile (the flat fallback in
+ * `profile-state.ts#getActiveProjectId` happens to agree), but once the
+ * "unknown" bucket is EVER populated by any principal-less write — the
+ * one-time legacy `projects.json` migration below, or any provision/`use`
+ * call made before this machine had a wallet allowance — it never gets
+ * updated again (real wallet operations write to the principal-keyed
+ * bucket, not "unknown") and PERMANENTLY shadows every later wallet-scoped
+ * activation for every caller that reads through this module: `resolveProjectId`
+ * / `resolveProject` (cli/lib/config.mjs), `projects current`, and every
+ * gitvault-verb target resolution. That is the root cause behind
+ * kychee-com/run402#559(a) — `repos create` DID call `projects.provision`,
+ * whose `creds.setActiveProject` correctly persisted the new project under
+ * the real wallet's scoped bucket AND the flat fallback, but every CLI read
+ * of "the active project" kept resolving the OLD "unknown"-bucket entry
+ * first and never fell through to the freshly-updated flat value.
+ *
+ * Best-effort: an unreadable/malformed allowance degrades to `null` (the
+ * same "unknown" bucket callers already tolerated before this fix), never a
+ * throw — this is a read-scoping concern, not an allowance-validity one.
+ */
+function currentPrincipal() {
+    try {
+        return readAllowance()?.address ?? null;
+    }
+    catch {
+        return null;
+    }
 }
 export function getActiveProjectId(path) {
-    return getProfileActiveProjectId(path);
+    return getProfileActiveProjectId(path, { principal: currentPrincipal() });
 }
 export function setActiveProjectId(projectId, path) {
-    setProfileActiveProjectId(projectId, path);
+    setProfileActiveProjectId(projectId, path, { principal: currentPrincipal() });
+}
+/**
+ * Scoped the same way as the getter/setter above — a caller reaching for
+ * `profile-state.ts`'s `clearActiveProjectId` directly (unscoped) clears only
+ * the "unknown"-principal bucket, leaving a real wallet's own scoped entry
+ * (set through `setActiveProjectId` above, or `NodeCredentialsProvider`)
+ * untouched and still resolvable.
+ */
+export function clearActiveProjectId(projectId, path) {
+    clearProfileActiveProjectId(projectId, path, { principal: currentPrincipal() });
 }
 //# sourceMappingURL=keystore.js.map

package/git-remote-run402.mjs

@@ -71,7 +71,7 @@
  *   - `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.
+ *     `run402 gitvault snapshot`, 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
@@ -83,6 +83,7 @@
 
 import { createInterface } from "node:readline";
 import { getSdk } from "./lib/sdk.mjs";
+import { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } from "./lib/wallet-context.mjs";
 import { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } from "#sdk";
 import { hardenedGit, resolveGitInvocationRepo } from "#sdk/node";
 
@@ -91,14 +92,81 @@ const out = (line) => process.stdout.write(`${line}\n`);
 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);
+/**
+ * Wallet selection (kychee-com/run402#558). Before this, this file called
+ * `getSdk()` directly and ran NO wallet selection at all — a `.run402.json`
+ * binding, and even the global `wallets use` default, silently never
+ * reached it; only the `RUN402_WALLET` env layer worked, so a bound
+ * checkout's very next `git push run402 main` after a correctly-bound
+ * `run402 repos create` used the WRONG wallet's (usually empty) allowance.
+ *
+ * Shares `resolveWalletCore`/`enforceWalletExistsCore` with the CLI
+ * (`cli/lib/wallet-context.mjs`) — ONE implementation, minus the CLI's
+ * `--wallet` flag layer (this binary parses no argv flags at all). Resolved
+ * and applied (`process.env.RUN402_WALLET`) once per invocation, right
+ * before the first credential-touching call — never for `capabilities` /
+ * `option`, which touch neither credentials nor the network.
+ *
+ * WHICH DIRECTORY the binding walk starts from is NOT uniform, for the same
+ * fail-closed reason this file's own header explains for repository
+ * resolution: `list` needs no repository (a repository-free `git ls-remote`
+ * outside any checkout must keep working), so it walks from `process.cwd()`.
+ * `fetch`/`push` DO have a resolved repository by the time wallet selection
+ * runs (`requireRepo()` already succeeded) — walking from ITS directory
+ * rather than cwd is what makes `git clone` (cwd = wherever clone was RUN
+ * FROM, not the target repo) pick up a binding committed in the target
+ * repository, not whatever checkout happened to be current.
+ */
+let resolvedWallet = null;
+
+function applyWalletForDir(dir) {
+  const resolved = resolveWalletCore({ env: process.env, cwd: dir });
+  enforceWalletExistsCore(resolved);
+  process.env.RUN402_WALLET = resolved.name;
+  resolvedWallet = resolved;
+  return resolved;
+}
+
+/** The resolved wallet's selection source, in the same words the CLI's own `--wallet` provenance line uses. `null` for the bare, unselected default. */
+function walletSourceLabel(resolved) {
+  if (!resolved) return null;
+  if (resolved.source === "env") return "RUN402_WALLET";
+  if (resolved.source === "binding") return resolved.sourceDetail; // the .run402.json path
+  if (resolved.source === "config") return "wallets use";
+  return null; // "default" — nothing selected anything
+}
+
+/**
+ * The allowance-missing/malformed family (`core/src/allowance.ts`'s own
+ * throws) all end with "Back up the file and run 'run402 init' to recreate
+ * it." — a remedy that assumes the resolved wallet is the one you meant.
+ * That is only true when NOTHING selected a wallet (the bare default); when
+ * an env var or a binding DID name one, the remedy is actively harmful —
+ * `run402 init` recreates the DEFAULT wallet's allowance, a DIFFERENT
+ * wallet than the one that was actually resolved and whose allowance is
+ * actually missing/broken (kychee-com/run402#558's second defect). Replace
+ * it with the resolved wallet's name and how selection works, so the fix is
+ * "correct the selection" rather than "recreate the wrong wallet".
+ */
+function enrichAllowanceError(message) {
+  if (!resolvedWallet || !/allowance\.json/.test(message)) return message;
+  const source = walletSourceLabel(resolvedWallet);
+  const stripped = message.replace(/\s*Back up the file and run 'run402 init' to recreate it\.?/, "").trim();
+  if (!source) {
+    // Genuinely the bare default wallet with no override anywhere — the
+    // original remedy already names the right target.
+    return `${stripped} Back up the file and run 'run402 init' to recreate it.`;
+  }
+  return (
+    `${stripped} Resolved wallet '${resolvedWallet.name}' via ${source} ` +
+    "(order: RUN402_WALLET env > .run402.json binding > 'wallets use' default > default). " +
+    `Wrong wallet? Fix selection instead. Right wallet, just no allowance yet? 'run402 wallets new ${resolvedWallet.name}'.`
+  );
 }
 
 function describeError(err) {
   const code = err?.code ?? err?.body?.code ?? null;
-  const message = err?.message ?? err?.body?.message ?? String(err);
+  const message = enrichAllowanceError(err?.message ?? err?.body?.message ?? String(err));
   // SLUG_RELEASED is never auto-followed — but the successor slug (design D6)
   // is exactly the fact a human/agent reading stderr needs to act on it.
   const released = gitvaultSlugReleasedInfo(err);
@@ -106,6 +174,11 @@ function describeError(err) {
   return oneLine(code ? `${code}: ${message}${suffix}` : message);
 }
 
+/** Protocol lines are single-line: collapse anything that could break framing. */
+function oneLine(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
+}
+
 /**
  * Resolve the vault address from git's argv.
  *
@@ -234,6 +307,10 @@ async function main(argv) {
   }
 
   async function runList() {
+    // `list` needs no repository (a repository-free `git ls-remote` outside
+    // any checkout must keep working) — the binding walk falls back to cwd,
+    // same as `capabilities`/`option`'s repository-free tier.
+    applyWalletForDir(process.cwd());
     let state;
     try {
       state = await (await openVault()).materialize();
@@ -274,6 +351,10 @@ async function main(argv) {
       repoRefusalNote(err);
       return 1;
     }
+    // The repository is resolved — walk the binding from ITS directory, not
+    // cwd (the "WHICH REPOSITORY" note above: during `git clone` cwd is
+    // wherever clone was run FROM, unrelated to the target repository).
+    applyWalletForDir(repoDir);
     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}`);
@@ -288,6 +369,8 @@ async function main(argv) {
       // 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();
+      // Same "walk from the resolved repository, not cwd" rule as `fetch`.
+      applyWalletForDir(repoDir);
       const newOids = new Map();
       for (const spec of specs) {
         // A deletion carries an empty <src>. Everything else is resolved by

package/lib/command-manifest.mjs

@@ -433,7 +433,11 @@ export const COMMAND_MANIFEST = [
   { path: ["service", "health"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["cache", "inspect"], positionals: [p("url")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["https://example.com/"] },
   { path: ["cache", "invalidate"], positionals: [p("url", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--all", "--host", "example.com"] },
-  { path: ["doctor"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
+  // projectScoped (kychee-com/run402#566): --project targets the gitvault
+  // check only (see doctor.mjs's own HELP) — every other check stays
+  // wallet/machine-wide, but the gate's contract is "accepts --project
+  // without rejecting it," which this satisfies.
+  { path: ["doctor"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
   { path: ["webhook-secret", "rotate"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["logs"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--request-id", "req_gate123"], runStyle: "merged" },
 ];

package/lib/doctor.mjs

@@ -12,7 +12,8 @@
  */
 
 import { existsSync, statSync } from "node:fs";
-import { configDir, readAllowance, loadKeyStore, getActiveProjectId } from "./config.mjs";
+import { configDir, readAllowance, loadKeyStore } from "./config.mjs";
+import { resolveGitvaultTarget } from "./gitvault-target.mjs";
 import { getSdk } from "./sdk.mjs";
 import {
   resolveScanRoot,
@@ -23,11 +24,15 @@ import { doctorUpdateCheck } from "./update-check.mjs";
 import { buildBuzzDoctorReport, parseBuzzDoctorArgs } from "./buzz-doctor.mjs";
 import { queueBuzzDoctorTelemetry } from "./diagnostic-telemetry.mjs";
 import { fail } from "./sdk-errors.mjs";
+import { normalizeArgv, assertKnownFlags, flagValue } from "./argparse.mjs";
+
+/** Value-taking flags (kychee-com/run402#566 — the flag set doctor actually parses; anything else is BAD_USAGE via assertKnownFlags, never silently ignored). */
+const DOCTOR_VALUE_FLAGS = ["--scan-dir", "--buzz-agent", "--project"];
 
 const HELP = `run402 doctor — Health and config diagnostics
 
 Usage:
-  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>]
+  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>] [--project <id>]
   run402 --wallet <profile> doctor --buzz --buzz-agent <npub-or-hex>
 
 Output:
@@ -40,9 +45,17 @@ Options:
   --refresh      Wait for a bounded live npm version check for the run402 CLI
   --no-scan      Skip the source-tree scan (config / health checks only)
   --scan-dir D   Scan a custom directory instead of \`<cwd>/src\`
+  --project <id> Target THIS project's gitvault check instead of the repo-standing
+                 default (the 4.38.0 pin / run402 remote / RUN402_PROJECT_ID / active
+                 project, in that order — see \`gitvault-target.mjs\`). Scoped to the
+                 gitvault check only; every other check is wallet/machine-wide, not
+                 per-project, and is unaffected by this flag.
   --buzz         Run only the zero-mutation Buzz setup preflight
   --buzz-agent P Bind Buzz mode to the intended public agent npub or hex key
 
+Any flag not listed above is rejected (BAD_USAGE / UNKNOWN_FLAG), never
+silently ignored.
+
 Telemetry:
   Buzz preflight sends only anonymous allowlisted start/pass/block counters.
   No identity, wallet, relay, domain, path, command output, or installation id
@@ -108,16 +121,25 @@ function describeCheckFailure(label, err) {
 }
 
 export async function run(sub, args = []) {
-  const all = [sub, ...args].filter(Boolean);
+  const all = normalizeArgv([sub, ...args].filter(Boolean));
   if (all.includes("--help") || all.includes("-h")) {
     console.log(HELP);
     return;
   }
+  // kychee-com/run402#566 (--project half): doctor used to accept ANY flag
+  // silently — an unrecognized one (a typo, or --project before this fix)
+  // was simply never looked at. Any flag doctor actually parses is listed
+  // here; anything else is now a structured BAD_USAGE/UNKNOWN_FLAG rejection
+  // instead of quietly doing nothing.
+  assertKnownFlags(all, ["--verbose", "--refresh", "--no-scan", "--buzz", ...DOCTOR_VALUE_FLAGS], DOCTOR_VALUE_FLAGS);
   const verbose = all.includes("--verbose");
   const refresh = all.includes("--refresh");
   const skipScan = all.includes("--no-scan");
   const scanDirArgIdx = all.indexOf("--scan-dir");
   const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
+  // Scoped to the gitvault check (see HELP): every other check is
+  // wallet/machine-wide, not per-project.
+  const projectOverride = flagValue(all, "--project");
 
   const buzzArgs = parseBuzzDoctorArgs(all);
   if (buzzArgs.error) fail(buzzArgs.error);
@@ -408,9 +430,20 @@ export async function run(sub, args = []) {
   // 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.
+  //
+  // TARGETING (repo-first-onramp follow-up, kychee-com/run402#559d, extended
+  // by kychee-com/run402#566's --project half): when cwd is a repository
+  // with its own pinned repo id or run402/origin remote, doctor checks THAT
+  // vault, not the profile's active project — the same pin > remote >
+  // RUN402_PROJECT_ID env > active-project order every other gitvault verb
+  // follows (`gitvault-target.mjs`). An explicit `--project <id>` outranks
+  // all of that (the resolver's own top tier), same as every other gitvault
+  // verb's `--project`.
   {
-    const projectId = (process.env.RUN402_PROJECT_ID || "").trim() || getActiveProjectId() || null;
-    if (!projectId) {
+    const target = await resolveGitvaultTarget({ repoDir: process.cwd(), explicitProjectId: projectOverride ?? undefined });
+    const projectId = target.project_id ?? null;
+    const repoId = target.repo_id ?? null;
+    if (!projectId && !repoId) {
       checks.push({
         name: "gitvault",
         status: "skipped",
@@ -418,9 +451,12 @@ export async function run(sub, args = []) {
       });
     } else {
       try {
-        const gv = await getSdk().gitvault.status({ project_id: projectId, repo_dir: process.cwd() });
+        const gv = await getSdk().gitvault.status({
+          ...(repoId ? { repo_id: repoId } : { project_id: projectId }),
+          repo_dir: process.cwd(),
+        });
         const value = {
-          project_id: projectId,
+          project_id: gv.project_id ?? projectId,
           repo_id: gv.repo_id,
           vault: gv.vault === null ? null : "allocated",
           gitvault_policy: gv.gitvault_policy,
@@ -446,7 +482,7 @@ export async function run(sub, args = []) {
           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})`);
+          gaps.push(`the '${gv.remote.name}' git remote points at a different project than ${value.project_id} (${gv.remote.url})`);
         }
         // Echoed exactly as the SDK reported them — including the
         // doctor-persistent `grandfathered` advisory it owns.

package/lib/gitvault-target.mjs

@@ -0,0 +1,145 @@
+/**
+ * Shared "which vault does this repo mean" resolution for `run402 gitvault`
+ * and `run402 doctor`'s gitvault check (repo-first-onramp follow-up,
+ * kychee-com/run402#559's design gap): gitvault verbs were purely
+ * active-project-scoped even when run standing inside a repository that
+ * already names its own vault via a pinned repo id or a run402/origin
+ * remote — git muscle memory says a command run inside a repo acts on THAT
+ * repo, and a stale active-project pointer silently targeted a DIFFERENT
+ * one instead (GITVAULT_ACCESS_DENIED, or worse, a silently WRONG vault).
+ *
+ * Targeting order for a verb run standing inside a git repository, highest
+ * first:
+ *   1. an explicit --repo/--project flag (owned by each call site — this
+ *      module supplies only the fallback chain beneath it, plus the
+ *      mismatch warning against tier 3)
+ *   2. the 4.38.0 pin (`r402.repoId` in local git config) — addresses the
+ *      vault by repo_id directly, no network read at all
+ *   3. the repo's run402/origin remote address — id-form is parsed
+ *      directly out of the address string (free, no network); slug-form is
+ *      resolved via the SDK (one read-only network call — `resolveAddress`,
+ *      never a pin, never a push-to-create; this is a TARGETING read, not a
+ *      publish)
+ *   4. RUN402_PROJECT_ID env
+ *   5. the profile's active project
+ *
+ * Outside a repository (or when repo detection itself fails), only tiers 4
+ * and 5 apply — unchanged from before this module existed.
+ *
+ * ARCHITECTURAL NOTE: this is CLI-edge policy (which flag/env/file wins),
+ * not gitvault protocol behavior — the same class of concern
+ * `wallet-context.mjs` owns for wallet selection. The protocol reads it
+ * composes (`readPinnedGitvaultRepo`, `resolveAddress`) already live once in
+ * the SDK; this module adds no protocol logic of its own.
+ */
+import { getActiveProjectId } from "./config.mjs";
+
+/**
+ * Tiers 4/5 (RUN402_PROJECT_ID env, then the active project) — deliberately
+ * NON-throwing, unlike `config.mjs#resolveProjectId`. `run402 doctor`'s
+ * gitvault check needs to report "skipped" gracefully when nothing resolves
+ * anywhere (its pre-existing, tested behavior); a `fail()`-triggered
+ * `process.exit()` here would abort doctor's ENTIRE report, not just this
+ * one check. Callers that DO want the historical PROJECT_REQUIRED failure
+ * (gitvault.mjs's own verbs) get it by falling back to `resolveProjectId`
+ * themselves when this returns `null` — see `vaultTarget` in gitvault.mjs.
+ */
+function envOrActiveProjectId() {
+  return (process.env.RUN402_PROJECT_ID || "").trim() || getActiveProjectId() || null;
+}
+
+async function isInsideGitRepo(repoDir) {
+  try {
+    const { hardenedGit } = await import("#sdk/node");
+    await hardenedGit(repoDir, ["rev-parse", "--git-dir"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The repo's OWN target, independent of any flag — the pin first, then the
+ * `run402`/`origin` remote (in that order, mirroring `scaffoldRemote`'s own
+ * naming precedence). `null` when the repo has neither, when this is not a
+ * repository at all, or (slug-form only) the remote fails to resolve over
+ * the network — a miss here is always ordinary, never thrown.
+ */
+export async function repoOwnGitvaultTarget(repoDir) {
+  if (!(await isInsideGitRepo(repoDir))) return null;
+
+  const { hardenedGit, readPinnedGitvaultRepo } = await import("#sdk/node");
+  const pinned = await readPinnedGitvaultRepo(repoDir);
+  if (pinned) return { repo_id: pinned.repo_id, project_id: null, source: "pin" };
+
+  const { parseGitvaultRemoteUrl, gitvaultRemoteAddressForm } = await import("#sdk");
+  for (const name of ["run402", "origin"]) {
+    let url;
+    try {
+      url = (await hardenedGit(repoDir, ["remote", "get-url", name])).text().trim();
+    } catch {
+      continue; // no such remote — try the other conventional name
+    }
+    if (!url) continue;
+    const address = parseGitvaultRemoteUrl(url);
+    if (!address) continue; // exists, but isn't a run402 address — try the other name
+    if (gitvaultRemoteAddressForm(address) === "id") {
+      // id-form already carries both halves in the address string — no
+      // network read needed at all.
+      return { repo_id: null, project_id: address.project_id, source: "remote", remote_name: name };
+    }
+    try {
+      const { getSdk } = await import("./sdk.mjs");
+      const resolved = await getSdk().gitvault.resolveAddress(address);
+      return { repo_id: resolved.repo_id, project_id: resolved.project_id, source: "remote", remote_name: name };
+    } catch {
+      // Offline, SLUG_RELEASED, not-found, ... — nothing to target from this
+      // rung; a caller falls through to env/active project.
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve `{ repo_id?, project_id? }` for a gitvault verb that addresses a
+ * vault the same way `--repo`/`--project` already do — pin beats remote
+ * beats env beats active project, an explicit flag beats all of them.
+ * `explicitProjectId`/`explicitRepoId` are the already-parsed flag values
+ * (`undefined`/`null` when absent — this module owns no flag parsing), and
+ * either, neither, or both may be set (mirroring `--repo`/`--project`
+ * together being valid on the CLI today). `warn` receives the one-line
+ * mismatch note when an explicit flag disagrees with the repo's OWN target;
+ * the flag still wins either way. The pin carries no project_id to compare
+ * for free, so only `--repo` is checked against it; only the remote tier
+ * carries a project_id for free (id-form) or resolves one (slug-form), so
+ * only `--project` is checked against it — matching the task's own wording
+ * ("a mismatch between an explicit flag and the repo's remote").
+ */
+export async function resolveGitvaultTarget({
+  repoDir = process.cwd(),
+  explicitProjectId,
+  explicitRepoId,
+  warn = (line) => console.error(line),
+} = {}) {
+  const needsOwn = explicitRepoId == null || explicitProjectId == null;
+  const own = needsOwn ? await repoOwnGitvaultTarget(repoDir) : null;
+
+  if (explicitRepoId != null && own?.source === "pin" && own.repo_id !== explicitRepoId) {
+    warn(`warning: --repo ${explicitRepoId} does not match this repo's pinned vault ${own.repo_id} — using --repo ${explicitRepoId}.`);
+  }
+  if (explicitProjectId != null && own?.source === "remote" && own.project_id && own.project_id !== explicitProjectId) {
+    warn(`warning: --project ${explicitProjectId} does not match this repo's '${own.remote_name}' remote project ${own.project_id} — using --project ${explicitProjectId}.`);
+  }
+
+  if (explicitRepoId != null || explicitProjectId != null) {
+    const result = {};
+    if (explicitRepoId != null) result.repo_id = explicitRepoId;
+    if (explicitProjectId != null) result.project_id = explicitProjectId;
+    return result;
+  }
+
+  if (own?.source === "pin") return { repo_id: own.repo_id };
+  if (own?.source === "remote" && own.project_id) return { project_id: own.project_id };
+  return { project_id: envOrActiveProjectId() };
+}

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 { resolveGitvaultTarget } from "./gitvault-target.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import {
@@ -158,29 +159,48 @@ Terminal loss (protocol §0):
 Examples:
   run402 gitvault init
   run402 gitvault status --refs
-  run402 gitvault push --message "wip: refactor the parser"
+  run402 gitvault snapshot --message "wip: refactor the parser"
   run402 gitvault policy grandfathered --reason "migrating CI to a vaulted client"
   run402 gitvault verify --budget 500
   run402 gitvault prune --project prj_1a2b3c
+  # \`gitvault push\` still works as a deprecation-warning alias for \`snapshot\`
+  # for one release; it will be removed next release.
 `;
 
 /**
  * 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.
+ * knows its repo_id needs no project lookup). Otherwise the project targets,
+ * highest first: `--project` > the repo's own pin/remote > RUN402_PROJECT_ID
+ * > the active project (repo-first-onramp follow-up, kychee-com/run402#559 —
+ * see `gitvault-target.mjs`'s module doc for the full targeting order and
+ * why it exists: a stale active-project pointer used to silently outrank the
+ * repository this command is actually standing in).
  */
-function vaultTarget(a) {
+async function vaultTarget(a) {
   const repoId = flagValue(a, "--repo");
   const project = flagValue(a, "--project");
-  const target = { repo_dir: process.cwd() };
+  const repoDir = process.cwd();
+  const resolved = await resolveGitvaultTarget({
+    repoDir,
+    explicitProjectId: project ?? undefined,
+    explicitRepoId: repoId ?? undefined,
+  });
+  const target = { repo_dir: repoDir };
   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);
+  // complete address, and requiring one on top of it would make the
+  // cold-restart path fail for no reason.
+  if (repoId == null || project != null) {
+    if ("repo_id" in resolved && project == null) target.repo_id = resolved.repo_id;
+    // `resolveGitvaultTarget` reports its last (env/active) tier
+    // non-throwingly (`run402 doctor`'s call site needs that) — this call
+    // site is the one that historically failed closed with PROJECT_REQUIRED
+    // when nothing resolves anywhere, and still does: `resolveProjectId`
+    // re-derives the exact same env/active check and throws.
+    if ("project_id" in resolved) target.project_id = resolved.project_id ?? resolveProjectId(project);
+  }
   return target;
 }
 
@@ -337,7 +357,7 @@ async function policy(args) {
     });
   }
 
-  const target = vaultTarget(a);
+  const target = await vaultTarget(a);
   try {
     const sdk = getSdk();
     const repoId = target.repo_id ?? (await sdk.gitvault.forProject(target.project_id)).repo_id;
@@ -363,7 +383,7 @@ async function status(args) {
   requirePositionalCount(a, COMMON_VALUE_FLAGS, {
     min: 0, max: 0, command: "run402 gitvault status", missing: "",
   });
-  const target = vaultTarget(a);
+  const target = await vaultTarget(a);
   if (a.includes("--refs")) target.refs = true;
   try {
     const s = await getSdk().gitvault.status(target);
@@ -452,7 +472,7 @@ async function snapshot(args) {
   // it is skipped there, matching `open()`'s own precedence. Skipped
   // entirely for a slug-form remote (`address` above) — that resolves
   // through the address, not a project_id, and needs no separate org_id.
-  const target = address ? { repo_dir: repoDir } : vaultTarget(a);
+  const target = address ? { repo_dir: repoDir } : await vaultTarget(a);
   const orgId = !address && target.project_id ? await resolveOwningOrgId(target.project_id) : null;
   const opts = {
     ...target,
@@ -495,7 +515,7 @@ async function compact(args) {
     min: 0, max: 0, command: "run402 gitvault compact", missing: "",
   });
   try {
-    const result = await getSdk().gitvault.compact(vaultTarget(a));
+    const result = await getSdk().gitvault.compact(await vaultTarget(a));
     console.log(JSON.stringify(result, null, 2));
     console.error(
       `checkpoint published at generation ${result.generation}: ` +
@@ -564,7 +584,7 @@ async function prune(args) {
       hint: "Add --submit, or drop the flags to plan.",
     });
   }
-  const opts = vaultTarget(a);
+  const opts = await vaultTarget(a);
   if (submitting) {
     opts.submit = {
       core: readJsonFile("--intent-core", corePath),
@@ -610,7 +630,7 @@ async function verify(args) {
   requirePositionalCount(a, valueFlags, {
     min: 0, max: 0, command: "run402 gitvault verify", missing: "",
   });
-  const target = vaultTarget(a);
+  const target = await vaultTarget(a);
   const budget = flagValue(a, "--budget");
   if (budget != null) target.verification_budget = parseIntegerFlag("--budget", budget, { min: 1 });
   try {

package/lib/next-actions.mjs

@@ -66,3 +66,28 @@ export function deployAction() {
     why: "Apply your release manifest to deploy.",
   });
 }
+
+/**
+ * `repos create` (and `gitvault init`) on an org with no claimed slug: the
+ * response's `address: null` had no pointer to WHY, or to the named-addressing
+ * feature at all (kychee-com/run402#560). One-time $1 fee, owner-only.
+ */
+export function claimOrgSlugAction() {
+  return nextAction("claim_org_slug", {
+    command: "run402 org slug <slug>",
+    why: "This organization has no claimed slug yet, so its repos have no run402::<slug>/<name> address. One-time $1, owner-only.",
+  });
+}
+
+/**
+ * The org already has a slug, but this project's address-form repo name was
+ * not claimed this time (a collision, or the best-effort claim failed for
+ * some other reason) — point at the explicit claim verb instead of leaving
+ * `address: null` unexplained.
+ */
+export function claimRepoNameAction(projectId) {
+  return nextAction("claim_repo_name", {
+    command: `run402 repos name <name> --project ${projectId}`,
+    why: "The owning organization has a slug, but this project has no claimed address-form name yet.",
+  });
+}