run402 4.38.0 → 4.38.1

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

@@ -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/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() };
+}

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 {
@@ -168,19 +169,36 @@ Examples:
  * 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 +355,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 +381,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 +470,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 +513,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 +582,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 +628,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.",
+  });
+}

package/lib/repos.mjs

@@ -38,7 +38,7 @@ import { withAutoApprove } from "./operator.mjs";
 import { allowanceAuthHeaders, isCoreApiTarget, resolveProjectId } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { resolveOrgId, resolveOwningOrgId } from "./org-context.mjs";
-import { nextAction } from "./next-actions.mjs";
+import { nextAction, claimOrgSlugAction, claimRepoNameAction } from "./next-actions.mjs";
 import { printKeystoreLocation } from "./gitvault.mjs";
 import { gitvaultRemoteUrlForRepo } from "#sdk";
 import {
@@ -214,19 +214,32 @@ async function create(args) {
     // a missing slug, or any other refusal just means no address this time;
     // `run402 repos name <name>` claims it explicitly later.
     let address = null;
+    let orgSlug = null;
     try {
       const orgRecord = await getSdk().org(effectiveOrgId).get();
-      if (orgRecord.slug) {
+      orgSlug = orgRecord.slug ?? null;
+      if (orgSlug) {
         const candidate = slugifyRepoName(name);
         if (candidate) {
           const named = await getSdk().projects.setRepoName(provisioned.project_id, candidate);
-          address = gitvaultRemoteUrlForRepo(orgRecord.slug, named.repo_name);
+          address = gitvaultRemoteUrlForRepo(orgSlug, named.repo_name);
         }
       }
     } catch (err) {
       console.error(`repo name not claimed (non-fatal): ${err?.message ?? String(err)}`);
     }
 
+    // `address: null` used to have no pointer to WHY, or to the
+    // named-addressing feature at all (kychee-com/run402#560): an agent
+    // reading the output had no path from "address is null" to
+    // `run402 org slug`/`run402 repos name`. One typed next_actions entry,
+    // pointing at whichever half is actually missing.
+    const nextActions = address
+      ? []
+      : orgSlug
+        ? [claimRepoNameAction(provisioned.project_id)]
+        : [claimOrgSlugAction()];
+
     const out = {
       project_id: provisioned.project_id,
       repo_id: vault.repo_id,
@@ -237,6 +250,7 @@ async function create(args) {
       recovery_receipt: vault.recovery_receipt,
       terminal_loss_statement: vault.terminal_loss_statement,
       deployed: false,
+      next_actions: nextActions,
     };
     console.log(JSON.stringify(out, null, 2));
     console.error(
@@ -244,6 +258,13 @@ async function create(args) {
       (vault.deduplicated ? "already existed — nothing was re-allocated" : `allocated (genesis ${vault.genesis_sha256})`),
     );
     if (address) console.error(`address: ${address}`);
+    else if (!orgSlug) {
+      console.error(
+        "no named address yet — claim an org slug (run402 org slug <slug>, one-time $1) to get run402::<slug>/<name> addresses",
+      );
+    } else {
+      console.error(`no address claimed — run 'run402 repos name <name> --project ${provisioned.project_id}' to claim one`);
+    }
     if (vault.remote) console.error(`remote '${vault.remote.name}' -> ${vault.remote.url} (${vault.remote.reason})`);
     console.error("");
     console.error(vault.terminal_loss_statement);

package/lib/up.mjs

@@ -585,14 +585,31 @@ function looksLikeGitRemoteUrl(source) {
   return /^[a-z][a-z0-9+.-]*:\/\//i.test(source) || /^[^\s@]+@[^\s:]+:/.test(source);
 }
 
-/** `git init` only when `dir` is not a repository yet. Returns whether it did. */
+/**
+ * `git init` only when `dir` is not a repository yet. Returns whether it did.
+ *
+ * `-b main`, not whatever `init.defaultBranch` (or the pre-2.28 hardcoded
+ * `master`) happens to be — the docs teach `git push origin main`, and the
+ * gitvault remote helper's own dangling-HEAD hazard note (a first push of
+ * any OTHER branch leaves HEAD naming a ref that does not exist yet) is
+ * exactly what a mismatched default branch here would walk `up` straight
+ * into. `-b` needs git 2.28+ (2020); an older git falls back to the same
+ * result by a different route — `symbolic-ref` on a still-empty repository
+ * has no existing ref to disturb, so it is exactly as safe as `-b main`
+ * would have been. Mirrors `Gitvault.scaffoldRemote`'s identical fallback.
+ */
 async function gitInitIfNeeded(dir) {
   const { hardenedGit } = await import("#sdk/node");
   try {
     await hardenedGit(dir, ["rev-parse", "--git-dir"]);
     return false;
   } catch {
-    await hardenedGit(dir, ["init", "-q", "-b", "main", "."]);
+    try {
+      await hardenedGit(dir, ["init", "-q", "-b", "main", "."]);
+    } catch {
+      await hardenedGit(dir, ["init", "-q", "."]);
+      await hardenedGit(dir, ["symbolic-ref", "HEAD", "refs/heads/main"]);
+    }
     return true;
   }
 }