run402 4.37.1 → 4.38.1

package/README.md

@@ -65,7 +65,9 @@ run402 repos list --org org_1a2b3c
 run402 repos delete prj_xyz --force           # refuses without --force while the vault holds generations
 ```
 
-A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. `repos create|list|delete` and `gitvault`'s mutating verbs (`init`, `snapshot`, `policy`, `compact`, `prune`) are CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete). See `run402 gitvault --help` and `run402 repos --help` for the full surface, and the CLI reference's `gitvault` / `repos` sections for the terminal-loss statement and the progressive backup warning.
+A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. `repos create|list|delete|name` and `gitvault`'s mutating verbs (`init`, `snapshot`, `policy`, `compact`, `prune`) are CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete). See `run402 gitvault --help` and `run402 repos --help` for the full surface, and the CLI reference's `gitvault` / `repos` sections for the terminal-loss statement and the progressive backup warning.
+
+**Named addressing (design D6).** `run402 org slug <slug>` (owner-only, small one-time fee) claims an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos name <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
 
 ### Allowance
 

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

@@ -28,6 +28,21 @@
  * completes the push. One command, no prior `gitvault init`. `git ls-remote`
  * / `fetch` stay pure reads and allocate nothing.
  *
+ * NAMED ADDRESSING + PUSH-TO-CREATE (repo-first-onramp task 4, design D6).
+ * `run402::<org>/<name>` admits TWO forms in the same slot — id-form
+ * (`org_id`/`prj_...`, unchanged: resolved via `r.gitvault.openOrCreate`
+ * above) and slug-form (`run402::<org-slug>/<name>`, e.g.
+ * `run402::acme/my-notes`) — discriminated by
+ * `gitvaultRemoteAddressForm`. A slug-form remote resolves through
+ * `r.gitvault.resolveOrCreateAddress`, which ALSO drives push-to-create on a
+ * miss (`push` only; `list`/`fetch` pass `allow_create: false`, same "reads
+ * never allocate" discipline as the id-form path) and PINS the resolved
+ * `repo_id` in this checkout's local git config the first time it resolves
+ * (task 4.5) — every later invocation on THIS checkout goes straight to the
+ * pinned id, skipping the address resolution round-trip entirely and
+ * surviving a later rename of either half. `SLUG_RELEASED` is never
+ * auto-followed: it refuses, naming the successor slug.
+ *
  * 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,
@@ -68,7 +83,8 @@
 
 import { createInterface } from "node:readline";
 import { getSdk } from "./lib/sdk.mjs";
-import { parseGitvaultRemoteUrl } from "#sdk";
+import { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } from "./lib/wallet-context.mjs";
+import { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } from "#sdk";
 import { hardenedGit, resolveGitInvocationRepo } from "#sdk/node";
 
 const out = (line) => process.stdout.write(`${line}\n`);
@@ -76,15 +92,91 @@ 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);
-  return oneLine(code ? `${code}: ${message}` : message);
+  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);
+  const suffix = released?.successor_slug ? ` (renamed to "${released.successor_slug}" — update the remote and re-run)` : "";
+  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);
 }
 
 /**
@@ -132,7 +224,10 @@ async function main(argv) {
   // `org_id` rides in the parsed address (`run402::<org_id>/<project_id>`),
   // so it costs nothing extra to carry — it is exactly what D2's lazy
   // creation needs to allocate an unresolved vault from `runPush` below, with
-  // no separate lookup.
+  // no separate lookup. Only meaningful for an ID-FORM address; a slug-form
+  // one resolves through `resolveOrCreateAddress` instead (below), which
+  // needs no separate org_id at all — the gateway resolves the slug itself.
+  const addressForm = gitvaultRemoteAddressForm(address);
   const target = { project_id: address.project_id, org_id: address.org_id };
   let verbosity = 1;
 
@@ -160,25 +255,42 @@ async function main(argv) {
     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;
-
   /** A 404/absent-vault refusal — the "nothing here yet" shape, never a genuine failure to mask. */
   function isVaultNotFound(err) {
     return err?.status === 404 || err?.code === "RESOURCE_NOT_FOUND" || err?.code === "ROUTE_NOT_FOUND";
   }
 
   /**
-   * Open the vault, allocating it first when it does not exist yet (D2). Used
-   * ONLY by `runPush` — `list`/`fetch` stay pure reads and never create
-   * anything (see `runList`'s own not-found handling below).
+   * Open the vault lazily — `capabilities` and `option` must never touch the
+   * network. Dispatches on the address form (design D6): id-form is
+   * BYTE-IDENTICAL to before (`gitvault.open` with `{org_id, project_id}`);
+   * slug-form resolves (and, on the first successful resolution, PINS
+   * `repo_id` in local git state — task 4.5) through
+   * `gitvault.resolveOrCreateAddress` with `allow_create: false` — a read
+   * never allocates, same discipline the id-form path already had.
+   */
+  const openVault = async (repoDir) => {
+    if (addressForm === "id") return (await getSdk().gitvault.open(repoDir ? { ...target, repo_dir: repoDir } : target)).vault;
+    const result = await getSdk().gitvault.resolveOrCreateAddress({ address, allow_create: false, ...(repoDir ? { repo_dir: repoDir } : {}) });
+    return result.handle.vault;
+  };
+
+  /**
+   * Open the vault, allocating it first when it does not exist yet (D2), and
+   * — for a SLUG-form address whose name does not resolve yet —
+   * PUSH-TO-CREATE it (design D6, task 4.4/4.5). Used ONLY by `runPush` —
+   * `list`/`fetch` stay pure reads and never create anything (see
+   * `runList`'s own not-found handling below).
    *
    * Prints the one-shot recovery receipt and the keystore path to stderr the
    * moment allocation happens, per the client-surface spec: an agent reads
    * stderr, and the receipt is worth exactly as many copies as get kept.
    */
   async function openOrCreateVault(repoDir) {
-    const result = await getSdk().gitvault.openOrCreate({ ...target, repo_dir: repoDir });
+    const result =
+      addressForm === "id"
+        ? await getSdk().gitvault.openOrCreate({ ...target, repo_dir: repoDir })
+        : await getSdk().gitvault.resolveOrCreateAddress({ address, repo_dir: repoDir, allow_create: true });
     if (!result.found && result.created) {
       note("");
       note(`vault ${result.handle.repo_id} allocated (genesis ${result.created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
@@ -195,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();
@@ -235,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}`);
@@ -249,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

@@ -197,6 +197,11 @@ export const COMMAND_MANIFEST = [
   { path: ["org", "get"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "rename"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--name", "Gate"] },
   { path: ["org", "payout-wallet"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
+  // repo-first-onramp task 4.1 (design D6). `--org` (not a positional org_id
+  // like rename/payout-wallet above) goes through resolveOrg's SHAPE
+  // validation (a real UUID) — "org_gate1" fails that locally, so this needs
+  // the same UUID-shaped fixture `org use` below already established.
+  { path: ["org", "slug"], positionals: [p("slug")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["acme", "--org", "11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "audit"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
@@ -274,6 +279,8 @@ export const COMMAND_MANIFEST = [
   { path: ["repos", "create"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "provisions a project, allocates a vault, and scaffolds a real git remote into cwd" },
   { path: ["repos", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "cross-references live projects against their live gitvault status, one call per project" },
   { path: ["repos", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [], runStyle: "sub", skipBehavioral: "irreversibly deletes a project after reading its live vault generation count" },
+  // repo-first-onramp task 4.2 (design D6): explicit address-form name claim.
+  { path: ["repos", "name"], positionals: [p("name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "claims a per-org-unique repo name against a live project" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────

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,
@@ -408,9 +409,18 @@ 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): when
+  // cwd is a repository with its own pinned repo id or run402/origin remote,
+  // doctor now 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`). Doctor has no
+  // `--project`/`--repo` flag of its own, so there is no explicit tier here.
   {
-    const projectId = (process.env.RUN402_PROJECT_ID || "").trim() || getActiveProjectId() || null;
-    if (!projectId) {
+    const target = await resolveGitvaultTarget({ repoDir: process.cwd() });
+    const projectId = target.project_id ?? null;
+    const repoId = target.repo_id ?? null;
+    if (!projectId && !repoId) {
       checks.push({
         name: "gitvault",
         status: "skipped",
@@ -418,9 +428,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 +459,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() };
+}