run402 4.37.0 → 4.38.0

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/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,7 @@
 
 import { createInterface } from "node:readline";
 import { getSdk } from "./lib/sdk.mjs";
-import { parseGitvaultRemoteUrl } from "#sdk";
+import { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } from "#sdk";
 import { hardenedGit, resolveGitInvocationRepo } from "#sdk/node";
 
 const out = (line) => process.stdout.write(`${line}\n`);
@@ -84,7 +99,11 @@ function oneLine(value) {
 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);
+  // 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);
 }
 
 /**
@@ -132,7 +151,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 +182,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:`);
@@ -189,12 +228,6 @@ async function main(argv) {
       } catch {
         // Never let a diagnostic line fail a push that already allocated successfully.
       }
-      try {
-        const { GITVAULT_ALLOCATION_POLICY_ADVISORY } = await import("./lib/gitvault-scaffold.mjs");
-        note(GITVAULT_ALLOCATION_POLICY_ADVISORY);
-      } catch {
-        // Same rule: advisory only, never fatal.
-      }
       note("");
     }
     return result.handle.vault;

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/gitvault-scaffold.mjs

@@ -19,20 +19,6 @@
 import { getSdk } from "./sdk.mjs";
 import { resolveOwningOrgId } from "./org-context.mjs";
 
-/**
- * The interim allocation→policy advisory (repo-first-onramp D3, stated as an
- * interim). TODAY the platform sets `gitvault_policy: required` at allocation
- * — the decoupling (allocation leaving the policy unset) is design D3's
- * gateway half and ships in a later release (task 3.1). Until it does, every
- * client-side path that allocates a vault prints this line so the policy flip
- * is never a silent side effect of a push or a create. Faithful over flattering:
- * documenting the designed future as the present is the breach; this line is
- * the truth. DELETE this export (and its four call sites) when the gateway
- * decoupling ships.
- */
-export const GITVAULT_ALLOCATION_POLICY_ADVISORY =
-  "note: allocation currently sets gitvault_policy to 'required' — from now on a deploy must present a vaulted capture (produced automatically by `run402 deploy apply` on any machine holding this keystore). Opt out with `run402 gitvault policy grandfathered --reason \"<why>\"`. A later release decouples allocation from the deploy gate (design D3).";
-
 /**
  * @param {object} options
  * @param {string} [options.repoDir] Working tree to scaffold. Defaults to `process.cwd()`.

package/lib/gitvault.mjs

@@ -19,7 +19,6 @@
 import { readFileSync } from "node:fs";
 import { resolveProjectId } from "./config.mjs";
 import { resolveOwningOrgId } from "./org-context.mjs";
-import { GITVAULT_ALLOCATION_POLICY_ADVISORY } from "./gitvault-scaffold.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import {
@@ -70,8 +69,12 @@ Subcommands:
             deploy — a vault-only project snapshots for months without one.
             Against a project with no vault yet, this ALLOCATES one inline
             (the six-stage creation, same as \`init\`) before publishing — one
-            command, no prior \`gitvault init\`. The one-shot recovery receipt
-            and keystore path print to stderr the moment that happens.
+            command, no prior \`gitvault init\`. When --repo/--project are
+            both omitted and the local run402/origin remote is a slug-form
+            address (run402::<org-slug>/<name>), PUSH-TO-CREATES through it
+            instead (design D6) — same as pushing that name with \`git\`. The
+            one-shot recovery receipt and keystore path print to stderr the
+            moment that happens.
             Before reporting a snapshot as landed the SDK compares finalization
             receipts against the expected manifest and reads the admitted head
             back from storage; a 200 alone is never enough. \`push\` is a
@@ -284,7 +287,6 @@ async function init(args) {
     );
     if (result.remote) console.error(`remote '${result.remote.name}' -> ${result.remote.url} (${result.remote.reason})`);
     if (remoteSkipped) console.error(`remote not added: ${remoteSkipped}`);
-    if (!result.deduplicated) console.error(GITVAULT_ALLOCATION_POLICY_ADVISORY);
     // The recovery receipt is integrity data, not a secret, and it is worth
     // exactly as much as the number of copies you keep. It is persisted into
     // the keystore automatically; say where, because "keep many copies" is
@@ -372,6 +374,15 @@ async function status(args) {
     if (s.remote) {
       console.error(`remote '${s.remote.name}': ${s.remote.url}${s.remote.matches ? "" : "  ← points at a DIFFERENT project than this status"}`);
     }
+    // The id-pinning state (design D6, task 4.5): a slug-form remote pins
+    // repo_id in local git state the first time it resolves; id-form pins
+    // nothing (it needs no pin — see resolveGitvaultAddress's doc comment).
+    if (s.pinned) {
+      console.error(
+        `pinned: repo_id ${s.pinned.repo_id}` +
+        (s.pinned.resolved_from ? ` (resolved from run402::${s.pinned.resolved_from.org_slug}/${s.pinned.resolved_from.repo_name})` : ""),
+      );
+    }
     if (s.refs) {
       const names = Object.keys(s.refs).sort();
       console.error(names.length === 0 ? "refs: (none yet)" : `refs (${names.length}):`);
@@ -398,6 +409,33 @@ async function status(args) {
  * only the dispatched SUBCOMMAND name changed (see `run()` below, where
  * `gitvault push` survives one release as a deprecation-warning alias).
  */
+/**
+ * D6 (repo-first-onramp task 4): when neither `--repo` nor `--project` was
+ * given explicitly, look at the local `run402`/`origin` remote (in that
+ * order, mirroring `scaffoldRemote`'s own naming) and, if it is a SLUG-form
+ * address (`run402::<org-slug>/<name>`), return the parsed address so
+ * `snapshot` can push-to-create through it — the same address-form
+ * resolution `git push` drives via the remote helper. `null` for an
+ * id-form remote, no remote at all, or an explicit `--repo`/`--project`.
+ */
+async function detectSlugFormRemote(a, repoDir) {
+  if (flagValue(a, "--repo") != null || flagValue(a, "--project") != null) return null;
+  const { hardenedGit } = await import("#sdk/node");
+  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;
+    }
+    if (!url) continue;
+    const address = parseGitvaultRemoteUrl(url);
+    if (address && gitvaultRemoteAddressForm(address) === "slug") return address;
+  }
+  return null;
+}
+
 async function snapshot(args) {
   const a = normalizeArgv(args);
   const valueFlags = [...COMMON_VALUE_FLAGS, "--message"];
@@ -406,14 +444,19 @@ async function snapshot(args) {
     min: 0, max: 0, command: "run402 gitvault snapshot", missing: "",
   });
   const message = flagValue(a, "--message");
-  const target = vaultTarget(a);
+  const repoDir = process.cwd();
+  const address = await detectSlugFormRemote(a, repoDir);
   // D2: lazily allocate the vault on first push when there is a project to
   // resolve the owning org from — the same resolution `gitvault init` uses.
   // `--repo`-only addressing has nothing to create FROM (no project_id), so
-  // it is skipped there, matching `open()`'s own precedence.
-  const orgId = target.project_id ? await resolveOwningOrgId(target.project_id) : null;
+  // 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 orgId = !address && target.project_id ? await resolveOwningOrgId(target.project_id) : null;
   const opts = {
     ...target,
+    ...(address ? { address } : {}),
     ...(orgId ? { org_id: orgId } : {}),
     // The gitvault_commit line is progress, not payload: print it the moment
     // the snapshot exists, well before the publication round-trips finish, so
@@ -428,7 +471,6 @@ async function snapshot(args) {
       console.error(`vault allocated (genesis ${created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
       console.error(JSON.stringify(created.recovery_receipt));
       await printKeystoreLocation();
-      console.error(GITVAULT_ALLOCATION_POLICY_ADVISORY);
       console.error("");
     },
   };

package/lib/org.mjs

@@ -30,6 +30,7 @@ Usage:
   run402 org get    <org_id>
   run402 org rename <org_id> --name <display_name>   (or: --clear to remove the label)
   run402 org payout-wallet <org_id> --wallet <wallet_address>  (or: --clear to remove the explicit default)
+  run402 org slug   <slug> [--org <org_id>]
   run402 org whoami
   run402 org use     <org_id>
   run402 org current
@@ -53,6 +54,9 @@ Subcommands:
   list        Orgs you are a member of
   get         Read one org (label + tier/lease + your role)
   rename      Set or clear an org's display label (owner-only)
+  slug        Claim or rename the org's globally-unique, address-form slug
+              (owner-only). A genesis claim spends a one-time claim fee; a
+              rename releases the old slug into a ~90-day cooldown.
   use         Select the current org for this wallet profile
   current     Report the resolved current org and where it came from
   clear       Clear this wallet profile's org selection
@@ -120,6 +124,26 @@ Legacy (still supported):
 
 Owner-only + step-up gated. Pass --clear (or an empty display_name) to remove
 the label. Output includes the updated tier and lease timestamps.
+`,
+  slug: `run402 org slug — claim or rename the org's address-form slug
+
+Usage:
+  run402 org slug <slug> [--org <org_id>] [--idempotency-key <key>]
+
+The slug is a globally-unique, claimable, address-form handle for the org
+(repo-first-onramp design D6) — the <org-slug> half of a named repo address
+run402::<org-slug>/<name>. Grammar: lowercase [a-z0-9-], no leading/trailing/
+double hyphen, max 39 chars. Owner-only.
+
+A genesis claim (the org had no prior slug) spends a one-time claim fee off
+the org's balance. A rename is free but releases the OLD slug into a ~90-day
+cooldown: it stops resolving, with a typed SLUG_RELEASED refusal naming the
+new slug as successor — there is no redirect, so update every remote and
+address that still names the old one.
+
+This is a paid, side-effecting mutation and requires Idempotency-Key; the SDK
+generates one automatically unless --idempotency-key is passed, so a retried
+call after a dropped response can never double-bill.
 `,
   "payout-wallet": `run402 org payout-wallet — set or clear the tenant route payout wallet
 
@@ -413,6 +437,51 @@ async function payoutWallet(args) {
   }
 }
 
+/**
+ * `run402 org slug <slug>` — claim or rename the org's address-form slug
+ * (repo-first-onramp design D6). Owner-only, and a genesis claim spends a
+ * one-time claim fee — this is a PAID, side-effecting mutation, so it
+ * requires `Idempotency-Key`; the SDK generates one client-side when
+ * `--idempotency-key` is omitted, so a retried call after a dropped response
+ * can never double-bill.
+ */
+async function slug(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--org", "--idempotency-key"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  const [newSlug] = requirePositionalCount(a, valueFlags, {
+    min: 1,
+    max: 1,
+    command: "run402 org slug <slug> [--org <org_id>]",
+    missing: "Missing <slug>.",
+  });
+  const org = await resolveOrg(a, { cmd: "org" });
+  if (!org) {
+    fail({
+      code: "ORG_UNRESOLVED",
+      message: "Could not resolve which organization to claim this slug for.",
+      hint: "Pass --org <org_id>, or select one first with `run402 org use <id>`.",
+    });
+  }
+  const idempotencyKey = flagValue(a, "--idempotency-key");
+  try {
+    const result = await getSdk().org(org.orgId).claimSlug(newSlug, idempotencyKey != null ? { idempotencyKey } : {});
+    console.log(JSON.stringify(result, null, 2));
+    if (result.created) {
+      console.error(`slug "${result.slug}" claimed for ${org.orgId} — a one-time claim fee was debited from the org's balance.`);
+    } else if (result.previous_slug && result.previous_slug !== result.slug) {
+      console.error(
+        `org ${org.orgId} renamed from "${result.previous_slug}" to "${result.slug}" — no fee. ` +
+        `"${result.previous_slug}" now enters its ~90-day release cooldown: it stops resolving with a typed SLUG_RELEASED refusal (naming "${result.slug}" as the successor), never a redirect. Update every remote and address that still names it.`,
+      );
+    } else {
+      console.error(`"${result.slug}" was already ${org.orgId}'s current slug — nothing changed, no fee.`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function audit(args) {
   const a = normalizeArgv(args);
   const valueFlags = ["--limit", "--after", "--before"];
@@ -630,6 +699,7 @@ export async function run(sub, args) {
     case "get": await get(args); break;
     case "rename": await rename(args); break;
     case "payout-wallet": await payoutWallet(args); break;
+    case "slug": await slug(args); break;
     case "whoami": await whoami(args); break;
     case "use": await use(args); break;
     case "current": await current(args); break;

package/lib/repos.mjs

@@ -35,12 +35,12 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { withAutoApprove } from "./operator.mjs";
-import { allowanceAuthHeaders, isCoreApiTarget } from "./config.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 { printKeystoreLocation } from "./gitvault.mjs";
-import { GITVAULT_ALLOCATION_POLICY_ADVISORY } from "./gitvault-scaffold.mjs";
+import { gitvaultRemoteUrlForRepo } from "#sdk";
 import {
   normalizeArgv,
   hasHelp,
@@ -57,21 +57,30 @@ Usage:
   run402 repos create <name> [--org <org_id>] [--dir <path>] [--tier <tier>]
   run402 repos list   [--org <org_id>]
   run402 repos delete <project_id> [--force]
+  run402 repos name   <name> [--project <id>]
 
 Subcommands:
   create  Provision a project, ALLOCATE its vault (mints key material and a
           one-shot recovery receipt), and scaffold the run402 remote —
           origin when free, run402 when taken (D1). No deploy plan, no
           release, nothing deployed: the vault-only track (design D8), for a
-          project that only ever hosts encrypted source.
+          project that only ever hosts encrypted source. When the owning org
+          has a slug (run402 org slug), also claims the project's address-
+          form repo name (best-effort — a name collision or missing slug
+          never fails the command) and prints the run402::<slug>/<name>
+          address (design D6).
   list    The organization's vault-bearing projects — those with an
           allocated vault, whether or not they have ever deployed. Not
-          every project in the org; ones with no vault are omitted.
+          every project in the org; ones with no vault are omitted. Shows
+          the run402::<slug>/<name> address for a repo that has claimed one.
   delete  Delete the project and everything in it (database, functions,
           subdomains, mailbox, secrets). REFUSES while the vault holds any
           admitted generation unless --force is passed — this is
           irreversible and destroys the vault's entire encrypted history
           along with everything else.
+  name    Claim or rename the project's per-org-unique, address-form name
+          (design D6) — the <name> half of run402::<org-slug>/<name>. No
+          fee, unlike the org slug. Same authority as renaming the project.
 
 Options:
   --org <org_id>    create/list: the owning organization. create resolves it
@@ -89,6 +98,8 @@ Options:
                      derived from the name)
   --force           delete: proceed even though the vault holds generations
                      that would be permanently and irrecoverably lost
+  --project <id>    name: project to claim the repo name for (default: the
+                     active project)
   --json            No-op: stdout is already JSON.
 
 There is no separate gitvault price: bytes count against the same
@@ -98,6 +109,7 @@ organization-pooled storage budget every project already has.
 const CREATE_VALUE_FLAGS = ["--org", "--dir", "--tier", "--idempotency-key"];
 const LIST_VALUE_FLAGS = ["--org"];
 const DELETE_VALUE_FLAGS = ["--project"];
+const NAME_VALUE_FLAGS = ["--project"];
 
 function validateProjectName(name) {
   if (name === "") {
@@ -124,6 +136,24 @@ function validateProjectName(name) {
   }
 }
 
+/**
+ * Best-effort slugify for the address-form repo name (design D6's grammar:
+ * lowercase [a-z0-9-], no leading/trailing/double hyphen, <=63 chars). The
+ * free-text project display name (`repos create <name>`'s positional) is
+ * NOT already in this charset, so `create` derives a candidate rather than
+ * sending the raw name straight to the claim route and failing on the first
+ * space or capital letter.
+ */
+function slugifyRepoName(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 63)
+    .replace(/-+$/g, "");
+}
+
 async function create(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--help", "-h"], CREATE_VALUE_FLAGS);
@@ -178,9 +208,29 @@ async function create(args) {
       project_id: provisioned.project_id,
       repo_dir: dir,
     });
+    // Best-effort address-form name claim (design D6): when the owning org
+    // has a slug, name this repo so it is reachable as
+    // run402::<slug>/<name> too — never fails `create` itself. A collision,
+    // a missing slug, or any other refusal just means no address this time;
+    // `run402 repos name <name>` claims it explicitly later.
+    let address = null;
+    try {
+      const orgRecord = await getSdk().org(effectiveOrgId).get();
+      if (orgRecord.slug) {
+        const candidate = slugifyRepoName(name);
+        if (candidate) {
+          const named = await getSdk().projects.setRepoName(provisioned.project_id, candidate);
+          address = gitvaultRemoteUrlForRepo(orgRecord.slug, named.repo_name);
+        }
+      }
+    } catch (err) {
+      console.error(`repo name not claimed (non-fatal): ${err?.message ?? String(err)}`);
+    }
+
     const out = {
       project_id: provisioned.project_id,
       repo_id: vault.repo_id,
+      address,
       remote: vault.remote,
       deduplicated: vault.deduplicated,
       genesis_sha256: vault.genesis_sha256,
@@ -193,11 +243,11 @@ async function create(args) {
       `project ${provisioned.project_id} provisioned; vault ${vault.repo_id} ` +
       (vault.deduplicated ? "already existed — nothing was re-allocated" : `allocated (genesis ${vault.genesis_sha256})`),
     );
+    if (address) console.error(`address: ${address}`);
     if (vault.remote) console.error(`remote '${vault.remote.name}' -> ${vault.remote.url} (${vault.remote.reason})`);
     console.error("");
     console.error(vault.terminal_loss_statement);
     await printKeystoreLocation();
-    if (!vault.deduplicated) console.error(GITVAULT_ALLOCATION_POLICY_ADVISORY);
     console.error("");
     console.error("nothing was deployed — this is a vault-only repo. Deploy later with `run402 deploy apply`, or never.");
   } catch (err) {
@@ -246,8 +296,21 @@ async function list(args) {
       genesis_admitted_at: status.vault.genesis_admitted_at,
     });
   }
-  console.log(JSON.stringify({ org_id: orgId, repos }, null, 2));
+  // The org's slug, when claimed (design D6) — printed so a human/agent can
+  // construct run402::<slug>/<name> addresses by hand. There is deliberately
+  // no per-project `address` field here yet: the gateway has no bulk (or
+  // even single) READ for a project's claimed repo_name today, only the
+  // WRITE route (`POST /projects/v1/:id/repo-name`) — adding one is gateway
+  // work, out of scope for this client-only change (see the final report).
+  let orgSlug = null;
+  try {
+    orgSlug = (await getSdk().org(orgId).get()).slug;
+  } catch {
+    // Best-effort — `list` must not fail over an org-slug lookup.
+  }
+  console.log(JSON.stringify({ org_id: orgId, org_slug: orgSlug, repos }, null, 2));
   console.error(`${repos.length} vault-bearing project(s) of ${projects.length} total in this organization`);
+  if (orgSlug) console.error(`org slug: ${orgSlug} — a repo with a claimed address-form name is reachable at run402::${orgSlug}/<name>`);
 }
 
 async function del(args) {
@@ -299,6 +362,41 @@ async function del(args) {
   }
 }
 
+/**
+ * `run402 repos name <name> [--project <id>]` — the explicit address-form
+ * claim (design D6, task 4.2): a project gets its per-org-unique `<name>`
+ * half of `run402::<org-slug>/<name>` either at push-to-create time or here.
+ */
+async function name(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...NAME_VALUE_FLAGS, "--help", "-h"], NAME_VALUE_FLAGS);
+  const [repoName] = requirePositionalCount(a, NAME_VALUE_FLAGS, {
+    min: 1, max: 1, command: "run402 repos name <name> [--project <id>]", missing: "run402 repos name <name>: a name is required",
+  });
+  const projectId = resolveProjectId(flagValue(a, "--project"));
+  try {
+    const result = await getSdk().projects.setRepoName(projectId, repoName);
+    let address = null;
+    try {
+      const owningOrg = await resolveOwningOrgId(projectId);
+      const orgSlug = owningOrg ? (await getSdk().org(owningOrg).get()).slug : null;
+      if (orgSlug) address = gitvaultRemoteUrlForRepo(orgSlug, result.repo_name);
+    } catch {
+      // The claim itself already succeeded — a failed address-preview lookup is never fatal.
+    }
+    console.log(JSON.stringify({ ...result, address }, null, 2));
+    console.error(
+      result.previous_repo_name && result.previous_repo_name !== result.repo_name
+        ? `renamed from "${result.previous_repo_name}" to "${result.repo_name}"`
+        : `name "${result.repo_name}" claimed for ${projectId}`,
+    );
+    if (address) console.error(`address: ${address}`);
+    else console.error("this org has no slug yet — claim one with `run402 org slug <slug>` to get a full run402::<slug>/<name> address");
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 export async function run(sub, args) {
   const argv = Array.isArray(args) ? args : [];
   if (!sub || hasHelp([sub, ...argv])) {
@@ -318,6 +416,10 @@ export async function run(sub, args) {
       await del(argv);
       break;
     }
+    case "name": {
+      await name(argv);
+      break;
+    }
     default:
       failUnknownSubcommand("repos", sub, {
         hint: "Run `run402 repos --help` for usage.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {

package/sdk/dist/index.d.ts

@@ -363,6 +363,6 @@ export type * from "./namespaces/wallets.js";
 export * from "./namespaces/gitvault.crypto.js";
 export type * from "./namespaces/gitvault.crypto.js";
 export type * from "./namespaces/gitvault.types.js";
-export { Gitvault, gitvaultRemoteUrl, parseGitvaultRemoteUrl, GITVAULT_LOSS_WARNING_THRESHOLDS, gitvaultLossWarningTrip, gitvaultLossWarningTripped, gitvaultLossWarningMessage, } from "./namespaces/gitvault.js";
+export { Gitvault, gitvaultRemoteUrl, gitvaultRemoteUrlForRepo, parseGitvaultRemoteUrl, gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, GITVAULT_LOSS_WARNING_THRESHOLDS, gitvaultLossWarningTrip, gitvaultLossWarningTripped, gitvaultLossWarningMessage, } from "./namespaces/gitvault.js";
 export type * from "./namespaces/gitvault.js";
 //# sourceMappingURL=index.d.ts.map