run402 4.0.3 → 4.1.1

package/README.md

@@ -75,6 +75,7 @@ run402 projects schema <id>                              # introspect tables + R
 run402 sites deploy-dir ./dist                # incremental upload (plan/commit transport)
 run402 deploy apply --manifest app.json       # one-call full stack deploy
 run402 apply --manifest app.json --rehearse --json
+run402 deploy verify op_... --project prj_... --wait
 run402 deploy release active                  # inspect current-live release inventory
 run402 deploy release diff --from empty --to active
 run402 deploy diagnose --project prj_123 https://example.com/events --method GET
@@ -83,7 +84,7 @@ run402 subdomains claim my-app                # → my-app.run402.com (auto-reas
 ```
 
 `deploy-dir` hashes each file client-side and only uploads bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`. Progress events stream to stderr.
-Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy diagnose` / `deploy resolve --url` print URL-first diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
+Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. `deploy verify` prints the canonical edge-coherence report and exits 2 when the report is valid but not yet coherent. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy diagnose` / `deploy resolve --url` print URL-first diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
 
 For database-bearing changes, use `run402 apply --manifest app.json --rehearse --json` before commit. It creates a contained branch, applies the candidate plan there, runs checks, and exits nonzero on a failed rehearsal. Manual restore points live under `run402 snapshots create|list|get|restore|delete`; temporary data branches live under `run402 branches create|list|renew|delete`.
 
@@ -153,7 +154,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. 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. `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/cli.mjs

@@ -27,7 +27,7 @@ Commands:
   credentials Manage local credential material (project-keys)
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
-  projects    Manage projects (provision, list, query, inspect, delete)
+  projects    Manage projects (provision, list, get, sql, delete)
   apply       Alias for deploy apply; supports --rehearse for migration rehearsal
   snapshots   Create/list/restore/delete project data snapshots
   branches    Create/list/renew/delete contained project branches

package/lib/allowance.mjs

@@ -242,7 +242,17 @@ async function balance() {
   }, null, 2));
 }
 
-async function exportAddr() {
+async function exportAddr(args = []) {
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, [], []);
+  const bare = positionalArgs(parsedArgs, []);
+  if (bare.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for allowance export: ${bare[0]}`,
+      details: { argument: bare[0] },
+    });
+  }
   try {
     const address = await getSdk().allowance.export();
     console.log(JSON.stringify({ address }));
@@ -333,7 +343,7 @@ export async function run(sub, args) {
     case "create":  await create(); break;
     case "fund":    await fund(); break;
     case "balance": await balance(); break;
-    case "export":   await exportAddr(); break;
+    case "export":   await exportAddr(args); break;
     case "checkout": await checkout(args); break;
     case "history":  await history(args); break;
     default:

package/lib/deploy-v2.mjs

@@ -190,6 +190,33 @@ Output:
   stdout: { "events": [...] }
 `;
 
+const VERIFY_HELP = `run402 deploy verify — Verify gateway and edge coherence
+
+Usage:
+  run402 deploy verify <operation_id> [--project <id>] [--wait] [--timeout <seconds>] [--json]
+  run402 deploy verify --operation <operation_id> [--project <id>] [--wait] [--timeout <seconds>] [--json]
+
+Checks that the gateway's live release and the edge pointers observed by
+Run402 agree for the deployment operation. Use --wait to poll until the report
+is coherent or the timeout elapses.
+
+Options:
+  --operation <id>       Operation id to verify. Equivalent to the positional id.
+  --project <id>         Project ID that owns the operation (default: active project)
+  --wait                 Poll until coherent or timeout
+  --timeout <seconds>    Maximum wait time with --wait (default 60)
+  --json                 No-op compatibility flag; output is always JSON
+
+Exit codes:
+  0  coherent
+  2  valid report, but not coherent before timeout
+  1  usage, auth, network, or gateway error
+
+Output:
+  stdout: { "status": "coherent"|"not_coherent", "coherent": boolean, "report": {...} }
+  stderr: one JSON poll progress line per attempt when --wait is set
+`;
+
 const REHEARSE_HELP = `run402 deploy rehearse — Run a persisted plan on a contained branch
 
 Usage:
@@ -301,6 +328,7 @@ export async function runDeployV2(sub, args) {
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
+  if (sub === "verify") return await verifyCmd(args);
   if (sub === "release") return await releaseCmd(args);
   if (sub === "diagnose") return await diagnoseCmd(args);
   if (sub === "resolve") return await resolveCmd(args);
@@ -1594,6 +1622,100 @@ async function eventsCmd(args) {
   }
 }
 
+async function verifyCmd(args) {
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy verify",
+    help: VERIFY_HELP,
+    valueFlags: ["--project", "--operation", "--timeout"],
+    booleanFlags: ["--wait", "--json"],
+  });
+  const positionals = expectPositionals(parsed.positionals, {
+    command: "run402 deploy verify <operation_id> [--project <id>] [--wait]",
+    max: 1,
+  });
+  const positionalOperationId = positionals[0] ?? null;
+  const flaggedOperationId = parsed.flags["--operation"] ?? null;
+  if (positionalOperationId && flaggedOperationId && positionalOperationId !== flaggedOperationId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Pass the operation id either positionally or with --operation, not both.",
+      details: { positional: positionalOperationId, operation: flaggedOperationId },
+    });
+  }
+  const operationId = flaggedOperationId ?? positionalOperationId;
+  if (!operationId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy verify <operation_id> [--project <id>] [--wait]",
+    });
+  }
+  const project = resolveProjectId(parsed.flags["--project"] ?? null);
+  const wait = Boolean(parsed.flags["--wait"]);
+  const timeoutSeconds = parsed.flags["--timeout"] === undefined
+    ? 60
+    : parsePositiveInt(parsed.flags["--timeout"], "--timeout");
+
+  allowanceAuthHeaders("/apply/v1/operations");
+
+  try {
+    let result;
+    if (wait) {
+      result = await getSdk()._applyEngine.waitEdgeCoherent(operationId, {
+        project,
+        timeoutMs: timeoutSeconds * 1000,
+        onPoll: (event) => {
+          console.error(JSON.stringify({
+            type: "deploy.verify.poll",
+            coherent: event.report.coherent,
+            attempts: event.attempts,
+            elapsed_ms: event.elapsedMs,
+            pending_count: event.report.pending_count,
+            path_count: event.report.path_count,
+            total_path_count: event.report.total_path_count,
+            paths_truncated: event.report.paths_truncated,
+            paths: summarizeEdgeCoherencePaths(event.report.paths),
+          }));
+        },
+      });
+    } else {
+      const report = await getSdk()._applyEngine.edgeCoherence(operationId, { project });
+      result = { coherent: report.coherent, attempts: 1, elapsedMs: 0, report };
+    }
+    const output = {
+      status: result.coherent ? "coherent" : "not_coherent",
+      coherent: result.coherent,
+      operation_id: result.report.operation_id,
+      project_id: result.report.project_id,
+      attempts: result.attempts,
+      elapsed_ms: result.elapsedMs,
+      report: result.report,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    if (!result.coherent) process.exitCode = 2;
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function summarizeEdgeCoherencePaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  return paths.map((path) => ({
+    path: path.path,
+    host: path.host,
+    state: path.state,
+    observed_confidence: path.observed_confidence,
+    expected_release_id: path.expected_release_id,
+    observed_release_id: path.observed_release_id,
+    expected_release_generation: path.expected_release_generation,
+    observed_release_generation: path.observed_release_generation,
+    status: path.status,
+    x_cache: path.x_cache,
+    age_seconds: path.age_seconds,
+    error: path.error,
+  }));
+}
+
 async function releaseCmd(args) {
   const action = args[0];
   if (!action || action === "--help" || action === "-h") {
@@ -1843,7 +1965,7 @@ function parseDeploySubcommandArgs(rawArgs, { command, help, valueFlags = [], bo
   const args = normalizeArgv(rawArgs);
   const valueFlagSet = new Set(valueFlags);
   const booleanFlagSet = new Set(booleanFlags);
-  const numericFlagSet = new Set(["--limit", "--site-limit"]);
+  const numericFlagSet = new Set(["--limit", "--site-limit", "--timeout"]);
   const allowedFlags = new Set([...valueFlags, ...booleanFlags, "--help", "-h"]);
   const flags = {};
   const positionals = [];

package/lib/deploy.mjs

@@ -11,6 +11,7 @@ Subcommands:
   resume <operation_id>         Resume a stuck operation
   list [--project <id>]         List recent deploy operations
   events <operation_id>         Fetch event stream for an operation
+  verify <operation_id>         Verify gateway and edge coherence
   diagnose <url>                Diagnose public URL routing
   resolve --url <url>           Low-level resolve diagnostics
   release ...                   Inspect release inventory and diffs
@@ -55,6 +56,7 @@ export async function run(args) {
     case "resume":
     case "list":
     case "events":
+    case "verify":
     case "diagnose":
     case "resolve":
     case "release": {

package/lib/doctor.mjs

@@ -56,6 +56,13 @@ Exit codes:
   1  — one or more checks failed (details in output)
 `;
 
+function redactAllowanceForDiagnostics(allowance) {
+  if (!allowance || typeof allowance !== "object") return allowance;
+  const safe = { ...allowance };
+  delete safe.privateKey;
+  return safe;
+}
+
 export async function run(sub, args = []) {
   const all = [sub, ...args].filter(Boolean);
   if (all.includes("--help") || all.includes("-h")) {
@@ -113,8 +120,9 @@ export async function run(sub, args = []) {
         value: {
           rail: allowance.rail,
           // Don't surface amounts or addresses unless --verbose; agents
-          // checking for config presence don't need wallet details.
-          ...(verbose && { details: allowance }),
+          // checking for config presence don't need wallet details. Never
+          // include keystore secrets in diagnostics, even in verbose mode.
+          ...(verbose && { details: redactAllowanceForDiagnostics(allowance) }),
         },
       });
     } else {
@@ -182,19 +190,34 @@ export async function run(sub, args = []) {
     const sdk = getSdk();
     const tier = await sdk.tier.status();
     const tierName = tier?.tier ?? null;
-    if (tierName && tierName !== "past_due" && tierName !== "frozen" && tierName !== "dormant") {
+    const lifecycle = tier?.organization_lifecycle_state ?? null;
+    const active = tier?.active === true;
+    if (tierName && active && lifecycle === "active") {
       checks.push({
         name: "tier",
         status: "ok",
-        value: { tier: tierName },
+        value: { tier: tierName, active, organization_lifecycle_state: lifecycle },
       });
     } else {
+      const status = lifecycle && lifecycle !== "active"
+        ? lifecycle
+        : tierName && !active
+          ? "inactive"
+          : tierName && lifecycle === null
+            ? "unknown"
+            : tierName ?? "missing";
       checks.push({
         name: "tier",
-        status: tierName ?? "missing",
-        ...(tierName && {
-          hint: "Run 'run402 tier set prototype' to subscribe (or upgrade).",
-        }),
+        status,
+        value: {
+          tier: tierName,
+          active,
+          organization_lifecycle_state: lifecycle,
+          lease_expires_at: tier?.lease_expires_at ?? null,
+        },
+        hint: lifecycle === null && tierName
+          ? "Tier resolved, but organization lifecycle could not be determined. Check `run402 tier status` before assuming the account is healthy."
+          : "Run 'run402 tier set prototype' to subscribe, renew, or reactivate the tier.",
       });
     }
   } catch (err) {

package/lib/up.mjs

@@ -8,7 +8,7 @@ import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs
 const HELP = `run402 up — Provision/link/deploy the current app
 
 Usage:
-  run402 up [repo-or-path] [--name <name>] [--project <id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--plan|--require-plan <id>] [--human|--json-stream] [--quiet]
+  run402 up [repo-or-path] [--name <name>] [--project <id>] [--manifest <path>] [--dir <path>] [--tier <tier>] [-y|--yes] [--check|--print-spec|--plan|--require-plan <id>] [--verify] [--human|--json-stream] [--quiet]
   run402 up verify [repo-or-path] [--project <id>] [--manifest <path>] [--dir <path>] [--human|--json-stream]
 
 Options:
@@ -44,6 +44,8 @@ Options:
   --propagation-budget-s <n>
                       Maximum wall-clock seconds to wait for fresh edge
                       propagation during app HTTP verification (default 120).
+  --verify            After a deploy apply, wait for gateway/edge release
+                      coherence and attach the report to the final result.
   --no-propagation-wait
                       Return propagation_pending immediately when the edge is
                       still settling.
@@ -121,6 +123,7 @@ export async function run(args = []) {
       "--allow-warnings",
       "--allow-prune",
       "--allow-shell-build",
+      "--verify",
       "--no-propagation-wait",
       "--json",
       "--human",
@@ -206,6 +209,7 @@ export async function run(args = []) {
   const quiet = parsed.includes("--quiet") || parsed.includes("--final-only") || jsonStream;
   const mode = parseExecutionMode(parsed);
   const dryRun = parsed.includes("--dry-run");
+  const verifyEdge = parsed.includes("--verify");
   if (human && (parsed.includes("--json") || jsonStream)) {
     fail({
       code: "BAD_USAGE",
@@ -220,6 +224,13 @@ export async function run(args = []) {
       details: { flag: "--dry-run" },
     });
   }
+  if (verifyEdge && (dryRun || isNonApplyingMode(mode))) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--verify can only be used when run402 up applies a deploy.",
+      details: { flag: "--verify", mode: dryRun ? "dry-run" : mode },
+    });
+  }
   if (isApplyReviewedMode(mode) && (parsed.includes("--allow-warnings") || parsed.includes("--allow-warning"))) {
     fail({
       code: "BAD_USAGE",
@@ -263,6 +274,14 @@ export async function run(args = []) {
               console.error(JSON.stringify(event));
             },
     });
+    const edgeWait = verifyEdge
+      ? await attachEdgeVerification(result, {
+          sdk,
+          timeoutSeconds: propagationBudgetSeconds ?? 120,
+          jsonStream,
+          quiet,
+        })
+      : null;
     if (jsonStream) {
       console.log(JSON.stringify({ type: "run402.up.result", result }));
     } else if (mode === "printSpec") {
@@ -277,6 +296,9 @@ export async function run(args = []) {
     if (shouldExitNonZeroForUpResult(result)) {
       process.exitCode = 1;
     }
+    if (edgeWait && !edgeWait.coherent && process.exitCode !== 1) {
+      process.exitCode = 2;
+    }
   } catch (err) {
     reportSdkError(err);
   }
@@ -415,6 +437,62 @@ function isApplyReviewedMode(mode) {
   return mode && typeof mode === "object" && mode.kind === "applyReviewed";
 }
 
+function isNonApplyingMode(mode) {
+  return mode === "check" || mode === "printSpec" || mode === "plan";
+}
+
+async function attachEdgeVerification(result, { sdk, timeoutSeconds, jsonStream, quiet }) {
+  const deploy = result?.result?.deploy;
+  const operationId = deploy?.operation_id;
+  const projectId = result?.result?.project_id;
+  if (!operationId || !projectId || String(operationId).startsWith("core:")) {
+    return null;
+  }
+  const scoped = await sdk.project(projectId);
+  const wait = await scoped.apply.waitEdgeCoherent(operationId, {
+    timeoutMs: timeoutSeconds * 1000,
+    onPoll: (event) => {
+      const line = {
+        type: "deploy.verify.poll",
+        coherent: event.report.coherent,
+        attempts: event.attempts,
+        elapsed_ms: event.elapsedMs,
+        pending_count: event.report.pending_count,
+        path_count: event.report.path_count,
+        total_path_count: event.report.total_path_count,
+        paths_truncated: event.report.paths_truncated,
+        paths: summarizeEdgeCoherencePaths(event.report.paths),
+      };
+      if (jsonStream) console.log(JSON.stringify({ type: "action.event", event: line }));
+      else if (!quiet) console.error(JSON.stringify(line));
+    },
+  });
+  result.result.edge_coherence = wait;
+  result.result.deploy = {
+    ...deploy,
+    edge_coherence: wait.report,
+  };
+  return wait;
+}
+
+function summarizeEdgeCoherencePaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  return paths.map((path) => ({
+    path: path.path,
+    host: path.host,
+    state: path.state,
+    observed_confidence: path.observed_confidence,
+    expected_release_id: path.expected_release_id,
+    observed_release_id: path.observed_release_id,
+    expected_release_generation: path.expected_release_generation,
+    observed_release_generation: path.observed_release_generation,
+    status: path.status,
+    x_cache: path.x_cache,
+    age_seconds: path.age_seconds,
+    error: path.error,
+  }));
+}
+
 function collectRepeatedValues(args, flag) {
   const values = [];
   for (let i = 0; i < args.length; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.0.3",
+  "version": "4.1.1",
   "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/namespaces/deploy.d.ts

@@ -19,7 +19,7 @@
  * behavior; this file is the implementation.
  */
 import type { Client } from "../kernel.js";
-import type { ApplyOptions, ActiveReleaseInventory, DeployEvent, DeployEventsResponse, DeployListOptions, DeployListResponse, DeployOperation, DeployResult, DeployResolveOptions, DeployResolveResponse, OperationSnapshot, PlanResponse, PromoteOptions, PromoteResult, ReleaseDiffOptions, ReleaseInventory, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseSpec, ReleaseToReleaseDiff, RehearsePlanOptions, RehearsePlanResult, StartOptions } from "./deploy.types.js";
+import type { ApplyOptions, ActiveReleaseInventory, DeployEvent, DeployEventsResponse, DeployListOptions, DeployListResponse, DeployOperation, DeployResult, DeployResolveOptions, DeployResolveResponse, EdgeCoherenceReport, EdgeCoherenceWaitOptions, EdgeCoherenceWaitResult, OperationSnapshot, PlanResponse, PromoteOptions, PromoteResult, ReleaseDiffOptions, ReleaseInventory, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseSpec, ReleaseToReleaseDiff, RehearsePlanOptions, RehearsePlanResult, StartOptions } from "./deploy.types.js";
 export declare class Deploy {
     private readonly client;
     constructor(client: Client);
@@ -149,6 +149,20 @@ export declare class Deploy {
     events(operationId: string, opts: {
         project: string;
     }): Promise<DeployEventsResponse>;
+    /**
+     * Probe whether the gateway and edge pointers agree on the active release
+     * for an operation. The endpoint requires `apikey` auth, so `project` is
+     * required. Use `waitEdgeCoherent` when you want bounded polling.
+     */
+    edgeCoherence(operationId: string, opts: {
+        project: string;
+    }): Promise<EdgeCoherenceReport>;
+    /**
+     * Poll `edgeCoherence` until the report is coherent or the timeout elapses.
+     * Returns the last report either way so automation can explain stale paths
+     * without issuing a second request.
+     */
+    waitEdgeCoherent(operationId: string, opts: EdgeCoherenceWaitOptions): Promise<EdgeCoherenceWaitResult>;
     /**
      * Fetch a release inventory by id. The endpoint requires `apikey` auth, so
      * pass the owning project id. `siteLimit` controls how many site paths the

package/sdk/dist/namespaces/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"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"}

package/sdk/dist/namespaces/deploy.js

@@ -376,6 +376,57 @@ export class Deploy {
             throw translateDeployError(err, "events", null, operationId);
         }
     }
+    /**
+     * Probe whether the gateway and edge pointers agree on the active release
+     * for an operation. The endpoint requires `apikey` auth, so `project` is
+     * required. Use `waitEdgeCoherent` when you want bounded polling.
+     */
+    async edgeCoherence(operationId, opts) {
+        if (!operationId || !operationId.startsWith("op_")) {
+            throw new Run402DeployError(`Invalid operation id: "${operationId}"`, {
+                code: "OPERATION_NOT_FOUND",
+                retryable: false,
+                context: "verifying deploy edge coherence",
+            });
+        }
+        if (!opts?.project) {
+            throw new LocalError("apply.edgeCoherence requires a project id ({ project: 'prj_...' })", "verifying deploy edge coherence");
+        }
+        const headers = await apikeyHeaders(this.client, opts.project);
+        try {
+            return await this.client.request(`/apply/v1/operations/${encodeURIComponent(operationId)}/edge-coherence`, { headers, context: "verifying deploy edge coherence" });
+        }
+        catch (err) {
+            throw translateDeployError(err, "edge-coherence", null, operationId);
+        }
+    }
+    /**
+     * Poll `edgeCoherence` until the report is coherent or the timeout elapses.
+     * Returns the last report either way so automation can explain stale paths
+     * without issuing a second request.
+     */
+    async waitEdgeCoherent(operationId, opts) {
+        const timeoutMs = normalizePositiveSafeIntegerQueryOption(opts?.timeoutMs ?? 60_000, "apply.waitEdgeCoherent timeoutMs", "waiting for deploy edge coherence") ?? 60_000;
+        const intervalMs = normalizePositiveSafeIntegerQueryOption(opts?.intervalMs ?? 1_000, "apply.waitEdgeCoherent intervalMs", "waiting for deploy edge coherence") ?? 1_000;
+        if (!opts?.project) {
+            throw new LocalError("apply.waitEdgeCoherent requires a project id ({ project: 'prj_...' })", "waiting for deploy edge coherence");
+        }
+        const start = Date.now();
+        let attempts = 0;
+        while (true) {
+            attempts += 1;
+            const report = await this.edgeCoherence(operationId, { project: opts.project });
+            const elapsedMs = Date.now() - start;
+            opts.onPoll?.({ attempts, elapsedMs, report });
+            if (report.coherent) {
+                return { coherent: true, attempts, elapsedMs, report };
+            }
+            if (elapsedMs >= timeoutMs) {
+                return { coherent: false, attempts, elapsedMs, report };
+            }
+            await sleep(Math.min(intervalMs, Math.max(timeoutMs - elapsedMs, 0)));
+        }
+    }
     /**
      * Fetch a release inventory by id. The endpoint requires `apikey` auth, so
      * pass the owning project id. `siteLimit` controls how many site paths the
@@ -1645,6 +1696,7 @@ async function pollUntilReady(client, commit, diff, warnings, emit, projectId, s
             diff,
             warnings,
             ...(commit.subdomain_bindings ? { subdomain_bindings: commit.subdomain_bindings } : {}),
+            ...(commit.edge ? { edge: commit.edge } : {}),
         };
     }
     const opHeaders = projectId ? await apikeyHeaders(client, projectId) : {};
@@ -1744,6 +1796,7 @@ async function pollSnapshotUntilReady(client, initial, diff, warnings, emit, pro
                 diff,
                 warnings,
                 ...(snapshot.subdomain_bindings ? { subdomain_bindings: snapshot.subdomain_bindings } : {}),
+                ...(snapshot.edge ? { edge: snapshot.edge } : {}),
             };
         }
         if (TERMINAL_STATUSES.includes(snapshot.status)) {