feat(release-promote): SDK r.project(id).apply.promote + run402 deploy promote CLI

Client-side wiring for the v1.58 gateway endpoint
POST /apply/v1/releases/:id/promote (run402-private commit b25ae87b,
deploy fix a47961ac). Operator pointer-swap recovery primitive — re-point
internal.projects.live_release_id at an existing release without
re-running the apply pipeline.

SDK:

- deploy.types.ts: PromoteOptions, PromoteResult, PromoteDiff exported.
  Mirror ApplyOptions for the parts that apply (allowWarnings,
  allowWarningCodes); skip onEvent / idempotencyKey / maxRetries
  (promote is single-shot).
- deploy.ts: Deploy.promote(project, releaseId, opts) method. POSTs to
  /apply/v1/releases/:id/promote with body { project, allow_warning_codes }.
  Local validation for releaseId shape (must start with rel_) + project
  id non-empty. allowWarnings: true expands to the known
  blocking-warning list (currently [MIGRATIONS_NOT_REVERSIBLE]) — no
  server-side wildcard accept.
- scoped.ts: ScopedApplyHero.promote attached to the hero. Direct-SDK
  consumers call r.project(id).apply.promote(releaseId, opts).

CLI:

- cli/lib/deploy-v2.mjs: promoteCmd + parsePromoteArgs + PROMOTE_HELP.
  Positional <release-id> (must be rel_*), --project (falls back to
  active project), --allow-warning (repeatable), --allow-warnings
  (ack all blocking), --quiet. Calls _applyEngine.promote directly
  (same pattern as the rest of the CLI — getSdk() returns the
  unwrapped Run402 instance whose project() is async, so the hero
  path would need an extra await for marginal clarity).
- cli/lib/deploy.mjs: 'promote' added to the deploy-subcommand allowlist.
- cli/llms-cli.txt: Recovery-from-destructive-apply paragraph with
  worked example + the full structured-warning + error-code surface.
  Promote listed in the CLI deploy-surface bullet list.

sync.test.ts: SURFACE entry { id: deploy_promote, endpoint:
POST /apply/v1/releases/:id/promote, cli: deploy:promote,
openclaw: deploy:promote }; SDK_BY_CAPABILITY mapping to
_applyEngine.promote.

End-to-end verified against the deployed gateway: PROMOTE_TARGET_NOT_FOUND
returns the right code + structured envelope + trace_id when a
nonexistent release is passed. 667 SDK + 32 sync + 244 astro tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

cli/lib/deploy-v2.mjs

@@ -267,6 +267,7 @@ exit 0; inspect would_serve and diagnostic_status in the result payload.
 
 export async function runDeployV2(sub, args) {
   if (sub === "apply") return await applyCmd(args);
+  if (sub === "promote") return await promoteCmd(args);
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
@@ -280,6 +281,189 @@ export async function runDeployV2(sub, args) {
   });
 }
 
+const PROMOTE_HELP = `run402 deploy promote — Operator pointer-swap recovery (v1.58+)
+
+Usage:
+  run402 deploy promote <release-id> [--project <id>] [--allow-warning <code>] [--allow-warnings] [--quiet]
+
+Re-points the project's live release at an existing release row without
+re-running the apply pipeline. Designed for "oops on a real project ID"
+recovery — when an apply shipped content the operator regrets, promote
+back to the prior release in seconds instead of re-deploying.
+
+Promotable statuses: ready, active, superseded. Releases with status
+'failed' or 'staging' are rejected (they never fully landed).
+
+Surfaces structured warnings:
+
+  MIGRATIONS_NOT_REVERSIBLE (requires_confirmation: true)
+    The target release predates migrations applied since. Those
+    migrations remain applied — the post-promote release runs against
+    the current schema. Ack with --allow-warning MIGRATIONS_NOT_REVERSIBLE.
+
+  FUNCTION_VERSION_MISMATCH (informational, no ack needed)
+    Overlapping function names have different code_hashes. The Lambda
+    code is whatever's currently $LATEST.
+
+Worked example: recover from a destructive apply
+
+  # rel_old (good)  →  rel_new (bad, destructive)  →  promote back
+  run402 deploy promote rel_old_abc123 --project prj_xyz \\
+    --allow-warning MIGRATIONS_NOT_REVERSIBLE
+
+Options:
+  <release-id>            Required positional. The release to promote to.
+                          Format: rel_*
+  --project <id>          Project id. Falls back to active project, then
+                          RUN402_PROJECT_ID env var.
+  --allow-warning <code>  Acknowledge a specific blocking warning
+                          (repeatable).
+  --allow-warnings        Acknowledge ALL blocking promote warnings.
+                          Use this for full recovery mode when you've
+                          already inspected the diff.
+  --quiet | --final-only  Suppress per-event stderr; only print the
+                          final JSON envelope on stdout.
+
+Output:
+  stdout: {
+    "status": "ok",
+    "release_id": "rel_old_abc123",
+    "operation_id": "op_...",
+    "previous_release_id": "rel_new_xxx",
+    "diff": { "functions": {...}, "migrations": {...}, "site_paths": {...} },
+    "warnings": [...]
+  }
+
+  Errors map to structured envelopes with codes:
+    PROMOTE_TARGET_NOT_FOUND        404 — release id doesn't exist
+    PROMOTE_PROJECT_MISMATCH        400 — release belongs to another project
+    PROMOTE_RELEASE_NOT_READY       409 — release status not promotable
+    PROMOTE_NO_OP                   409 — target = current live (use
+                                          cache.invalidateAll instead)
+    PROMOTE_WARNING_REQUIRES_ACK    409 — at least one blocking warning
+                                          unacked; details list codes`;
+
+function parsePromoteArgs(args) {
+  const opts = {
+    releaseId: null,
+    project: null,
+    allowWarnings: false,
+    allowWarningCodes: [],
+    quiet: false,
+  };
+  const allowedFlags = [
+    "--project",
+    "--allow-warning",
+    "--allow-warnings",
+    "--quiet",
+    "--final-only",
+    "--help",
+    "-h",
+  ];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log(PROMOTE_HELP);
+      process.exit(0);
+    }
+    if (arg === "--project" || arg === "--allow-warning") {
+      const value = args[i + 1];
+      if (value === undefined || (typeof value === "string" && value.startsWith("--"))) {
+        fail({
+          code: "BAD_USAGE",
+          message: `${arg} requires a value`,
+          details: { flag: arg },
+        });
+      }
+      if (arg === "--project") {
+        opts.project = value;
+      } else {
+        opts.allowWarningCodes.push(value);
+      }
+      i += 1;
+      continue;
+    }
+    if (arg === "--quiet" || arg === "--final-only") {
+      opts.quiet = true;
+      continue;
+    }
+    if (arg === "--allow-warnings") {
+      opts.allowWarnings = true;
+      continue;
+    }
+    if (typeof arg === "string" && arg.startsWith("-")) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Unknown flag for deploy promote: ${arg}`,
+        details: { flag: arg, allowed_flags: allowedFlags },
+      });
+    }
+    // Positional: the release id
+    if (opts.releaseId !== null) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Unexpected positional argument for deploy promote: ${arg}`,
+        details: { argument: arg, already_have: opts.releaseId },
+      });
+    }
+    opts.releaseId = arg;
+  }
+
+  if (opts.releaseId === null) {
+    fail({
+      code: "BAD_USAGE",
+      message: "deploy promote requires a release id (positional argument)",
+      details: { example: "run402 deploy promote rel_abc123" },
+    });
+  }
+  if (typeof opts.releaseId !== "string" || !opts.releaseId.startsWith("rel_")) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Invalid release id: '${opts.releaseId}' (expected rel_*)`,
+      details: { release_id: opts.releaseId },
+    });
+  }
+
+  return opts;
+}
+
+async function promoteCmd(args) {
+  const opts = parsePromoteArgs(args);
+  const projectId = opts.project ?? resolveProjectId(null);
+
+  // Preserve the aggressive early-exit when no allowance is configured
+  // — same as apply.
+  allowanceAuthHeaders("/apply/v1/releases");
+
+  try {
+    // Call the engine directly (matches the pattern used by apply / resume
+    // in this file). The `r.project(id).apply.promote` hero exists for
+    // direct-SDK consumers; the CLI's `getSdk()` returns the unwrapped
+    // Run402 instance whose `project()` method is async, so going through
+    // the hero here would require an extra `await`.
+    const result = await getSdk()._applyEngine.promote(projectId, opts.releaseId, {
+      allowWarnings: opts.allowWarnings,
+      allowWarningCodes: opts.allowWarningCodes,
+    });
+    if (!opts.quiet) {
+      // Emit a single structured stderr event so observers can pick it up
+      // alongside the regular deploy event stream. Promote is a one-shot
+      // operation; there are no intermediate phase events.
+      console.error(JSON.stringify({
+        type: "promote.committed",
+        release_id: result.release_id,
+        previous_release_id: result.previous_release_id,
+        operation_id: result.operation_id,
+        warnings: result.warnings,
+      }));
+    }
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);

cli/lib/deploy.mjs

@@ -49,6 +49,7 @@ export async function run(args) {
 
   switch (sub) {
     case "apply":
+    case "promote":
     case "resume":
     case "list":
     case "events":

cli/llms-cli.txt

@@ -322,6 +322,16 @@ run402 deploy resume <operation_id>
 
 The gateway re-runs only the failed phase forward — SQL is never replayed.
 
+Recovery from a destructive apply (v1.58+): when an `apply` shipped content the operator regrets (accidental destructive prune, content overwrite, broken release), `run402 deploy promote <release-id>` re-points the project's live release at a prior release row WITHOUT re-running the apply pipeline. No bytes-upload, no bundling, no migration — just a pointer swap on `internal.projects.live_release_id` plus an ssr_cache flush. Designed for "oops on a real project ID" recovery in seconds rather than re-deploying.
+
+```bash
+# rel_old (good)  →  rel_new (bad, destructive)  →  promote back
+run402 deploy promote rel_old_abc123 --project prj_xyz \
+  --allow-warning MIGRATIONS_NOT_REVERSIBLE
+```
+
+Surfaces structured warnings. `MIGRATIONS_NOT_REVERSIBLE` (requires_confirmation: true) fires when the target release predates migrations applied since — the migrations remain applied, so the post-promote release runs against the current schema. Ack with `--allow-warning MIGRATIONS_NOT_REVERSIBLE`. `FUNCTION_VERSION_MISMATCH` (informational) fires when overlapping function names have different code_hashes; the Lambda code is whatever's currently `$LATEST`. Rejected codes: `PROMOTE_TARGET_NOT_FOUND` (release id doesn't exist), `PROMOTE_PROJECT_MISMATCH` (release belongs to another project), `PROMOTE_RELEASE_NOT_READY` (release status not promotable: must be `ready`, `active`, or `superseded`), `PROMOTE_NO_OP` (target IS already the current live; use `cache.invalidateAll` to refresh cache instead), `PROMOTE_WARNING_REQUIRES_ACK` (at least one blocking warning unacked).
+
 Inspect deploy history: list recent operations for a project, or pull the recorded phase-event stream for a specific operation (after the fact — for live progress events during an in-flight deploy, the `apply` command already streams them on stderr):
 
 ```bash
@@ -817,6 +827,7 @@ All admin subcommands require a platform-admin allowance wallet (or an admin OAu
 ### deploy
 - `run402 deploy apply --manifest app.json [--project <id>] [--quiet|--final-only] [--allow-warning <code> ...] [--allow-warnings]` — unified apply primitive (v1.34 unified deploy → v2.0 unified apply with `assets` slice support)
 - `run402 deploy resume <operation_id> [--quiet]` — re-run a stuck operation forward
+- `run402 deploy promote <release-id> [--project <id>] [--allow-warning <code>] [--allow-warnings]` — operator pointer-swap (re-point live release without re-running the apply pipeline); v1.58+
 - `run402 deploy list [--project <id>] [--limit <n>]` — list recent deploy operations
 - `run402 deploy events <operation_id> [--project <id>]` — fetch the recorded event stream for an operation
 - `run402 deploy release get <release_id> [--project <id>] [--site-limit <n>]` — fetch release inventory

sdk/src/namespaces/deploy.ts

@@ -71,6 +71,8 @@ import type {
   OperationStatus,
   PlanRequest,
   PlanResponse,
+  PromoteOptions,
+  PromoteResult,
   ReleaseDiffOptions,
   ReleaseInventory,
   ReleaseInventoryByIdOptions,
@@ -297,6 +299,81 @@ export class Deploy {
     return await pollSnapshotUntilReady(this.client, snapshot, {}, [], emit, opts.project);
   }
 
+  /**
+   * Promote an existing release to be the project's current live release —
+   * a pointer swap on `internal.projects.live_release_id` without re-running
+   * the apply pipeline. Designed for operator recovery from a destructive
+   * apply ("oops on a real project ID"). The prior release's bytes,
+   * functions, and migrations remain persisted; this just routes traffic
+   * back to them.
+   *
+   * Surfaces structured warnings via the result envelope:
+   *
+   *   - `MIGRATIONS_NOT_REVERSIBLE` (requires_confirmation: true) when the
+   *     target release predates migrations applied since. The migrations
+   *     remain applied; the new live release runs against the current
+   *     schema. Ack via `opts.allowWarningCodes`.
+   *
+   *   - `FUNCTION_VERSION_MISMATCH` (informational) when overlapping
+   *     function names have different code_hashes. The Lambda code is
+   *     whatever's currently $LATEST.
+   *
+   * Rejected cases:
+   *   - `PROMOTE_TARGET_NOT_FOUND` — releaseId doesn't exist
+   *   - `PROMOTE_PROJECT_MISMATCH` — releaseId belongs to a different project
+   *   - `PROMOTE_RELEASE_NOT_READY` — release status isn't promotable
+   *   - `PROMOTE_NO_OP` — releaseId IS already the project's current live
+   *   - `PROMOTE_WARNING_REQUIRES_ACK` — at least one blocking warning unacked
+   *
+   * Capability: unified-deploy (v1.58+, release-promote).
+   */
+  async promote(
+    project: string,
+    releaseId: string,
+    opts: PromoteOptions = {},
+  ): Promise<PromoteResult> {
+    if (!project || typeof project !== "string") {
+      throw new Run402DeployError(`Invalid project id: "${String(project)}"`, {
+        code: "BAD_REQUEST",
+        retryable: false,
+        context: "promoting release",
+      });
+    }
+    if (!releaseId || !releaseId.startsWith("rel_")) {
+      throw new Run402DeployError(`Invalid release id: "${releaseId}"`, {
+        code: "BAD_REQUEST",
+        retryable: false,
+        context: "promoting release",
+      });
+    }
+    // Note: `allowWarnings: true` is implemented client-side by enumerating
+    // every known blocking warning code, since the gateway expects a precise
+    // list per warning code (no wildcard accept). v1.58 has exactly one
+    // blocking promote warning (MIGRATIONS_NOT_REVERSIBLE); if more land,
+    // expand this list.
+    const ALL_BLOCKING_PROMOTE_WARNINGS = ["MIGRATIONS_NOT_REVERSIBLE"];
+    const allowCodes =
+      opts.allowWarnings === true
+        ? ALL_BLOCKING_PROMOTE_WARNINGS
+        : (opts.allowWarningCodes ?? []);
+    try {
+      return await this.client.request<PromoteResult>(
+        `/apply/v1/releases/${encodeURIComponent(releaseId)}/promote`,
+        {
+          method: "POST",
+          context: "promoting release",
+          headers: { "content-type": "application/json" },
+          body: {
+            project,
+            allow_warning_codes: allowCodes,
+          },
+        },
+      );
+    } catch (err) {
+      throw translateDeployError(err, "promote", null, releaseId);
+    }
+  }
+
   /**
    * Snapshot a deploy operation. The endpoint requires `apikey` auth, so
    * pass the project that owns the operation. (When omitted, the request

sdk/src/namespaces/deploy.types.ts

@@ -2368,6 +2368,49 @@ export interface StartOptions {
   allowWarningCodes?: string[];
 }
 
+/**
+ * Options for the `r.project(id).apply.promote(releaseId, opts?)` operator
+ * pointer-swap operation. Mirrors `ApplyOptions` for the parts that apply
+ * (`allowWarnings`, `allowWarningCodes`); skips the parts that don't
+ * (`onEvent` — promote is a single-shot operation, no per-phase events;
+ * `idempotencyKey` — gateway derives idempotency from `(project, release_id)`;
+ * `maxRetries` — no plan-time race window).
+ */
+export interface PromoteOptions {
+  /** Continue past confirmation-required warnings (e.g. MIGRATIONS_NOT_REVERSIBLE).
+   *  Default false: the gateway aborts before the pointer swap when a
+   *  blocking warning isn't covered. */
+  allowWarnings?: boolean;
+  /** Cover specific confirmation-required warning codes. Every blocking
+   *  warning must be covered by this list or by `allowWarnings`. */
+  allowWarningCodes?: string[];
+}
+
+/**
+ * Result envelope returned by `r.project(id).apply.promote(releaseId, opts?)`.
+ * The promote operation is a single-shot pointer swap; no phase events,
+ * no payment-required hook (promote uses existing-release content).
+ */
+export interface PromoteResult {
+  status: "ok";
+  /** The release id now live on the project. Equal to the input releaseId. */
+  release_id: string;
+  /** The new `internal.apply_operations` row id (created with kind='promote'). */
+  operation_id: string;
+  /** The release that was live BEFORE the swap. */
+  previous_release_id: string;
+  /** Structured diff between previous and new live release. */
+  diff: PromoteDiff;
+  /** Any structured warnings produced — including ones the caller acked. */
+  warnings: WarningEntry[];
+}
+
+export interface PromoteDiff {
+  functions: { only_in_current: string[]; only_in_target: string[]; changed: string[] };
+  migrations: { only_in_current: string[]; only_in_target: string[] };
+  site_paths: { added_in_current: number; removed_in_current: number };
+}
+
 export interface DeployOperation {
   /** The operation id (also exposed via the snapshot). */
   readonly id: string;