run402 3.5.2 → 3.5.4

package/lib/deploy-v2.mjs

@@ -36,6 +36,7 @@ import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId } from
 import { normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./operator.mjs";
+import { editRequestAction, nextAction, retryAction } from "./next-actions.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -939,66 +940,66 @@ const CI_DEPLOY_ERROR_GUIDANCE = {
   invalid_token: {
     hint: "Ensure the workflow has permissions: id-token: write and is running in the repository/branch linked with run402 ci link github.",
     next_actions: [
-      "Check the workflow permissions block includes id-token: write.",
-      "Re-run run402 ci link github if the repository, branch, or environment changed.",
+      nextAction("edit_request", { why: "Check the workflow permissions block includes id-token: write." }),
+      editRequestAction("run402 ci link github", "Re-link if the repository, branch, or environment changed."),
     ],
   },
   access_denied: {
     hint: "The OIDC token was valid, but no active Run402 CI binding allowed this workflow.",
     next_actions: [
-      "Run run402 ci list --project <prj_...> locally to inspect bindings.",
-      "Run run402 ci link github again for this repository/branch/environment.",
+      editRequestAction("run402 ci list --project <prj_...>", "Inspect active CI bindings for this project."),
+      editRequestAction("run402 ci link github", "Link this repository, branch, and environment to Run402."),
     ],
   },
   binding_revoked: {
     hint: "A matching CI binding existed but was revoked — most often because the project was transferred or handed to a new owner, which suspends the prior org's CI bindings.",
     next_actions: [
-      "Run run402 ci link github again from this repository to re-create the binding.",
-      "Do not run run402 ci set-asset-scopes — it returns 409 on a revoked binding.",
-      "Run run402 ci list --project <prj_...> locally to confirm the binding state.",
+      editRequestAction("run402 ci link github", "Re-create the CI binding from this repository."),
+      nextAction("edit_request", { why: "Do not run run402 ci set-asset-scopes; it returns 409 on a revoked binding." }),
+      editRequestAction("run402 ci list --project <prj_...>", "Confirm the binding state locally."),
     ],
   },
   event_not_allowed: {
     hint: "This binding only allows push and workflow_dispatch events in v1.",
     next_actions: [
-      "Trigger the workflow with push or workflow_dispatch.",
-      "Create a separate follow-up design before enabling PR deploy events.",
+      nextAction("retry", { why: "Trigger the workflow with push or workflow_dispatch." }),
+      nextAction("edit_request", { why: "Create a separate follow-up design before enabling PR deploy events." }),
     ],
   },
   repository_id_mismatch: {
     hint: "The GitHub repository id in the OIDC token does not match the linked binding.",
     next_actions: [
-      "Run run402 ci link github again from the current repository.",
-      "If automatic lookup fails, pass --repository-id with the numeric GitHub repository id.",
+      editRequestAction("run402 ci link github", "Re-link from the current repository."),
+      editRequestAction("run402 ci link github --repository-id <id>", "Pass the numeric GitHub repository id if automatic lookup fails."),
     ],
   },
   forbidden_spec_field: {
     hint: "CI deploys can deploy site/functions/database content and route declarations only when the binding includes covering route scopes.",
     next_actions: [
-      "Remove forbidden fields such as secrets, subdomains, or checks from the CI manifest.",
-      "Keep the normalized manifest small enough to avoid manifest_ref.",
+      nextAction("edit_request", { why: "Remove forbidden fields such as secrets, subdomains, or checks from the CI manifest." }),
+      nextAction("edit_request", { why: "Keep the normalized manifest small enough to avoid manifest_ref." }),
     ],
   },
   CI_ROUTE_SCOPE_DENIED: {
     hint: "This CI binding does not cover one or more route declarations in the deploy manifest.",
     next_actions: [
-      "Re-run run402 ci link github with --route-scope for every exact or prefix path the workflow may deploy.",
-      "Use exact scopes such as --route-scope /admin or prefix scopes such as --route-scope /api/*.",
-      "Run the deploy locally with run402 deploy apply for route changes outside the CI delegation.",
+      editRequestAction("run402 ci link github --route-scope <pattern>", "Add a CI route scope for every exact or prefix path the workflow may deploy."),
+      nextAction("edit_request", { why: "Use exact scopes such as --route-scope /admin or prefix scopes such as --route-scope /api/*." }),
+      editRequestAction("run402 deploy apply", "Run route changes locally when they are outside the CI delegation."),
     ],
   },
   forbidden_plan: {
     hint: "The gateway rejected this deploy plan for CI. Keep CI deploys to the allowed resources and re-link if policy changed.",
     next_actions: [
-      "Inspect the gateway error details for the rejected resource.",
-      "Run the deploy locally with run402 deploy apply for operations outside the CI allowlist.",
+      nextAction("edit_request", { why: "Inspect the gateway error details for the rejected resource." }),
+      editRequestAction("run402 deploy apply", "Run operations outside the CI allowlist locally."),
     ],
   },
   payment_required: {
     hint: "The project tier or payment state does not allow this CI deploy.",
     next_actions: [
-      "Run run402 tier status --project <prj_...> locally.",
-      "Renew or upgrade the project tier, then re-run the workflow.",
+      editRequestAction("run402 tier status --project <prj_...>", "Inspect project tier and payment state locally."),
+      editRequestAction("run402 tier set <tier>", "Renew or upgrade the project tier, then re-run the workflow."),
     ],
   },
 };
@@ -1032,18 +1033,22 @@ function enhanceDeployWarningError(err) {
       : code
         ? [code]
         : [];
-  const allowWarningAction = unacknowledgedCodes.length === 1
-    ? `Retry with \`--allow-warning ${unacknowledgedCodes[0]}\` only after reviewing that warning.`
-    : unacknowledgedCodes.length > 1
-      ? `Retry with one \`--allow-warning <code>\` per reviewed warning code: ${unacknowledgedCodes.join(", ")}.`
-      : "Retry with `--allow-warning <code>` only after reviewing the warning.";
+  const allowWarningCommand = unacknowledgedCodes.length > 0
+    ? `run402 deploy apply ${unacknowledgedCodes.map((warningCode) => `--allow-warning ${warningCode}`).join(" ")}`
+    : "run402 deploy apply --allow-warning <code>";
+  const allowWarningAction = editRequestAction(
+    allowWarningCommand,
+    unacknowledgedCodes.length > 0
+      ? `Retry only after reviewing warning code${unacknowledgedCodes.length === 1 ? "" : "s"}: ${unacknowledgedCodes.join(", ")}.`
+      : "Retry only after reviewing the warning code.",
+  );
   const defaultNextActions = [
     ...(affected.length > 0
-      ? [`Set or inspect affected secrets: ${Array.from(new Set(affected)).join(", ")}`]
+      ? [editRequestAction("run402 secrets set <project> <KEY> --stdin", `Set or inspect affected secrets: ${Array.from(new Set(affected)).join(", ")}`)]
       : []),
-    "Retry `run402 deploy apply` after resolving warnings.",
+    retryAction("run402 deploy apply", "Retry after resolving warnings."),
     allowWarningAction,
-    "Use `--allow-warnings` only when every warning was explicitly reviewed.",
+    editRequestAction("run402 deploy apply --allow-warnings", "Use only when every warning was explicitly reviewed."),
   ];
   enhanced.body = {
     ...existingBody,
@@ -1066,98 +1071,98 @@ const ROUTE_WARNING_GUIDANCE = {
   PUBLIC_ROUTED_FUNCTION: {
     hint: "A deploy route makes a function public same-origin browser ingress; direct /functions/v1/:name remains API-key protected.",
     next_actions: [
-      "Review application auth and authorization in the routed function.",
-      "Add CSRF protection for cookie-authenticated POST/PUT/PATCH/DELETE routes.",
-      "Implement CORS and OPTIONS explicitly when cross-origin callers are intended.",
-      "Retry with --allow-warnings only after the public ingress review is intentional.",
+      nextAction("edit_request", { why: "Review application auth and authorization in the routed function." }),
+      nextAction("edit_request", { why: "Add CSRF protection for cookie-authenticated POST/PUT/PATCH/DELETE routes." }),
+      nextAction("edit_request", { why: "Implement CORS and OPTIONS explicitly when cross-origin callers are intended." }),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only after the public ingress review is intentional."),
     ],
   },
   ROUTE_TARGET_CARRIED_FORWARD: {
     hint: "A carried-forward route still points at a base-release function target.",
     next_actions: [
-      "Inspect the active release with run402 deploy release active.",
-      "Deploy routes.replace if the target should change in this release.",
+      editRequestAction("run402 deploy release active", "Inspect the active release."),
+      editRequestAction("run402 deploy apply --manifest <path>", "Deploy routes.replace if the target should change in this release."),
     ],
   },
   ROUTE_SHADOWS_STATIC_PATH: {
     hint: "A dynamic route shadows a static site path.",
     next_actions: [
-      "Inspect the warning details for affected static paths.",
-      "Inspect live routes with run402 deploy release active.",
-      "Retry with --allow-warnings only when dynamic shadowing is intentional.",
+      nextAction("edit_request", { why: "Inspect the warning details for affected static paths." }),
+      editRequestAction("run402 deploy release active", "Inspect live routes."),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only when dynamic shadowing is intentional."),
     ],
   },
   WILDCARD_ROUTE_SHADOWS_STATIC_PATHS: {
     hint: "A prefix wildcard route shadows one or more static site paths.",
     next_actions: [
-      "Review affected route/static path details.",
-      "Split exact routes or move static paths if the shadowing is accidental.",
-      "Retry with --allow-warnings only when the wildcard shadowing is intentional.",
+      nextAction("edit_request", { why: "Review affected route/static path details." }),
+      nextAction("edit_request", { why: "Split exact routes or move static paths if the shadowing is accidental." }),
+      retryAction("run402 deploy apply --allow-warnings", "Retry only when the wildcard shadowing is intentional."),
     ],
   },
   METHOD_SPECIFIC_ROUTE_ALLOWS_GET_STATIC_FALLBACK: {
     hint: "A method-specific route allows static fallback for unmatched methods such as GET.",
     next_actions: [
-      "Confirm that static fallback for GET/HEAD is intended.",
-      "Add method coverage or static files deliberately.",
+      nextAction("edit_request", { why: "Confirm that static fallback for GET/HEAD is intended." }),
+      nextAction("edit_request", { why: "Add method coverage or static files deliberately." }),
     ],
   },
   WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS: {
     hint: "A wildcard function route only allows GET/HEAD, so POST/PUT/PATCH/DELETE paths under that prefix will be rejected before the function runs.",
     next_actions: [
-      "Add the mutation methods the routed function supports, such as POST.",
-      "Omit methods to allow every supported method when the route is an API surface.",
-      "Set acknowledge_readonly: true on an intentionally read-only GET/HEAD wildcard function route.",
-      "Use --allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS only as a reviewed CLI escape hatch.",
+      nextAction("edit_request", { why: "Add the mutation methods the routed function supports, such as POST." }),
+      nextAction("edit_request", { why: "Omit methods to allow every supported method when the route is an API surface." }),
+      nextAction("edit_request", { why: "Set acknowledge_readonly: true on an intentionally read-only GET/HEAD wildcard function route." }),
+      retryAction("run402 deploy apply --allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS", "Use only as a reviewed CLI escape hatch."),
     ],
   },
   ROUTE_TABLE_NEAR_LIMIT: {
     hint: "The route table is near the gateway/project limit.",
     next_actions: [
-      "Consolidate prefix routes where possible.",
-      "Remove stale route entries before adding more.",
+      nextAction("edit_request", { why: "Consolidate prefix routes where possible." }),
+      nextAction("edit_request", { why: "Remove stale route entries before adding more." }),
     ],
   },
   ROUTES_NOT_ENABLED: {
     hint: "Deploy-v2 web routes are not enabled for this project or environment; direct /functions/v1/:name remains protected and is not a browser-route substitute.",
     next_actions: [
-      "Deploy without the routes resource, or request route enablement for this project/environment.",
-      "Keep direct function invocation API-key protected; do not substitute it for same-origin browser routes.",
+      nextAction("edit_request", { why: "Deploy without the routes resource, or request route enablement for this project/environment." }),
+      nextAction("edit_request", { why: "Keep direct function invocation API-key protected; do not substitute it for same-origin browser routes." }),
     ],
   },
   STATIC_ALIAS_SHADOWS_STATIC_PATH: {
     hint: "A static route target shadows a direct static path at the same public URL.",
     next_actions: [
-      "Inspect the route pattern, target.file, and direct static path.",
-      "Confirm only when the static route target is intentional.",
+      nextAction("edit_request", { why: "Inspect the route pattern, target.file, and direct static path." }),
+      nextAction("edit_request", { why: "Confirm only when the static route target is intentional." }),
     ],
   },
   STATIC_ALIAS_RELATIVE_ASSET_RISK: {
     hint: "Relative asset URLs inside the target HTML may resolve differently at the static route target URL.",
     next_actions: [
-      "Inspect the target HTML for relative asset references.",
-      "Use absolute asset URLs or confirm only when the alternate URL is intentional.",
+      nextAction("edit_request", { why: "Inspect the target HTML for relative asset references." }),
+      nextAction("edit_request", { why: "Use absolute asset URLs or confirm only when the alternate URL is intentional." }),
     ],
   },
   STATIC_ALIAS_DUPLICATE_CANONICAL_URL: {
     hint: "Both the static route target URL and the target file URL may be publicly reachable.",
     next_actions: [
-      "Decide which URL should be canonical.",
-      "Update links/canonical tags or accept the duplicate public URL intentionally.",
+      nextAction("edit_request", { why: "Decide which URL should be canonical." }),
+      nextAction("edit_request", { why: "Update links/canonical tags or accept the duplicate public URL intentionally." }),
     ],
   },
   STATIC_ALIAS_EXTENSIONLESS_NON_HTML: {
     hint: "An extensionless static route target points at a non-HTML file.",
     next_actions: [
-      "Check that the extensionless route is meant to serve that content type.",
-      "Prefer extensionless static route targets for HTML pages.",
+      nextAction("edit_request", { why: "Check that the extensionless route is meant to serve that content type." }),
+      nextAction("edit_request", { why: "Prefer extensionless static route targets for HTML pages." }),
     ],
   },
   STATIC_ALIAS_TABLE_NEAR_LIMIT: {
     hint: "Static route targets count toward the route table limit.",
     next_actions: [
-      "Consolidate manual static route targets where possible.",
-      "Avoid one route entry per page for large sites until framework-scale Web Output support exists.",
+      nextAction("edit_request", { why: "Consolidate manual static route targets where possible." }),
+      nextAction("edit_request", { why: "Avoid one route entry per page for large sites until framework-scale Web Output support exists." }),
     ],
   },
 };

package/lib/doctor-source-scan.mjs

@@ -29,7 +29,7 @@
  * summary. Wired into `run402 deploy` pre-flight as a deploy-failing
  * gate for the error severities; non-blocking for warning severities.
  *
- * @see openspec/changes/auth-aware-ssr/specs/functions-sdk-auth-model
+ * @see the auth-aware-ssr OpenSpec change (functions-sdk-auth-model)
  */
 
 import { readdirSync, readFileSync, statSync } from "node:fs";

package/lib/functions.mjs

@@ -3,6 +3,7 @@ import { findProject, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, validateRegularFile } from "./argparse.mjs";
+import { cliCommandAction } from "./next-actions.mjs";
 
 const FUNCTION_LOG_REQUEST_ID_RE = /^req_[A-Za-z0-9_-]{4,128}$/;
 const ISO_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
@@ -541,7 +542,7 @@ async function rebuild(projectId, args = []) {
         code: "CANNOT_REBUILD_UNLOCKED_DEPS",
         message: err.body.error || err.body.message || "Function was deployed before dependency locking.",
         hint: UNLOCKED_DEPS_HINT,
-        next_actions: [`run402 functions deploy ${projectId} ${name} --file <file>`],
+        next_actions: [cliCommandAction("deploy", `run402 functions deploy ${projectId} ${name} --file <file>`, "Redeploy the function once so Run402 can lock dependencies for future rebuilds.")],
         retryable: false,
         safe_to_retry: false,
       });

package/lib/init.mjs

@@ -1,6 +1,7 @@
 import { readAllowance, saveAllowance, loadKeyStore, configDir } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { fail } from "./sdk-errors.mjs";
+import { setTierAction, deployAction } from "./next-actions.mjs";
 import { getActiveProfile } from "../core-dist/config.js";
 import { readMeta } from "../core-dist/profiles.js";
 import { mkdirSync } from "fs";
@@ -95,6 +96,7 @@ export async function run(args = []) {
     balances: null,
     tier: null,
     projects_saved: 0,
+    next_actions: [],
     next_step: null,
   };
 
@@ -268,18 +270,18 @@ export async function run(args = []) {
   summary.projects_saved = Object.keys(store.projects).length;
   line("Projects", `${summary.projects_saved} saved`);
 
-  // 6. Next step
+  // 6. Next step — canonical typed action(s); `next_step` is the back-compat
+  // string mirror of the first action's command (one spelling, surface-wide).
   write("");
-  const nextStep = (!tierInfo || !tierInfo.tier || !tierInfo.active)
-    ? "run402 tier set prototype"
-    : "run402 deploy apply --manifest app.json";
-  if (!tierInfo || !tierInfo.tier || !tierInfo.active) {
+  const tierMissing = !tierInfo || !tierInfo.tier || !tierInfo.active;
+  summary.next_actions = [tierMissing ? setTierAction("prototype") : deployAction()];
+  summary.next_step = summary.next_actions[0].command;
+  if (tierMissing) {
     write("  Next: run402 tier set prototype");
   } else {
     write("  Ready to deploy. Run: run402 deploy apply --manifest app.json");
   }
   write("");
-  summary.next_step = nextStep;
 
   console.log(JSON.stringify(summary, null, 2));
 }

package/lib/next-actions.mjs

@@ -0,0 +1,61 @@
+/**
+ * Canonical bootstrap `next_actions` entries
+ * (change: keep-agent-in-loop-on-cold-start).
+ *
+ * One spelling, surface-wide: each cold-start wall hands the agent a typed
+ * action whose `command` is the literal CLI invocation. The shape mirrors the
+ * gateway's `next_actions` (`{ type, why, ... }`) extended with `command` for
+ * CLI-resolvable, client-side actions — the same shape already used by
+ * `cli/lib/email.mjs`. The `type` values match the SDK `NextActionType` union.
+ *
+ * Use these helpers whenever the CLI itself authors next actions. Gateway/SDK
+ * `next_actions` remain the lower-layer source of truth and should pass through.
+ */
+
+export function nextAction(type, fields = {}) {
+  const action = { type };
+  for (const key of ["command", "method", "path", "auth", "why"]) {
+    if (fields[key] !== undefined) action[key] = fields[key];
+  }
+  return action;
+}
+
+export function cliCommandAction(type, command, why) {
+  return nextAction(type, { command, why });
+}
+
+export function editRequestAction(command, why) {
+  return cliCommandAction("edit_request", command, why);
+}
+
+export function retryAction(command, why) {
+  return cliCommandAction("retry", command, why);
+}
+
+export function initializeWalletAction() {
+  return nextAction("initialize_wallet", {
+    command: "run402 init",
+    why: "Create and fund an agent allowance, then retry.",
+  });
+}
+
+export function createProjectAction() {
+  return nextAction("create_project", {
+    command: "run402 projects provision",
+    why: "Provision a project to act on, then retry.",
+  });
+}
+
+export function setTierAction(tier = "prototype") {
+  return nextAction("renew_tier", {
+    command: `run402 tier set ${tier}`,
+    why: "Subscribe the account to a tier (free on testnet), then retry.",
+  });
+}
+
+export function deployAction() {
+  return nextAction("deploy", {
+    command: "run402 deploy apply --manifest app.json",
+    why: "Apply your release manifest to deploy.",
+  });
+}

package/lib/projects.mjs

@@ -149,13 +149,16 @@ Examples:
   provision: `run402 projects provision — Provision a new Postgres project
 
 Usage:
-  run402 projects provision [--tier <tier>] [--name <name>] [--org <id>]
+  run402 projects provision [--tier <tier>] [--name <name>] [--org <id>] [--idempotency-key <key>]
 
 Options:
   --tier <tier>       Tier for the new project (default: prototype)
   --name <name>       Human-readable name for the project
   --org <id>          Provision into an EXISTING org (needs developer+ on it).
                       Omit for the cold-start path. Tier is org-governed.
+  --idempotency-key <key>  Retry-safe key: re-running with the same key returns
+                      the existing project instead of duplicating it. Auto-derived
+                      from --name when omitted; an unnamed provision stays un-keyed.
 
 Notes:
   - Payment is automatic via x402; requires a funded allowance
@@ -257,7 +260,7 @@ async function quote() {
 }
 
 async function provision(args) {
-  const opts = { tier: "prototype", name: undefined, orgId: undefined };
+  const opts = { tier: "prototype", name: undefined, orgId: undefined, idempotencyKey: undefined };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
     // Use !== undefined so an empty-string value is captured (and rejected
@@ -267,6 +270,16 @@ async function provision(args) {
     // Omitted = cold-start. Tier is org-governed, so --tier is irrelevant here
     // (the gateway ignores a client-supplied tier in all cases).
     if (args[i] === "--org" && args[i + 1] !== undefined) opts.orgId = args[++i];
+    // Retry-safety: re-running provision (the agent's natural mode after a
+    // crash/fresh session) must not duplicate-bill a project.
+    if (args[i] === "--idempotency-key" && args[i + 1] !== undefined) opts.idempotencyKey = args[++i];
+  }
+  // Auto-derive a stable key from --name when none was supplied: a named
+  // project is a stable intent, so re-running `provision --name X` collapses
+  // onto the same project. An explicit --idempotency-key always wins; an
+  // unnamed provision stays un-keyed (each call is a new project on purpose).
+  if (opts.idempotencyKey === undefined && opts.name) {
+    opts.idempotencyKey = `provision:${opts.name}`;
   }
   if (opts.orgId === "") {
     fail({
@@ -312,7 +325,7 @@ async function provision(args) {
   const activeBefore = getActiveProjectId();
   try {
     const data = await withAutoApprove(() =>
-      getSdk().projects.provision({ tier: opts.tier, name: opts.name, orgId: opts.orgId }),
+      getSdk().projects.provision({ tier: opts.tier, name: opts.name, orgId: opts.orgId, idempotencyKey: opts.idempotencyKey }),
     );
     const activeAfter = getActiveProjectId();
     const out = { ...data };

package/lib/secrets.mjs

@@ -2,6 +2,7 @@ import { readFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateRegularFile } from "./argparse.mjs";
+import { editRequestAction } from "./next-actions.mjs";
 
 const HELP = `run402 secrets — Manage project secrets
 
@@ -163,8 +164,8 @@ function failMissingStdin() {
     message: "Missing secret value on stdin.",
     hint: "Pipe a value, use --file <path>, or provide an inline value only when shell history exposure is acceptable.",
     next_actions: [
-      "printf %s \"$VALUE\" | run402 secrets set <project> <KEY> --stdin",
-      "run402 secrets set <project> <KEY> --file <path>",
+      editRequestAction("printf %s \"$VALUE\" | run402 secrets set <project> <KEY> --stdin", "Pipe the secret value through stdin."),
+      editRequestAction("run402 secrets set <project> <KEY> --file <path>", "Read the secret value from a local file."),
     ],
   });
 }

package/lib/subdomains.mjs

@@ -2,6 +2,7 @@ import { resolveProject, resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { cliCommandAction } from "./next-actions.mjs";
 
 const HELP = `run402 subdomains — Manage custom subdomains
 
@@ -115,7 +116,7 @@ async function claim(args) {
       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: [{ action: "deploy_site_first" }],
+      next_actions: [cliCommandAction("deploy", "run402 deploy apply", "Deploy a site first, then retry claiming the subdomain.")],
     });
   }
   try {

package/lib/tier.mjs

@@ -1,6 +1,7 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, normalizeArgv, positionalArgs, flagValue } from "./argparse.mjs";
+import { setTierAction } from "./next-actions.mjs";
 
 const HELP = `run402 tier — Manage your Run402 tier subscription
 
@@ -50,11 +51,16 @@ Examples:
   set: `run402 tier set — Subscribe, renew, or upgrade your tier
 
 Usage:
-  run402 tier set <tier>
+  run402 tier set <tier> [--idempotency-key <key>]
 
 Arguments:
   <tier>              One of: prototype, hobby, team
 
+Options:
+  --idempotency-key <key>  Retry-safe key: re-running the same subscribe/renew
+                           intent with this key does not double-charge. Use a
+                           fresh key for a deliberate second renewal.
+
 Tiers:
   prototype           $0.10/7d (free with testnet faucet)
   hobby               $5/30d
@@ -101,8 +107,8 @@ async function status(args = []) {
 
 async function set(args = []) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
+  assertKnownFlags(parsedArgs, ["--help", "-h"], ["--idempotency-key"]);
+  const positionals = positionalArgs(parsedArgs, ["--idempotency-key"]);
   if (positionals.length > 1) {
     fail({
       code: "BAD_USAGE",
@@ -116,11 +122,16 @@ async function set(args = []) {
       code: "BAD_USAGE",
       message: "Missing <tier>.",
       hint: "run402 tier set <prototype|hobby|team>",
+      next_actions: [setTierAction()],
     });
   }
+  // Caller-supplied idempotency key makes a retried subscribe/renew safe from
+  // double-charge. Not auto-derived: the SDK cannot tell a retry from a new
+  // renewal intent (that boundary is the caller's).
+  const idempotencyKey = flagValue(parsedArgs, "--idempotency-key") ?? undefined;
   try {
     const sdk = getSdk();
-    const data = await sdk.tier.set(tierName);
+    const data = await sdk.tier.set(tierName, idempotencyKey ? { idempotencyKey } : {});
     let statusAfter = null;
     try {
       statusAfter = await sdk.tier.status();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "3.5.2",
+  "version": "3.5.4",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/credentials.d.ts

@@ -46,7 +46,7 @@ export interface WalletIdentity {
  * Gateway write-auth (operator-approval) capabilities. Each is scoped to a
  * target: `org.project.create` → an org, the others → a project.
  */
-export type WriteAuthCapability = "org.project.create" | "project.deploy" | "project.secret.write";
+export type WriteAuthCapability = "org.project.create" | "project.deploy" | "project.secret.write" | "project.archives.export";
 /** A write-capability target: an org (for `org.project.create`) or a project. */
 export interface WriteAuthTarget {
     org_id?: string;

package/sdk/dist/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,oBAAoB,GACpB,gBAAgB,GAChB,sBAAsB,CAAC;AAE3B,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,+BAA+B;IAC/B,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAE1F;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEpD;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D,kGAAkG;IAClG,aAAa,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,oEAAoE;IACpE,aAAa,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,kEAAkE;IAClE,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,oEAAoE;IACpE,gBAAgB,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5C,gFAAgF;IAChF,aAAa,CAAC,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEhD,6CAA6C;IAC7C,aAAa,CAAC,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD,oHAAoH;IACpH,eAAe,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAE3C,6FAA6F;IAC7F,gBAAgB,CAAC,IAAI,MAAM,CAAC;IAE5B;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACtD"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,oBAAoB,GACpB,gBAAgB,GAChB,sBAAsB,GACtB,yBAAyB,CAAC;AAE9B,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,+BAA+B;IAC/B,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAE1F;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEpD;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D,kGAAkG;IAClG,aAAa,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,oEAAoE;IACpE,aAAa,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,kEAAkE;IAClE,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,oEAAoE;IACpE,gBAAgB,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5C,gFAAgF;IAChF,aAAa,CAAC,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEhD,6CAA6C;IAC7C,aAAa,CAAC,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD,oHAAoH;IACpH,eAAe,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAE3C,6FAA6F;IAC7F,gBAAgB,CAAC,IAAI,MAAM,CAAC;IAE5B;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACtD"}

package/sdk/dist/errors.d.ts

@@ -58,8 +58,8 @@ export declare abstract class Run402Error extends Error {
     readonly traceId?: string;
     /** Canonical structured context. Preserved by reference from the response body. */
     readonly details?: unknown;
-    /** Advisory next actions from the gateway. Rendering them must not execute them. */
-    readonly nextActions?: unknown[];
+    /** Advisory next actions (gateway-authored or SDK-synthesized). Rendering them must not execute them. */
+    readonly nextActions?: NextAction[];
     /**
      * Quota-denial scope (v1.46+). `"organization"` for pooled organization
      * denials; `"project"` for the orphan fallback (project whose organization
@@ -252,6 +252,29 @@ export declare class TransferFreezeError extends Run402Error {
     readonly projectId: string | null;
     constructor(message: string, status: number, body: unknown, context: string);
 }
+/**
+ * Known `type` values for a {@link NextAction}. The gateway set (style.md
+ * §Errors) extended with the client-side bootstrap verbs `create_project` and
+ * `initialize_wallet`, plus `operator_approve` (synthesized for WRITE_AUTH).
+ * Tolerates unknown future gateway types via the `(string & {})` fallback.
+ */
+export type NextActionType = "retry" | "authenticate" | "submit_payment" | "renew_tier" | "check_usage" | "resume_deploy" | "edit_request" | "edit_migration" | "create_project" | "initialize_wallet" | "deploy" | "operator_approve" | "contact_support";
+/**
+ * A single advisory "what to do next" entry. Mirrors the gateway's
+ * `next_actions[]` shape (`{ type, method?, path?, auth?, why? }`) extended with
+ * `command` — the literal CLI invocation — for client-side, CLI-resolvable
+ * actions. Rendering an action must never execute it.
+ */
+export interface NextAction {
+    type: NextActionType | (string & {});
+    /** Literal CLI invocation for client-side, CLI-resolvable actions. */
+    command?: string;
+    method?: string;
+    path?: string;
+    auth?: string;
+    why?: string;
+    [key: string]: unknown;
+}
 /**
  * HTTP 403 `STEP_UP_REQUIRED` — the gateway requires a fresh, same-client
  * step-up (a recent `passkey` AMR) before this high-stakes control-plane