run402 4.86.1 → 4.88.0

package/README.md

@@ -249,7 +249,7 @@ import { db, adminDb, auth, email, ai } from "@run402/functions";
 
 ### Same-origin web routes
 
-`run402 deploy apply` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Recipe — static home page + SPA shell: a root alias `{ "pattern": "/", "target": { "type": "static", "file": "home.html" } }` (with `home.html` at the site root) serves real static bytes at `GET /` (`route_static_alias`) while unmatched app routes keep the `index.html` shell (`spa_fallback`); expect non-blocking `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn) / `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info) plan lints and verify with `run402 deploy resolve --url https://<your-site>/ --method GET`. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
+`run402 deploy apply` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `site.embedding.frame_ancestors` (catalog keys, e.g. `["localhost"]`, never raw origins) lets the named embedders put the site in an iframe: the gateway sends `Content-Security-Policy: frame-ancestors http://localhost:* http://127.0.0.1:*` and drops `X-Frame-Options` on every response of the host; omitted on a later apply carries the previous declaration forward, `null` returns to deny, unknown keys fail `INVALID_SPEC` naming the valid ones, and `/_run402/config.json` discloses the effective policy cross-origin so an embedder can check before framing. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Recipe — static home page + SPA shell: a root alias `{ "pattern": "/", "target": { "type": "static", "file": "home.html" } }` (with `home.html` at the site root) serves real static bytes at `GET /` (`route_static_alias`) while unmatched app routes keep the `index.html` shell (`spa_fallback`); expect non-blocking `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn) / `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info) plan lints and verify with `run402 deploy resolve --url https://<your-site>/ --method GET`. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
 
 ### Secrets
 

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.86.1",
+  "surface_version": "4.88.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/deploy-v2.mjs

@@ -40,7 +40,7 @@ import {
 } from "#sdk/node";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId, isCoreApiTarget } from "./config.mjs";
+import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId, isCoreApiTarget, updateProject } from "./config.mjs";
 import { delegateTokenFromEnv } from "#sdk/node";
 import { flagValue, normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
@@ -1050,6 +1050,16 @@ export function collectManifestSourceFiles(spec, baseDir) {
   return [...out];
 }
 
+/**
+ * Persist an activated release's `deployment_id` into the local keystore.
+ * `run402 subdomains claim` reads it as an optimization only — the gateway
+ * binds the live release without it — so this must never throw.
+ */
+export function rememberLastDeployment(projectId, deploymentId) {
+  if (!projectId || typeof deploymentId !== "string" || !deploymentId) return;
+  try { updateProject(projectId, { last_deployment_id: deploymentId }); } catch { /* best-effort cache */ }
+}
+
 async function applyCmd(args) {
   const opts = parseApplyArgs(args);
   const { source, error: sourceError } = resolveApplySource(opts, hasStdinSource());
@@ -1296,6 +1306,10 @@ async function applyCmd(args) {
         onCommitLine: (line) => { if (!opts.quiet) process.stderr.write(`${line}\n`); },
       }),
     );
+    // Cache the activated deployment id so `run402 subdomains claim` can
+    // pass it as an optimization (the gateway defaults to the live release
+    // without it). Best-effort: a keystore hiccup never fails the deploy.
+    rememberLastDeployment(releaseSpec.project, outcome.deploy?.urls?.deployment_id);
     if (!outcome.gitvault) {
       console.log(JSON.stringify({ ...outcome.deploy, stats: sdkStats(sdk) }, null, 2));
       printVerboseStats(opts.verbose, sdk);

package/lib/image.mjs

@@ -2,6 +2,8 @@ import { writeFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
+import { resolveOrg } from "./org-context.mjs";
+import { nextAction } from "./next-actions.mjs";
 
 const HELP = `run402 image — Generate AI images via x402 micropayments
 
@@ -13,7 +15,9 @@ Options:
   --output <file>     Save image to file (e.g. output.png)
                       If omitted, returns base64 JSON to stdout
   --org <org_id>      The paying organization when the wallet belongs to more
-                      than one (Lightning rail); x402 ignores it
+                      than one (Lightning rail); x402 ignores it. Omitted, it
+                      is the current org (RUN402_ORG, the .run402.json binding,
+                      run402 org use, or the active project's owning org)
   --help, -h          Show this help message
 
 Examples:
@@ -47,7 +51,9 @@ Options:
   --output <file>     Save image to file (e.g. output.png). If omitted,
                       returns base64 JSON to stdout.
   --org <org_id>      The paying organization when the wallet belongs to more
-                      than one (Lightning rail); x402 ignores it
+                      than one (Lightning rail); x402 ignores it. Omitted, it
+                      is the current org (RUN402_ORG, the .run402.json binding,
+                      run402 org use, or the active project's owning org)
 
 Notes:
   - Requires a funded allowance (run402 allowance create && run402 allowance fund)
@@ -104,8 +110,17 @@ export async function run(sub, args) {
   }
   assertAllowedValue(opts.aspect, ["square", "landscape", "portrait"], "--aspect");
 
+  // The paying organization rides the ONE shared org chain (--org, then
+  // RUN402_ORG / RUN402_ROOM / RUN402_PROJECT_ID, then the .run402.json
+  // binding, then `org use` / the active project's owning org). Only the
+  // Lightning rail reads it — a multi-org principal is refused
+  // ORGANIZATION_SELECTION_REQUIRED without one — and x402 ignores it, so
+  // resolving it is never a reason to refuse an x402 purchase: `optional`
+  // answers null rather than ORG_REQUIRED when the chain is empty.
+  const org = await resolveOrg({ org: opts.org }, { cmd: "image", optional: true });
+
   try {
-    const data = await getSdk().ai.generateImage({ prompt: opts.prompt, aspect: opts.aspect, ...(opts.org ? { orgId: opts.org } : {}) });
+    const data = await getSdk().ai.generateImage({ prompt: opts.prompt, aspect: opts.aspect, ...(org ? { orgId: org.orgId } : {}) });
     if (opts.output) {
       const buf = Buffer.from(data.image, "base64");
       writeFileSync(opts.output, buf);
@@ -114,6 +129,45 @@ export async function run(sub, args) {
       console.log(JSON.stringify({ aspect: data.aspect, content_type: data.content_type, image: data.image }));
     }
   } catch (err) {
+    reportOrgSelectionError(err, org);
     reportSdkError(err);
   }
 }
+
+/**
+ * The Lightning rail's two org refusals, explained in the CLI's own words:
+ * `ORGANIZATION_SELECTION_REQUIRED` (no org named, and the SDK found no
+ * single local match among the gateway's candidates) and the 403 the
+ * gateway answers when the resolved org is one the principal cannot bill.
+ * Both name where the org came from and how to name another one.
+ */
+function reportOrgSelectionError(err, org) {
+  const code = err?.code;
+  const details = err?.details && typeof err.details === "object" ? err.details : {};
+  if (code === "ORGANIZATION_SELECTION_REQUIRED") {
+    const ids = Array.isArray(details.organization_ids) ? details.organization_ids : [];
+    fail({
+      code,
+      message: err.message,
+      hint:
+        `Pass --org <org_id> (one of: ${ids.join(", ") || "run402 org list"}) or select a current organization with ` +
+        "run402 org use <org_id>. Only the Lightning rail needs it; x402 ignores it.",
+      details: { ...details, organization_ids: ids, org_source: org?.source ?? null, org_source_detail: org?.sourceDetail ?? null },
+      next_actions: err.nextActions ?? [
+        nextAction("edit_request", { command: 'run402 image generate "<prompt>" --org <org_id>', why: "Name the paying organization on this call." }),
+        nextAction("edit_request", { command: "run402 org use <org_id>", why: "Select a current organization for this profile." }),
+      ],
+    });
+  }
+  if (err?.status === 403 && org && details.org_id === org.orgId && org.source !== "flag") {
+    fail({
+      code: code ?? "FORBIDDEN",
+      message: err.message,
+      hint:
+        `The paying organization ${org.orgId} came from ${org.sourceDetail} (${org.source}) and this principal holds no billing role there. ` +
+        "Pass --org <org_id> for an organization you can bill, or run: run402 org use <org_id>",
+      details: { ...details, org_source: org.source, org_source_detail: org.sourceDetail },
+      next_actions: err.nextActions,
+    });
+  }
+}

package/lib/init.mjs

@@ -1,7 +1,7 @@
 import { readAllowance, saveAllowance, loadKeyStore, configDir, configureApiBase, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
-import { setTierAction, deployAction } from "./next-actions.mjs";
+import { upDeployAction, deployAction } from "./next-actions.mjs";
 import { resolveOwningOrgId } from "./org-context.mjs";
 import { getActiveProfile } from "../core-dist/config.js";
 import { readMeta } from "../core-dist/profiles.js";
@@ -77,7 +77,8 @@ Steps (idempotent when re-run with the same rail; pass --switch-rail to change r
   3. Checks on-chain balance; requests faucet if zero
   4. Shows current tier subscription status
   5. Lists local project count
-  6. Suggests next step (tier set or deploy)
+  6. Suggests next step (run402 up -y when no tier is held yet — it subscribes
+     the prototype tier as part of the first deploy — or deploy apply)
 
 Run this once to get started, or again to check your setup.
 `;
@@ -730,10 +731,15 @@ export async function run(args = []) {
   // string mirror of the first action's command (one spelling, surface-wide).
   write("");
   const tierMissing = !tierInfo || !tierInfo.tier || !tierInfo.active;
-  summary.next_actions = [tierMissing ? setTierAction("prototype") : deployAction()];
+  summary.next_actions = [tierMissing ? upDeployAction() : deployAction()];
   summary.next_step = summary.next_actions[0].command;
   if (tierMissing) {
-    write("  Next: run402 tier set prototype");
+    // `up -y` subscribes the prototype tier itself as part of the first
+    // deploy; `init` never buys the tier, so the one command that finishes
+    // the cold start is `up`, with `tier set` named as the standalone option.
+    write("  Next: run402 up -y");
+    write("        Deploy with run402 up -y — it subscribes the prototype tier (free on testnet) as part of the first deploy.");
+    write("        Or subscribe separately: run402 tier set prototype.");
   } else {
     write("  Ready to deploy. Run: run402 deploy apply --manifest app.json");
   }

package/lib/next-actions.mjs

@@ -67,6 +67,19 @@ export function deployAction() {
   });
 }
 
+/**
+ * The cold-start deploy when the account holds no tier yet: `run402 up -y`
+ * subscribes the prototype tier itself as part of the first deploy, so `init`
+ * hands the agent ONE command instead of `tier set` + a separate deploy.
+ * `tier set prototype` stays named as the standalone alternative.
+ */
+export function upDeployAction() {
+  return nextAction("deploy", {
+    command: "run402 up -y",
+    why: "Deploy with run402 up -y — it subscribes the prototype tier (free on testnet) as part of the first deploy. Or subscribe separately: run402 tier set prototype.",
+  });
+}
+
 /**
  * `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

package/lib/status.mjs

@@ -7,6 +7,7 @@ import {
   apiTargetKind,
 } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
+import { fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
 import { getActiveProfile } from "../core-dist/config.js";
 import { readMeta } from "../core-dist/profiles.js";
@@ -14,7 +15,7 @@ import { readMeta } from "../core-dist/profiles.js";
 const HELP = `run402 status — Show full organization state in one shot
 
 Usage:
-  run402 status [--json]
+  run402 status [--json|--human]
 
 Displays:
   - Wallet identity (local_label, server_label, address)
@@ -26,6 +27,9 @@ Displays:
   - Active API target
 
 Output is JSON by default. --json is accepted as a compatibility no-op.
+--human renders a compact human summary instead (wallet, API target, tier,
+active project, balance, and the next action); it cannot be combined with
+--json.
 Run402 Cloud status requires an allowance; Core target status can still report
 local project state without one.
 `;
@@ -90,7 +94,16 @@ function normalizeProject(raw) {
 export async function run(args = []) {
   args = normalizeArgv(args);
   if (hasHelp(args)) { console.log(HELP); process.exit(0); }
-  assertKnownFlags(args, ["--help", "-h", "--json"]);
+  assertKnownFlags(args, ["--help", "-h", "--json", "--human"]);
+  const human = args.includes("--human");
+  if (human && args.includes("--json")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--human cannot be combined with --json.",
+      details: { flags: args.filter((arg) => arg === "--human" || arg === "--json") },
+      hint: "JSON is the default; drop --json to keep it, or keep --human alone for the rendered view.",
+    });
+  }
   const allowance = readAllowance();
   const target = {
     api_base: apiBase(),
@@ -99,13 +112,18 @@ export async function run(args = []) {
   };
   if (!allowance) {
     const store = loadKeyStore();
-    console.log(JSON.stringify({
+    const bare = {
       wallet: null,
       target,
       projects: Object.keys(store.projects).map(id => ({ project_id: id })),
       active_project: getActiveProjectId() || null,
       hint: target.kind === "core" ? "Run: run402 projects provision --name my-app" : "Run: run402 init",
-    }));
+    };
+    if (human) {
+      console.log(formatStatusHuman(bare));
+      return;
+    }
+    console.log(JSON.stringify(bare));
     return;
   }
 
@@ -170,5 +188,80 @@ export async function run(args = []) {
     target,
   };
 
+  if (human) {
+    console.log(formatStatusHuman(result));
+    return;
+  }
   console.log(JSON.stringify(result, null, 2));
 }
+
+function usdFromMicros(micros) {
+  if (typeof micros !== "number" || !Number.isFinite(micros)) return null;
+  return `$${(micros / 1_000_000).toFixed(2)}`;
+}
+
+/**
+ * The one next action for the human view, derived from the same state the
+ * JSON carries. Mirrors `init`: `run402 up -y` subscribes the prototype tier
+ * itself as part of the first deploy, so a tier-less account gets ONE command.
+ */
+function statusNextAction(result) {
+  if (!result.wallet) {
+    return result.hint?.replace(/^Run:\s*/, "") ?? "run402 init";
+  }
+  if (!result.tier) {
+    return "run402 up -y  (subscribes the prototype tier, free on testnet, as part of the first deploy; or: run402 tier set prototype)";
+  }
+  if (!result.active_project) {
+    return "run402 up --name <name> -y  (or select an existing project: run402 projects use <project_id>)";
+  }
+  return "run402 up -y  (redeploys the active project from run402.json)";
+}
+
+/**
+ * Compact human rendering of the status payload — the same style as
+ * `run402 up --human`: one fact per line, the next action last. The JSON
+ * shape is untouched; this only formats it.
+ */
+export function formatStatusHuman(result) {
+  const lines = [];
+  if (!result.wallet) {
+    lines.push("Wallet:   none (no allowance on this machine)");
+  } else {
+    const label = result.wallet.server_label
+      ? `${result.wallet.local_label} (${result.wallet.server_label})`
+      : result.wallet.local_label;
+    lines.push(`Wallet:   ${label} ${result.wallet.address}`);
+    if (result.rail) lines.push(`Rail:     ${result.rail}`);
+  }
+  lines.push(`API:      ${result.target.api_base} (${result.target.kind}, ${result.target.api_base_source})`);
+  if (result.wallet) {
+    if (result.tier) {
+      const lifecycle = result.organization_lifecycle_state ? `, org ${result.organization_lifecycle_state}` : "";
+      const expiry = result.lease_perpetual === true
+        ? ", perpetual"
+        : (result.tier.expires ? `, expires ${result.tier.expires}` : "");
+      lines.push(`Tier:     ${result.tier.name} (${result.tier.status}${lifecycle}${expiry})`);
+    } else {
+      lines.push("Tier:     none");
+    }
+  }
+  const projects = Array.isArray(result.projects) ? result.projects : [];
+  if (result.active_project) {
+    const active = projects.find((p) => p?.project_id === result.active_project);
+    const site = active?.site_url ? ` ${active.site_url}` : "";
+    lines.push(`Project:  ${result.active_project}${site}`);
+  } else {
+    lines.push(`Project:  none active${projects.length ? ` (${projects.length} known)` : ""}`);
+  }
+  if (result.balances) {
+    const parts = [];
+    const onChain = usdFromMicros(result.balances.on_chain_usd_micros);
+    if (onChain) parts.push(`${onChain} ${result.balances.on_chain_token} on-chain`);
+    const credit = usdFromMicros(result.balances.prepaid_credit_usd_micros);
+    if (credit) parts.push(`${credit} prepaid credit`);
+    if (parts.length) lines.push(`Balance:  ${parts.join(", ")}`);
+  }
+  lines.push(`Next:     ${statusNextAction(result)}`);
+  return lines.join("\n");
+}

package/lib/subdomains.mjs

@@ -2,7 +2,6 @@ import { resolveProject, resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
-import { cliCommandAction } from "./next-actions.mjs";
 
 const HELP = `run402 subdomains — Manage custom subdomains
 
@@ -10,28 +9,30 @@ Usage:
   run402 subdomains <subcommand> [args...]
 
 Subcommands:
-  claim  <name> [--project <id>] [--deployment <id>]   Claim a subdomain
-  delete <name> --confirm [--project <id>]              Release a subdomain. Requires --confirm.
-  list   [--project <id>]                               List subdomains for a project
+  claim  <name> [--project <id>] [--release <id> | --deployment <id>]   Claim a subdomain
+  delete <name> --confirm [--project <id>]                              Release a subdomain. Requires --confirm.
+  list   [--project <id>]                                               List subdomains for a project
 
-Options default to the active project and its last deployment when omitted.
+Options default to the active project. With neither --release nor
+--deployment, claim binds the project's live release.
 
 Examples:
   run402 subdomains claim myapp
-  run402 subdomains claim myapp --deployment dpl_abc123 --project prj_abc123
+  run402 subdomains claim myapp --release rel_abc123 --project prj_abc123
   run402 subdomains delete myapp --confirm
   run402 subdomains list
 
 Notes:
   - Subdomain names: 3-63 chars, lowercase alphanumeric + hyphens
-  - Creates <name>.run402.com pointing to the deployment
+  - Creates <name>.run402.com pointing to the bound release
+  - Or declare it in the deploy manifest: "subdomains": { "set": ["myapp"] }
 `;
 
 const SUB_HELP = {
-  claim: `run402 subdomains claim — Claim a custom subdomain for a deployment
+  claim: `run402 subdomains claim — Claim a custom subdomain for a release
 
 Usage:
-  run402 subdomains claim <name> [--project <id>] [--deployment <id>]
+  run402 subdomains claim <name> [--project <id>] [--release <id> | --deployment <id>]
 
 Arguments:
   <name>              Subdomain name (3-63 chars, lowercase alphanumeric +
@@ -39,15 +40,19 @@ Arguments:
 
 Options:
   --project <id>      Project ID (defaults to the active project)
-  --deployment <id>   Deployment ID to point at (defaults to the project's
-                      last deployment)
+  --release <id>      Release ID (rel_...) to point at. With neither flag,
+                      the project's live release is bound.
+  --deployment <id>   Legacy deployment ID (dpl_...); rel_.../op_... ids are
+                      accepted too.
 
 Notes:
-  - Deploy a site first (or pass --deployment) so there is a target to claim
+  - With no flag the gateway binds the project's live (active) release; a
+    project with no live site answers 404.
+  - A deploy manifest can declare the same thing: "subdomains": { "set": ["<name>"] }
 
 Examples:
   run402 subdomains claim myapp
-  run402 subdomains claim myapp --deployment dpl_abc123 --project prj_abc123
+  run402 subdomains claim myapp --release rel_abc123 --project prj_abc123
 `,
   list: `run402 subdomains list — List subdomains claimed by a project
 
@@ -82,19 +87,20 @@ Examples:
 
 async function claim(args) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--project", "--deployment"];
+  const valueFlags = ["--project", "--deployment", "--release"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
   const opts = {
     project: flagValue(parsedArgs, "--project"),
     deployment: flagValue(parsedArgs, "--deployment"),
+    release: flagValue(parsedArgs, "--release"),
   };
-  let name, deploymentId;
+  let name;
   const positionals = positionalArgs(parsedArgs, valueFlags);
   if (positionals.length > 1) {
     fail({
       code: "BAD_USAGE",
       message: `Unexpected argument for subdomains claim: ${positionals[1]}`,
-      hint: "Use `run402 subdomains claim <name> --deployment <deployment_id>`.",
+      hint: "Use `run402 subdomains claim <name> [--release <rel_id>]`.",
     });
   }
   if (positionals.length === 1) {
@@ -104,23 +110,26 @@ async function claim(args) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <name>.",
-      hint: "run402 subdomains claim <name> [--project <id>] [--deployment <id>]",
+      hint: "run402 subdomains claim <name> [--project <id>] [--release <id> | --deployment <id>]",
     });
   }
-  const projectId = resolveProjectId(opts.project);
-  const p = resolveProject(opts.project);
-  deploymentId = opts.deployment || deploymentId || p.last_deployment_id;
-  if (!deploymentId) {
+  if (opts.deployment && opts.release) {
     fail({
-      code: "NO_DEPLOYMENT",
-      message: "no deployment_id specified and no recent deployment found.",
-      hint: "Deploy a site first or pass --deployment <id>.",
-      details: { project_id: projectId },
-      next_actions: [cliCommandAction("deploy", "run402 deploy apply", "Deploy a site first, then retry claiming the subdomain.")],
+      code: "BAD_USAGE",
+      message: "Pass either --release or --deployment, not both.",
+      hint: "run402 subdomains claim <name> [--release <id> | --deployment <id>]",
     });
   }
+  const projectId = resolveProjectId(opts.project);
+  const p = resolveProject(opts.project);
+  // With neither flag, the keystore's cached `last_deployment_id` is only an
+  // optimization; absent one, the gateway resolves the project's live
+  // release itself. Never fail client-side here — a unified-apply deploy
+  // may never have written the cache.
+  const deploymentId = opts.deployment || (opts.release ? undefined : p.last_deployment_id) || undefined;
+  const releaseId = opts.release || undefined;
   try {
-    const data = await getSdk().subdomains.claim({ name, deploymentId, projectId });
+    const data = await getSdk().subdomains.claim({ name, deploymentId, releaseId, projectId });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);

package/lib/up.mjs

@@ -6,7 +6,7 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
 import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
-import { allowanceAuthHeaders, isCoreApiTarget } from "./config.mjs";
+import { allowanceAuthHeaders, isCoreApiTarget, updateProject } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 
 const HELP = `run402 up — Provision/link/deploy the current app
@@ -372,6 +372,16 @@ export async function run(args = []) {
                 console.error(JSON.stringify(event));
               },
       });
+      // Cache the activated deployment id so `run402 subdomains claim` can
+      // pass it as an optimization (the gateway binds the live release
+      // without it). Best-effort: a keystore hiccup never fails `up`.
+      {
+        const deployedProject = result?.result?.project_id ?? result?.result?.deploy?.project_id ?? null;
+        const deploymentId = result?.result?.deploy?.urls?.deployment_id;
+        if (deployedProject && typeof deploymentId === "string" && deploymentId) {
+          try { updateProject(deployedProject, { last_deployment_id: deploymentId }); } catch { /* best-effort cache */ }
+        }
+      }
       // The remote scaffold + first push are best-effort ADDITIONS to an
       // already-successful deploy: a git hiccup here must never flip an
       // otherwise-successful `up` into a failure (the same non-fatal
@@ -384,7 +394,7 @@ export async function run(args = []) {
             createdRepository = await gitInitIfNeeded(workDir);
             result.result.repo = await composeRepoPushStep({ sdk, workDir, projectId, createdRepository, nested });
           } catch (err) {
-            result.result.repo = { status: "failed", first_push: null, first_push_error: { code: err?.code ?? "GITVAULT_SETUP_FAILED", message: err?.message ?? String(err) } };
+            result.result.repo = { status: "failed", first_push: null, first_push_error: { code: err?.code ?? "GITVAULT_SETUP_FAILED", message: err?.message ?? String(err) }, ...repoNextActionsOf(err) };
           }
         }
       }
@@ -405,9 +415,9 @@ export async function run(args = []) {
     } else if (mode === "printSpec") {
       console.log(JSON.stringify(result.result?.spec ?? null, null, 2));
     } else if (human && result?.result?.app_result) {
-      console.log([formatAppUpHuman(result.result.app_result), formatRepoSkipLine(result)].filter(Boolean).join("\n"));
+      console.log([formatAppUpHuman(result.result.app_result), formatRepoSkipLine(result), formatRepoFirstPushErrorLine(result)].filter(Boolean).join("\n"));
     } else if (human && shouldRenderHumanSuccess(result)) {
-      console.log([formatLegacyUpSuccess(result), formatRepoSkipLine(result)].filter(Boolean).join("\n"));
+      console.log([formatLegacyUpSuccess(result), formatRepoSkipLine(result), formatRepoFirstPushErrorLine(result)].filter(Boolean).join("\n"));
     } else {
       console.log(JSON.stringify(result, null, 2));
     }
@@ -688,9 +698,6 @@ async function composeRepoPushStep({ sdk, workDir, projectId, createdRepository,
   // `run402 up --nested` (the caller's own spelling of the way out).
   const scaffold = await scaffoldGitvaultRemote({ repoDir: workDir, projectId, orgId: orgId ?? undefined, createRepoIfMissing: false, nested, nestedCommand: "run402 up --nested" });
   if (createdRepository && scaffold.gitvault) scaffold.gitvault.created_repository = true;
-  // A nested repository the scaffold itself just created is as fresh as one
-  // `up`'s own git init made: nothing committed, every file untracked.
-  const freshRepository = createdRepository || scaffold.gitvault?.created_repository === true;
   const out = { ...scaffold, first_push: null, first_push_error: null };
   if (scaffold.status !== "scaffolded") {
     // Nothing was scaffolded (the app root is inside another repository, or
@@ -702,14 +709,22 @@ async function composeRepoPushStep({ sdk, workDir, projectId, createdRepository,
     out.first_push_error = { code: "GITVAULT_ORG_UNRESOLVED", message: `could not resolve the owning org for ${projectId} — the first push was skipped` };
     return out;
   }
+  // Read BEFORE the push decision: an unborn HEAD is what decides the lane.
+  out.local_git = await readLocalGitState(workDir);
+  // A nested repository the scaffold itself just created is as fresh as one
+  // `up`'s own git init made: nothing committed, every file untracked. So is
+  // a repository the agent `git init`ed itself and never committed to (an
+  // UNBORN HEAD): there is no clean tree to keep, only untracked files, and
+  // the strict lane would refuse SNAPSHOT_DIRTY_TREE on every first push.
+  const freshRepository = createdRepository || scaffold.gitvault?.created_repository === true || out.local_git.unborn === true;
   try {
     let vaultCreated = null;
-    // A repository `up` itself just created has, by definition, nothing
-    // committed yet — every file is untracked, so a clean-tree capture would
-    // refuse SNAPSHOT_DIRTY_TREE on every fresh directory. Capture it as the
-    // synthetic first commit the dirty-tree lane produces (disclosed under
-    // first_push.snapshot); an EXISTING repository keeps the clean-tree rule
-    // and its refusal is reported, never overridden.
+    // A fresh repository has, by definition, nothing committed yet — every
+    // file is untracked, so a clean-tree capture would refuse
+    // SNAPSHOT_DIRTY_TREE on every first push. Capture it as the synthetic
+    // first commit the dirty-tree lane produces (disclosed under
+    // first_push.snapshot); a repository WITH commits keeps the clean-tree
+    // rule and its refusal is reported, never overridden.
     const pushed = await sdk.gitvault.push({
       project_id: projectId,
       org_id: orgId,
@@ -728,15 +743,26 @@ async function composeRepoPushStep({ sdk, workDir, projectId, createdRepository,
     };
   } catch (err) {
     out.first_push_error = { code: err?.body?.code ?? err?.code ?? "GITVAULT_PUSH_FAILED", message: err?.message ?? String(err) };
+    Object.assign(out, repoNextActionsOf(err));
   }
+  return out;
+}
+
+/** `{ next_actions }` derived from a thrown SDK error's own advice, or nothing. */
+function repoNextActionsOf(err) {
+  const actions = Array.isArray(err?.nextActions) ? err.nextActions : Array.isArray(err?.next_actions) ? err.next_actions : [];
+  return actions.length > 0 ? { next_actions: actions.map((a) => ({ type: a?.type, ...(a?.command ? { command: a.command } : {}), ...(a?.why ? { why: a.why } : {}) })) } : {};
+}
+
+/** Branch / HEAD / unborn / dirty of `workDir`, or `{ state: "unavailable" }`. Never throws. */
+async function readLocalGitState(workDir) {
   try {
     const { hardenedGit } = await import("#sdk/node");
     const read = async (args) => { try { return (await hardenedGit(workDir, args)).text().trim(); } catch { return null; } };
     const head = await read(["rev-parse", "--verify", "HEAD"]);
     const status = await read(["status", "--porcelain"]);
-    out.local_git = { branch: await read(["symbolic-ref", "--short", "HEAD"]), head, unborn: head === null, dirty: status === null ? null : status.length > 0 };
-  } catch { out.local_git = { state: "unavailable" }; }
-  return out;
+    return { branch: await read(["symbolic-ref", "--short", "HEAD"]), head, unborn: head === null, dirty: status === null ? null : status.length > 0 };
+  } catch { return { state: "unavailable" }; }
 }
 
 /**
@@ -833,6 +859,20 @@ function formatRepoSkipLine(result) {
   return `Encrypted remote skipped: ${repo.reason ?? "skipped"}${where}.${remedy}`;
 }
 
+/**
+ * One line for the human summary when the first push into the encrypted
+ * remote failed: the error code and the first next action's command (or its
+ * advice) — the deploy itself succeeded, so this is a footnote, never an exit.
+ */
+function formatRepoFirstPushErrorLine(result) {
+  const repo = result?.result?.repo;
+  const error = repo?.first_push_error;
+  if (!error?.code) return null;
+  const first = (Array.isArray(repo.next_actions) ? repo.next_actions : []).find((action) => action?.command || action?.why);
+  const remedy = first?.command ? ` Next: ${first.command}` : first?.why ? ` ${first.why}` : "";
+  return `Encrypted remote first push failed: ${error.code}.${remedy}`;
+}
+
 function formatLegacyUpSuccess(result) {
   const urls = result?.result?.deploy?.urls ?? {};
   const origin = urls.site ?? urls.subdomain ?? urls.deployment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.86.1",
+  "version": "4.88.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": {