deepspace 0.14.0 → 0.15.0

package/dist/cli.js

@@ -3,8 +3,8 @@
 // src/cli/cli.ts
 import { defineCommand as defineCommand14, runMain, runCommand, renderUsage } from "citty";
 import { sync as spawnSync8 } from "cross-spawn";
-import { readFileSync as readFileSync28, existsSync as existsSync26 } from "fs";
-import { dirname as dirname10, join as join24 } from "path";
+import { readFileSync as readFileSync29, existsSync as existsSync27 } from "fs";
+import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/lib/spinner.ts
@@ -89,11 +89,12 @@ function printAction(action) {
 
 // src/cli/lib/api.ts
 var ApiError = class extends Error {
-  constructor(message, status3, code, apiPath) {
+  constructor(message, status3, code, apiPath, details) {
     super(message);
     this.status = status3;
     this.code = code;
     this.apiPath = apiPath;
+    this.details = details;
   }
 };
 var refreshAuthToken = null;
@@ -387,6 +388,9 @@ var Refusal = class extends Error {
     this.extra = opts.extra ?? {};
   }
 };
+function apiErrorDetails(err) {
+  return err instanceof ApiError ? err.details : void 0;
+}
 function withoutReservedKeys(payload) {
   return Object.fromEntries(
     Object.entries(payload).filter(
@@ -450,7 +454,7 @@ function defineDeepspaceCommand(def) {
               ...refusal?.actionRequired ? { actionRequired: true } : {},
               error: message,
               ...refusal?.action ? { action: refusal.action } : {},
-              ...withoutReservedKeys(refusal?.extra ?? {})
+              ...withoutReservedKeys(refusal?.extra ?? apiErrorDetails(err) ?? {})
             })
           );
         } else {
@@ -734,7 +738,7 @@ async function provisionProfile(jwt) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve19) => setTimeout(resolve19, ms));
+  return new Promise((resolve20) => setTimeout(resolve20, ms));
 }
 function base64url(bytes) {
   return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -1305,7 +1309,7 @@ function upsertWorktreeLaunchConfig(mainRepoRoot, worktreeName, appDir, opts) {
     let port = opts.port;
     if (opts.probePort) {
       const taken = new Set(
-        config.configurations.map((c) => Number(c?.port)).filter((p34) => Number.isInteger(p34) && p34 > 0)
+        config.configurations.map((c) => Number(c?.port)).filter((p35) => Number.isInteger(p35) && p35 > 0)
       );
       for (let i = 0; i < WORKTREE_PORT_RANGE && taken.has(port); i++) {
         port = WORKTREE_PORT_MIN + (port - WORKTREE_PORT_MIN + 1) % WORKTREE_PORT_RANGE;
@@ -2328,18 +2332,18 @@ function ensureInstallReady(appDir) {
   const logPath = join9(sentinelDir, "install.log");
   if (existsSync9(errPath)) {
     const detail = readFileSync11(errPath, "utf-8").trimEnd();
-    const log28 = existsSync9(logPath) ? ` Full log: ${logPath}.` : "";
+    const log29 = existsSync9(logPath) ? ` Full log: ${logPath}.` : "";
     throw new Refusal(
-      `Dependency install failed: ${detail}.${log28} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
+      `Dependency install failed: ${detail}.${log29} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
       "install_failed",
       { action: { cwd: appDir, argv: [detectPackageManager(appDir), "install"] } }
     );
   }
   if (existsSync9(startedPath) && !existsSync9(donePath)) {
     if (!installWorkerAlive(sentinelDir)) {
-      const log28 = existsSync9(logPath) ? ` See what happened: ${logPath}.` : "";
+      const log29 = existsSync9(logPath) ? ` See what happened: ${logPath}.` : "";
       throw new Refusal(
-        `The dependency install is no longer running and never finished.${log28} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
+        `The dependency install is no longer running and never finished.${log29} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
         "install_failed",
         { action: { cwd: appDir, argv: [detectPackageManager(appDir), "install"] } }
       );
@@ -2488,7 +2492,7 @@ function lintSchema(schema) {
     const offendingRoles = Object.entries(schema.permissions).filter(([, perms]) => perms.read === true).map(([role]) => role);
     if (offendingRoles.length > 0) {
       const usesAware = Object.values(schema.permissions).some(
-        (p34) => typeof p34.read === "string" && VISIBILITY_AWARE.includes(p34.read)
+        (p35) => typeof p35.read === "string" && VISIBILITY_AWARE.includes(p35.read)
       );
       if (!usesAware) {
         warnings.push(
@@ -2573,11 +2577,11 @@ import { createServer, Socket } from "net";
 var DEFAULT_PORT = 5173;
 function isPortListening(port, host, timeoutMs = 500) {
   const target2 = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
-  return new Promise((resolve19) => {
+  return new Promise((resolve20) => {
     const socket = new Socket();
     const done = (listening) => {
       socket.destroy();
-      resolve19(listening);
+      resolve20(listening);
     };
     socket.setTimeout(timeoutMs);
     socket.once("connect", () => done(true));
@@ -2590,7 +2594,7 @@ async function waitForPortListening(port, host, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isPortListening(port, host)) return true;
-    await new Promise((resolve19) => setTimeout(resolve19, 250));
+    await new Promise((resolve20) => setTimeout(resolve20, 250));
   }
   return false;
 }
@@ -3797,60 +3801,97 @@ import { defineCommand as defineCommand3 } from "citty";
 import { resolve as resolve12 } from "path";
 
 // src/cli/lib/edge-propagation.ts
-var NOT_SERVING = ["Assets have not yet deployed", "No app configured"];
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+
+// src/shared/app-routing.ts
 var RELEASE_STAMP_PATH = "/.well-known/deepspace/release.json";
+var SDK_RUN_WORKER_FIRST = [
+  "/api/*",
+  "/ws/*",
+  "/internal/*",
+  "/v1/*",
+  "/_deepspace/*",
+  "/llms.txt",
+  "/llms-full.txt",
+  "/.well-known/mcp",
+  "/.well-known/mcp.json",
+  "/.well-known/mcp/*"
+];
+var DOCUMENTATION_PATHS = [
+  "/_documentation",
+  "/_documentation/*",
+  "/_documentation-root",
+  "/_documentation-root/*"
+];
+var RESERVED_RUN_WORKER_FIRST = [
+  ...SDK_RUN_WORKER_FIRST,
+  ...DOCUMENTATION_PATHS
+];
+
+// src/cli/lib/edge-propagation.ts
+var CONSECUTIVE_MATCHES = 10;
+var MATCH_INTERVAL_MS = 250;
 async function waitForLiveRelease(url, releaseStamp, timeoutMs) {
-  return releaseStamp ? waitForReleaseStamp(url, releaseStamp, timeoutMs) : waitForEdgePropagation(url, timeoutMs);
-}
-async function waitForReleaseStamp(url, releaseStamp, timeoutMs) {
+  if (!releaseStamp) return "unverifiable";
   const deadline = Date.now() + timeoutMs;
   let attempt = 0;
   let streak = 0;
   while (Date.now() < deadline) {
     attempt++;
-    try {
-      const probe = new URL(RELEASE_STAMP_PATH, url);
-      probe.searchParams.set("probe", `${Date.now()}-${attempt}`);
-      const response = await fetch(probe, { redirect: "manual" });
-      const body = await response.json().catch(() => null);
-      if (response.ok && body?.release === releaseStamp) {
-        streak++;
-        if (streak >= 3) return true;
-        await new Promise((resolve19) => setTimeout(resolve19, 1500));
-        continue;
-      }
-      streak = 0;
-    } catch {
-      streak = 0;
+    const probe = new URL(RELEASE_STAMP_PATH, url);
+    probe.searchParams.set("probe", `${Date.now()}-${attempt}`);
+    if (await servesRelease(probe, releaseStamp)) {
+      streak++;
+      if (streak >= CONSECUTIVE_MATCHES) return "confirmed";
+      await sleep2(MATCH_INTERVAL_MS);
+      continue;
     }
-    const waitMs = Math.min(8e3, 1e3 * 2 ** (attempt - 1));
-    await new Promise((resolve19) => setTimeout(resolve19, waitMs));
+    streak = 0;
+    await sleep2(Math.min(4e3, 500 * 2 ** Math.min(attempt - 1, 3)));
   }
-  return false;
+  return "unconfirmed";
 }
-async function waitForEdgePropagation(url, timeoutMs) {
-  const deadline = Date.now() + timeoutMs;
-  let attempt = 0;
-  let streak = 0;
-  while (Date.now() < deadline) {
-    attempt++;
-    try {
-      const response = await fetch(url, { redirect: "manual" });
-      const body = await response.text();
-      if (!NOT_SERVING.some((marker) => body.includes(marker))) {
-        streak++;
-        if (streak >= 3) return true;
-        await new Promise((resolve19) => setTimeout(resolve19, 1500));
-        continue;
-      }
-      streak = 0;
-    } catch {
-      streak = 0;
-    }
-    const waitMs = Math.min(8e3, 1e3 * 2 ** (attempt - 1));
-    await new Promise((resolve19) => setTimeout(resolve19, waitMs));
+async function servesRelease(probe, releaseStamp) {
+  const body = await getOnFreshConnection(probe);
+  if (body === null) return false;
+  try {
+    return JSON.parse(body).release === releaseStamp;
+  } catch {
+    return false;
   }
-  return false;
+}
+function getOnFreshConnection(url, timeoutMs = 5e3) {
+  const send = url.protocol === "http:" ? httpRequest : httpsRequest;
+  return new Promise((resolve20) => {
+    const request2 = send(
+      url,
+      { method: "GET", agent: false, timeout: timeoutMs, headers: { "cache-control": "no-cache" } },
+      (response) => {
+        if (response.statusCode !== 200) {
+          response.resume();
+          resolve20(null);
+          return;
+        }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          if (body.length < 4096) body += chunk;
+        });
+        response.on("end", () => resolve20(body));
+        response.on("error", () => resolve20(null));
+      }
+    );
+    request2.on("timeout", () => {
+      request2.destroy();
+      resolve20(null);
+    });
+    request2.on("error", () => resolve20(null));
+    request2.end();
+  });
+}
+function sleep2(ms) {
+  return new Promise((resolve20) => setTimeout(resolve20, ms));
 }
 
 // src/shared/app-files.ts
@@ -3944,7 +3985,7 @@ function readDocumentationDeployManifest(appDir, clientDir) {
   return JSON.parse(readFileSync15(manifestPath, "utf8"));
 }
 
-// src/cli/commands/migrate/app-migrations.ts
+// src/cli/commands/update/app-migrations.ts
 import {
   closeSync,
   constants,
@@ -3961,7 +4002,7 @@ import { join as join15 } from "path";
 // src/shared/protocol/app-migrations.ts
 var APP_MIGRATION_ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
 var MAX_APP_MIGRATION_IDS = 256;
-var CANONICAL_APP_IDENTITY_MIGRATION_ID = "2026-08-canonical-app-identity-wire";
+var WORKER_OWNED_NOT_FOUND_MIGRATION_ID = "2026-08-worker-owned-not-found";
 function validateAppMigrationIds(value) {
   if (!Array.isArray(value)) {
     return { valid: false, reason: "app migrations must be a JSON string array" };
@@ -3987,14 +4028,14 @@ function validateAppMigrationIds(value) {
   return { valid: true, ids };
 }
 
-// src/cli/commands/migrate/app-migrations.ts
+// src/cli/commands/update/app-migrations.ts
 var APP_MIGRATIONS_MANIFEST = "deepspace.migrations.json";
 var SOURCE_MIGRATIONS = [
   {
-    id: CANONICAL_APP_IDENTITY_MIGRATION_ID,
-    description: "Use the immutable app id for authenticated platform requests",
-    transform: migrateCanonicalIdentityWire,
-    findBlockers: findLegacyIdentityWireBlockers
+    id: WORKER_OWNED_NOT_FOUND_MIGRATION_ID,
+    description: "Let the worker answer misses, so deleted files 404 instead of serving HTML",
+    transform: migrateWorkerOwnedNotFound,
+    findBlockers: findWorkerOwnedNotFoundBlockers
   }
 ];
 var APP_MIGRATION_DEFINITIONS = SOURCE_MIGRATIONS.map(
@@ -4039,7 +4080,7 @@ function planAppMigrations(appDir) {
     const before = readRegularFile(absolutePath);
     let after = before;
     for (const migration of pendingMigrations) {
-      const result = migration.transform(after);
+      const result = migration.transform(after, repoPath);
       after = result.source;
       if (result.replacements > 0) {
         const planned = perMigration.get(migration.id) ?? {
@@ -4076,9 +4117,6 @@ function planAppMigrations(appDir) {
   };
 }
 function applyAppMigrationPlan(appDir, plan) {
-  if (plan.blockers.length > 0) {
-    throw new Error("Cannot apply an app migration plan with unresolved blockers.");
-  }
   const repo = repoToplevel(appDir);
   for (const edit of plan.edits) {
     const absolutePath = join15(repo, edit.path);
@@ -4138,119 +4176,78 @@ function writeRegularFile(path, before, after) {
 }
 function isSourcePath(repoPath, appPrefix) {
   if (appPrefix && !repoPath.startsWith(appPrefix)) return false;
+  if (repoPath.endsWith("wrangler.toml")) return true;
   return /\.(?:[cm]?[jt]sx?)$/.test(repoPath);
 }
-function migrateCanonicalIdentityWire(source) {
+function migrateWorkerOwnedNotFound(source, file) {
   let replacements = 0;
-  const lines = source.split("\n");
-  for (let index = 0; index < lines.length; index++) {
-    let line = lines[index];
-    line = line.replace(
-      /(\.set\(\s*)(['"])x-app-name\2(\s*,\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME(\s*\))/g,
-      (_match, open, quote, separator, receiver, close) => {
-        replacements++;
-        return `${open}${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID${close}`;
-      }
-    );
-    line = line.replace(
-      /(['"])x-app-name\1(\s*:\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME/g,
-      (_match, quote, separator, receiver) => {
-        replacements++;
-        return `${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID`;
-      }
-    );
-    line = line.replace(
-      /(\[\s*)(['"])x-app-name\2(\s*\]\s*=\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME/g,
-      (_match, open, quote, separator, receiver) => {
-        replacements++;
-        return `${open}${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID`;
-      }
-    );
-    line = line.replace(
-      /(forwardedParams\.set\(\s*)(['"])appName\2(\s*,\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME(\s*\))/g,
-      (_match, open, quote, separator, receiver, close) => {
-        replacements++;
-        return `${open}${quote}appId${quote}${separator}${receiver}.DEEPSPACE_APP_ID${close}`;
-      }
-    );
-    lines[index] = line;
-  }
-  if (replacements === 0) return { source, replacements };
-  let migrated = lines.join("\n");
-  if (/forwardedParams\.set\(\s*['"]appId['"]/.test(migrated)) {
-    migrated = migrated.replaceAll("injectAppName", "injectAppId").replaceAll("`?appName=...`", "`?appId=...`").replaceAll("Inject appName into the query string", "Inject appId into the query string").replaceAll("caller-supplied appName", "caller-supplied appId").replaceAll(
-      "/_deepspace/subscriptions/plans?appName=",
-      "/_deepspace/subscriptions/plans?appId="
-    );
+  if (file.endsWith("wrangler.toml")) {
+    const next = source.replace(/not_found_handling\s*=\s*"single-page-application"/g, () => {
+      replacements++;
+      return 'not_found_handling = "none"';
+    });
+    return { source: next, replacements };
   }
-  migrated = migrated.replaceAll(
-    "APP_IDENTITY_TOKEN + APP_NAME",
-    "APP_IDENTITY_TOKEN + DEEPSPACE_APP_ID"
+  const retargeted = source.replace(
+    /(url\.pathname\s*=\s*)(['"])\/index\.html\2/g,
+    (_match, assignment, quote) => {
+      replacements++;
+      return `${assignment}${quote}/${quote}`;
+    }
   );
-  return {
-    source: ensureCanonicalIdentityProperties(migrated),
-    replacements
-  };
+  const guarded = insertFileMissGuard(retargeted);
+  return { source: guarded.source, replacements: replacements + guarded.replacements };
 }
-function ensureCanonicalIdentityProperties(source) {
+var SHELL_FALLBACK_LINE = /^(\s*)url\.pathname\s*=\s*(['"])\/\2\s*$/;
+var GUARD_LOOKBACK_LINES = 8;
+function insertFileMissGuard(source) {
   const lines = source.split("\n");
+  let replacements = 0;
   for (let index = lines.length - 1; index >= 0; index--) {
-    const match = /^(\s*)(?:readonly\s+)?APP_NAME\??\s*:\s*string\s*([;,]?)\s*$/.exec(lines[index]);
-    if (!match || blockAlreadyDeclaresCanonicalId(lines, index, match[1].length)) continue;
-    const suffix = match[2] ?? "";
-    lines.splice(index + 1, 0, `${match[1]}DEEPSPACE_APP_ID: string${suffix}`);
+    const match = SHELL_FALLBACK_LINE.exec(lines[index]);
+    if (!match || hasFileMissGuard(lines, index)) continue;
+    const indent = match[1];
+    lines.splice(
+      index,
+      0,
+      `${indent}// A FILE, not a client route: a miss must 404. Returning the shell here`,
+      `${indent}// is HTML parsed as JavaScript, which is a blank page.`,
+      `${indent}if (${FILE_MISS_TEST}) {`,
+      `${indent}  return c.json({ error: 'not_found' }, 404)`,
+      `${indent}}`
+    );
+    replacements++;
   }
-  return lines.join("\n");
+  return { source: lines.join("\n"), replacements };
 }
-function blockAlreadyDeclaresCanonicalId(lines, propertyIndex, propertyIndent) {
-  for (const direction of [-1, 1]) {
-    for (let index = propertyIndex + direction; index >= 0 && index < lines.length; index += direction) {
-      const line = lines[index];
-      if (/^\s*(?:readonly\s+)?DEEPSPACE_APP_ID\??\s*:/.test(line)) return true;
-      const trimmed = line.trimStart();
-      if (!trimmed) continue;
-      const indent = line.length - trimmed.length;
-      if (indent < propertyIndent && (trimmed.includes("{") || trimmed.startsWith("}"))) break;
-    }
-  }
-  return false;
+var FILE_MISS_TEST = "url.pathname.slice(url.pathname.lastIndexOf('/') + 1).includes('.')";
+function hasFileMissGuard(lines, fallbackIndex) {
+  const start = Math.max(0, fallbackIndex - GUARD_LOOKBACK_LINES);
+  return lines.slice(start, fallbackIndex).some((line) => line.includes(FILE_MISS_TEST) || /\bnamesAFile\s*\(/.test(line));
 }
-function findLegacyIdentityWireBlockers(source, file) {
+function findWorkerOwnedNotFoundBlockers(source, file) {
+  if (file.endsWith("wrangler.toml")) return [];
+  if (!source.includes("ASSETS")) return [];
   const blockers = [];
-  for (const [index, line] of source.split("\n").entries()) {
-    const trimmed = line.trimStart();
-    if (!/['"]x-app-name['"]/.test(line) || /\.delete\(\s*['"]x-app-name['"]/.test(line) || trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) {
-      continue;
-    }
+  const lines = source.split("\n");
+  for (const [index, line] of lines.entries()) {
+    if (!/['"`]\/index\.html/.test(line)) continue;
     blockers.push({
-      migrationId: CANONICAL_APP_IDENTITY_MIGRATION_ID,
+      migrationId: WORKER_OWNED_NOT_FOUND_MIGRATION_ID,
       file,
       line: index + 1,
-      message: "This app still sends the removed x-app-name identity header in a form the safe migration cannot rewrite."
+      message: `This worker still asks the asset layer for "/index.html". Deploys now set not_found_handling = "none", and "/index.html" redirects to "/" \u2014 the browser follows it and loses the path it asked for. Fetch "/" instead, and 404 first when the last path segment contains a "." (a file, not a client route).`
     });
   }
   return blockers;
 }
 
 // src/cli/commands/deploy/build.ts
-var RESERVED_RUN_WORKER_FIRST = /* @__PURE__ */ new Set([
-  "/api/*",
-  "/ws/*",
-  "/internal/*",
-  "/v1/*",
-  "/_deepspace/*",
-  "/_documentation",
-  "/_documentation/*",
-  "/_documentation-root",
-  "/_documentation-root/*",
-  // Agent-protocol paths: the worker must see them so they cannot fall through
-  // to the SPA shell (templates/base/src/server/http-routes.ts reserves them).
-  "/llms.txt",
-  "/llms-full.txt",
-  "/.well-known/mcp",
-  "/.well-known/mcp.json",
-  "/.well-known/mcp/*"
-]);
+var RESERVED_RUN_WORKER_FIRST2 = new Set(RESERVED_RUN_WORKER_FIRST);
+function declaredCompatibilityDate(config) {
+  const declared = config.compatibility_date;
+  return typeof declared === "string" && /^\d{4}-\d{2}-\d{2}$/.test(declared) ? declared : null;
+}
 async function buildDeployBundle(options) {
   const { appDir, appName, envName, sharedDevVarsCache, output, spinner: spinner2 } = options;
   const junk = removeMacosJunk(appDir);
@@ -4362,7 +4359,10 @@ async function buildDeployBundle(options) {
     appMigrations,
     doManifest,
     customBindings,
-    extraRoutes
+    extraRoutes,
+    compatibilityDate: declaredCompatibilityDate(outputConfig),
+    compatibilityFlags: Array.isArray(outputConfig.compatibility_flags) ? outputConfig.compatibility_flags.filter((flag) => typeof flag === "string") : [],
+    notFoundHandling: typeof outputConfig.assets?.not_found_handling === "string" ? outputConfig.assets.not_found_handling : null
   };
 }
 function extractRunWorkerFirst(config) {
@@ -4372,7 +4372,7 @@ function extractRunWorkerFirst(config) {
   for (const entry of raw) {
     if (typeof entry !== "string") continue;
     const route = entry.trim();
-    if (!route.startsWith("/") || RESERVED_RUN_WORKER_FIRST.has(route) || seen.has(route)) continue;
+    if (!route.startsWith("/") || RESERVED_RUN_WORKER_FIRST2.has(route) || seen.has(route)) continue;
     seen.add(route);
     routes.push(route);
   }
@@ -5418,7 +5418,7 @@ async function pushWithTransientRetry(push) {
       const message = errorMessage3(error);
       const transient = /(?:HTTP |error: )(?:429|503)\b/i.test(message);
       if (transient && attempt < backoffMs.length && Date.now() + backoffMs[attempt] < deadline) {
-        await new Promise((resolve19) => setTimeout(resolve19, backoffMs[attempt]));
+        await new Promise((resolve20) => setTimeout(resolve20, backoffMs[attempt]));
         continue;
       }
       throw error;
@@ -5510,6 +5510,15 @@ async function deployBuiltBundle(options) {
     if (Object.keys(bundle.assetConfig).length) {
       form.append("assetConfig", JSON.stringify(bundle.assetConfig));
     }
+    if (bundle.compatibilityDate) {
+      form.append("compatibilityDate", bundle.compatibilityDate);
+    }
+    if (bundle.compatibilityFlags.length) {
+      form.append("compatibilityFlags", JSON.stringify(bundle.compatibilityFlags));
+    }
+    if (bundle.notFoundHandling) {
+      form.append("notFoundHandling", bundle.notFoundHandling);
+    }
     form.append("name", appName);
     if (confirmRename) form.append("confirmRename", "true");
     if (shouldSendLineage(repository.commitOid, repository.recoverable)) {
@@ -5763,7 +5772,7 @@ async function postWithRetry(url, makeInit, {
       lastError = error;
     }
     if (attempt < attempts) {
-      await new Promise((resolve19) => setTimeout(resolve19, Math.min(8e3, 500 * 2 ** (attempt - 1))));
+      await new Promise((resolve20) => setTimeout(resolve20, Math.min(8e3, 500 * 2 ** (attempt - 1))));
     }
   }
   if (lastResponse) return lastResponse;
@@ -5883,46 +5892,6 @@ function errorMessage5(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-// src/cli/commands/migrate/legacy-app-id.ts
-var LEGACY_APP_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
-function readLegacyAppId(cwd = process.cwd(), wranglerEnv) {
-  const cfg = readWranglerIdentityConfig(cwd);
-  if (!cfg) return null;
-  const slot = wranglerEnv ? cfg.env?.[wranglerEnv] : cfg;
-  if (!slot) return null;
-  const declaredId = slot.vars?.DEEPSPACE_APP_ID;
-  if (declaredId !== void 0) {
-    if (typeof declaredId === "string" && LEGACY_APP_ID_RE.test(declaredId)) return declaredId;
-    throw new InputError(
-      "DEEPSPACE_APP_ID is present but invalid; correct it before migrating.",
-      "invalid_app_id"
-    );
-  }
-  const appName = typeof slot.vars?.APP_NAME === "string" ? slot.vars.APP_NAME : null;
-  const workerName = typeof slot.name === "string" ? slot.name : null;
-  if (!appName) return null;
-  if (!workerName) {
-    throw new InputError(
-      "Legacy migration requires both Worker name and APP_NAME to be present and identical.",
-      "ambiguous_legacy_app_id"
-    );
-  }
-  if (appName !== workerName) {
-    throw new InputError(
-      `Legacy APP_NAME "${appName}" does not match Worker name "${workerName}"; migration cannot choose safely.`,
-      "ambiguous_legacy_app_id"
-    );
-  }
-  return !APP_ID_RE.test(appName) && LEGACY_APP_ID_RE.test(appName) ? appName : null;
-}
-function legacyDeployRefusal(appDir, wranglerEnv) {
-  const legacyAppId = readLegacyAppId(appDir, wranglerEnv);
-  return legacyAppId ? {
-    error: `This checkout still uses legacy app identity ${legacyAppId}. Run \`deepspace app migrate --dry-run\`, then complete \`deepspace app migrate\` before deploying.`,
-    code: "legacy_app_migration_required"
-  } : null;
-}
-
 // src/cli/commands/deploy.ts
 var DEPLOY_URL3 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 var deploy_default = defineCommand3({
@@ -6006,10 +5975,6 @@ var deploy_default = defineCommand3({
     }
     const appName = nameResult.name;
     let appId = readAppId(appDir, envName);
-    if (!appId) {
-      const refusal = legacyDeployRefusal(appDir, envName);
-      if (refusal) output.die(refusal.error, refusal.code);
-    }
     p12.log.info(envName ? `App: ${appName}  (env: ${envName})` : `App: ${appName}`);
     const { token, ownerId } = await authenticate(appDir, output);
     if (!appId) {
@@ -6075,15 +6040,18 @@ var deploy_default = defineCommand3({
       output,
       spinner: spinner2
     });
+    let serving = "unverifiable";
     if (body.url) {
-      spinner2.message("Waiting for edge propagation...");
-      const ready = await waitForLiveRelease(body.url, body.releaseStamp, 9e4);
-      if (!ready) {
-        spinner2.stop("Deployed (edge propagation still in progress after 90s)");
+      spinner2.message("Waiting for the edge to serve this release...");
+      serving = await waitForLiveRelease(body.url, body.releaseStamp, 9e4);
+      if (serving !== "confirmed") {
+        spinner2.stop(
+          serving === "unconfirmed" ? "Deployed \u2014 the edge is still rolling this release out" : "Deployed \u2014 serving could not be verified from here"
+        );
         p12.log.warn(
-          "First requests may briefly hit the assets transitional page; retry in a minute."
+          serving === "unconfirmed" ? "Some requests still get the previous release. Cloudflare rolls a version out per edge machine; it usually settles within a couple of minutes. Wait before asserting against it." : "This release carries no serving stamp (older platform, or a resumed deploy), so the CLI cannot tell which release the edge answers with."
         );
-        p12.log.info(`URL: ${body.url} (deploy accepted; serving not yet verified from here)`);
+        p12.log.info(`URL: ${body.url}`);
         await syncCommerce(appDir, appId, token, output.nonInteractive);
         if (output.json) {
           return output.emitJson({
@@ -6093,7 +6061,10 @@ var deploy_default = defineCommand3({
             url: body.url,
             releaseId: body.releaseId ?? null,
             bundleRetained: body.bundleRetained ?? null,
-            edgePropagating: true,
+            // `serving` says what was actually established; `edgePropagating`
+            // stays for callers written against the old shape.
+            serving,
+            edgePropagating: serving === "unconfirmed",
             recoverable: repository.recoverable,
             ...staleBaseGuardFields(body)
           });
@@ -6111,6 +6082,9 @@ var deploy_default = defineCommand3({
         appId,
         appName,
         url: body.url ?? null,
+        // Always present, so a caller branches on one field instead of
+        // inferring success from the absence of `edgePropagating`.
+        serving,
         releaseId: body.releaseId ?? null,
         bundleRetained: body.bundleRetained ?? null,
         recoverable: repository.recoverable,
@@ -6565,7 +6539,7 @@ function formatEvent(e, color, now = Date.now()) {
   const client = e.source === "client" ? paint("35", "CLIENT", color) + " " : "";
   return `${time} ${client}${tag} ${body}`;
 }
-var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
 var logs_default = defineCommand4({
   meta: {
     name: "logs",
@@ -6685,7 +6659,7 @@ var logs_default = defineCommand4({
       }
     }
     for (; ; ) {
-      await sleep2(backoff || interval);
+      await sleep3(backoff || interval);
       const freshToken = await ensureToken();
       let page;
       try {
@@ -7855,11 +7829,11 @@ function fmtDate(iso) {
 }
 async function confirm4(message) {
   process.stdout.write(`${message} [y/N] `);
-  return new Promise((resolve19) => {
+  return new Promise((resolve20) => {
     process.stdin.setEncoding("utf-8");
     process.stdin.once("data", (data) => {
       const answer = data.toString().trim().toLowerCase();
-      resolve19(answer === "y" || answer === "yes");
+      resolve20(answer === "y" || answer === "yes");
     });
   });
 }
@@ -8211,8 +8185,14 @@ async function request(baseUrl, token, path, init = {}) {
   if (res.ok) return res;
   const text2 = await res.text();
   let code;
+  let details;
   try {
-    code = JSON.parse(text2.trim()).code;
+    const body = JSON.parse(text2.trim());
+    code = typeof body.code === "string" ? body.code : void 0;
+    const rest = Object.fromEntries(
+      Object.entries(body).filter(([key]) => key !== "error" && key !== "code")
+    );
+    if (Object.keys(rest).length > 0) details = rest;
   } catch {
   }
   throw new ApiError(
@@ -8222,7 +8202,8 @@ async function request(baseUrl, token, path, init = {}) {
     // oversized request short is not a different failure from the worker
     // refusing it, and two codes made it look like one.
     code ?? (res.status === 413 ? "too_large" : res.status >= 500 ? "server_error" : "http_error"),
-    path
+    path,
+    details
   );
 }
 async function readJson(res, path) {
@@ -8585,8 +8566,8 @@ var list4 = defineDeepspaceCommand({
       }
       if (pending.length) {
         console.log(`PENDING INVITES ON ${app2}`);
-        for (const p34 of pending) {
-          console.log(`  ${p34.email} (expires ${new Date(p34.expiresAt).toLocaleDateString()})`);
+        for (const p35 of pending) {
+          console.log(`  ${p35.email} (expires ${new Date(p35.expiresAt).toLocaleDateString()})`);
         }
       }
     }
@@ -8684,7 +8665,7 @@ var cancel3 = defineDeepspaceCommand({
       `/api/app-collaborators/${encodeURIComponent(app2)}`
     );
     const target2 = email.trim().toLowerCase();
-    const found = pending.find((p34) => p34.email.toLowerCase() === target2);
+    const found = pending.find((p35) => p35.email.toLowerCase() === target2);
     if (!found) {
       throw new Refusal(`${email} has no pending invite on ${app2}`, "no_pending_invite", {
         action: cliAction("deepspace", "app", "collaborators", "list", "--app", app2)
@@ -8742,7 +8723,10 @@ var accept = defineDeepspaceCommand({
     }
     return {
       data: { ...res },
-      action: cliAction("deepspace", "pull", "--app", res.appId)
+      // `pull` fast-forwards a checkout this caller does not have yet — the
+      // invite just granted access, so there is nothing local to update.
+      // `clone` is the step that actually works from here.
+      action: cliAction("deepspace", "clone", res.appId)
     };
   }
 });
@@ -11032,13 +11016,14 @@ Re-run with --allow-do-deletion to accept the data loss.`,
         "invalid_response"
       );
     }
-    let edgePropagating = false;
+    let serving = "unverifiable";
     if (result.url) {
-      spinner2?.message("Waiting for edge propagation...");
-      edgePropagating = !await waitForLiveRelease(result.url, result.releaseStamp, 9e4);
+      spinner2?.message("Waiting for the edge to serve this release...");
+      serving = await waitForLiveRelease(result.url, result.releaseStamp, 9e4);
     }
+    const edgePropagating = serving === "unconfirmed";
     spinner2?.stop(
-      edgePropagating ? `Rolled back to ${result.rolledBackTo ?? releaseId} (edge propagation still in progress after 90s).` : `Rolled back to ${result.rolledBackTo ?? releaseId}.`
+      serving === "confirmed" ? `Rolled back to ${result.rolledBackTo ?? releaseId}.` : serving === "unconfirmed" ? `Rolled back to ${result.rolledBackTo ?? releaseId} \u2014 the edge is still rolling it out.` : `Rolled back to ${result.rolledBackTo ?? releaseId} \u2014 serving could not be verified from here.`
     );
     const doClassGuard = result.doClassGuard === "unverified" ? "unverified" : void 0;
     if (!args.json) {
@@ -11069,6 +11054,8 @@ Re-run with --allow-do-deletion to accept the data loss.`,
         url: result.url ?? null,
         versionId: result.versionId ?? null,
         wranglerEnv: wranglerEnv ?? null,
+        // Always present, matching `deploy`: one field to branch on.
+        serving,
         ...edgePropagating ? { edgePropagating: true } : {},
         ...doClassGuard ? { doClassGuard } : {}
       }
@@ -13072,541 +13059,183 @@ function sameRefs(left, right) {
   return left.every((ref) => expected.get(ref.name) === ref.oid);
 }
 
-// src/cli/commands/migrate/identity-api.ts
-async function getIdentityMigration(deployUrl, token, appId) {
-  try {
-    const result = await apiFetch(
-      deployUrl,
-      token,
-      `/api/apps/${encodeURIComponent(appId)}/identity-migration`
-    );
-    return result.migration;
-  } catch (error) {
-    if (error instanceof ApiError && error.code === "migration_not_found") return null;
-    throw error;
-  }
-}
-async function prepareIdentityMigration(deployUrl, token, legacyAppId, input) {
-  const result = await apiFetch(
-    deployUrl,
-    token,
-    `/api/apps/${encodeURIComponent(legacyAppId)}/identity-migration/prepare`,
-    { method: "POST", body: JSON.stringify(input) }
-  );
-  return result.migration;
-}
-async function inspectIdentityMigration(deployUrl, token, legacyAppId, input) {
-  const result = await apiFetch(
-    deployUrl,
-    token,
-    `/api/apps/${encodeURIComponent(legacyAppId)}/identity-migration/inspect`,
-    { method: "POST", body: JSON.stringify(input) }
+// src/cli/commands/update.ts
+import * as p34 from "@clack/prompts";
+import { existsSync as existsSync26, readFileSync as readFileSync28, writeFileSync as writeFileSync10 } from "fs";
+import { join as join24, resolve as resolve19 } from "path";
+var REGISTRY = "https://registry.npmjs.org/deepspace/latest";
+var DOCS_URL = "https://documentation.deep.space/cli-reference/commands";
+var OLDEST_SUPPORTED_MINOR = 12;
+function parseVersion(raw) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(raw.trim().replace(/^[\^~]/, ""));
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function gapIsTooWide(from, to) {
+  if (from.major !== to.major) return true;
+  return from.major === 0 && from.minor < OLDEST_SUPPORTED_MINOR;
+}
+function readAppSdkVersion(appDir) {
+  const installed = join24(appDir, "node_modules", "deepspace", "package.json");
+  if (existsSync26(installed)) {
+    const parsed2 = JSON.parse(readFileSync28(installed, "utf8"));
+    if (typeof parsed2.version === "string") return parsed2.version;
+  }
+  const manifest = join24(appDir, "package.json");
+  if (!existsSync26(manifest)) return null;
+  const parsed = JSON.parse(readFileSync28(manifest, "utf8"));
+  return parsed.dependencies?.deepspace ?? null;
+}
+function pinSdkVersion(appDir, version) {
+  const path = join24(appDir, "package.json");
+  const source = readFileSync28(path, "utf8");
+  const updated = source.replace(
+    /("deepspace"\s*:\s*")[^"]+(")/,
+    (_match, head, tail) => `${head}^${version}${tail}`
   );
-  return result.inventory;
-}
-async function commitIdentityMigration(deployUrl, token, appId, input) {
-  const result = await apiFetch(
-    deployUrl,
-    token,
-    `/api/apps/${encodeURIComponent(appId)}/identity-migration/commit`,
-    { method: "POST", body: JSON.stringify(input) }
-  );
-  return result.migration;
+  if (updated === source) return false;
+  writeFileSync10(path, updated);
+  return true;
 }
-async function cancelIdentityMigration(deployUrl, token, appId) {
-  await apiFetch(
-    deployUrl,
-    token,
-    `/api/apps/${encodeURIComponent(appId)}/identity-migration`,
-    { method: "DELETE" }
+async function latestPublishedVersion() {
+  const response = await fetch(REGISTRY, { signal: AbortSignal.timeout(15e3) }).catch(
+    (error) => {
+      throw new Refusal(
+        `Could not reach the npm registry to find the latest version: ${error instanceof Error ? error.message : String(error)}. Pass --to <version> to update without a lookup.`,
+        "registry_unreachable"
+      );
+    }
   );
+  if (!response.ok) {
+    throw new Refusal(
+      `The npm registry answered ${response.status} for the latest deepspace version. Pass --to <version> to update without a lookup.`,
+      "registry_unreachable"
+    );
+  }
+  const body = await response.json();
+  if (typeof body.version !== "string") {
+    throw new Refusal("The npm registry returned no version for deepspace.", "registry_unreachable");
+  }
+  return body.version;
 }
-async function verifyIdentityMigration(deployUrl, token, appId) {
-  const result = await apiFetch(
-    deployUrl,
-    token,
-    `/api/apps/${encodeURIComponent(appId)}/identity-migration/verify`,
-    { method: "POST" }
-  );
-  return result.migration;
+function reportPlan(plan, applied) {
+  for (const migration of plan.pending) {
+    const verb = applied ? "Applied" : "Would apply";
+    p34.log.success(
+      `${verb}: ${migration.description} \u2014 ${migration.replacements} change(s) in ${migration.files.join(", ")}`
+    );
+  }
+  if (plan.blockers.length) {
+    p34.log.warn(
+      `${plan.blockers.length} change(s) could not be made for you \u2014 this file differs from the version the change was written against:`
+    );
+    for (const blocker of plan.blockers) {
+      p34.log.message(`  ${blocker.file}:${blocker.line}
+    ${blocker.message}`);
+    }
+  }
 }
-
-// src/cli/commands/migrate.ts
-var STRICT_APP_ID_RE2 = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
-var migrate_default = defineDeepspaceCommand({
+var update_default = defineDeepspaceCommand({
   meta: {
-    name: "migrate",
-    description: "Apply pending DeepSpace app migrations without moving retained data"
+    name: "update",
+    description: "Move this app onto the current SDK and apply the source changes it requires"
   },
   args: {
-    remote: {
+    to: {
       type: "string",
-      description: "GitHub remote name when it cannot be inferred (default: origin)",
-      required: false
-    },
-    env: {
-      type: "string",
-      alias: "e",
-      description: "wrangler.toml environment whose app id should be migrated",
+      description: "Target version (default: the latest published deepspace)",
       required: false
     },
     "dry-run": {
       type: "boolean",
-      description: "Inspect prerequisites and show the migration without changing anything",
-      default: false
-    },
-    cancel: {
-      type: "boolean",
-      description: "Cancel a prepared migration after restoring and publishing the legacy id",
+      description: "Report what would change without touching the checkout",
       default: false
     }
   },
   async run({ args }) {
-    const recoveryMode = args.cancel === true ? "cancel" : null;
-    const exclusiveModes = [args["dry-run"], args.cancel].filter(Boolean).length;
-    if (exclusiveModes > 1) {
-      throw new Refusal("Use only one of --dry-run or --cancel.", "conflicting_migration_mode");
-    }
-    const appDir = findAppDir();
-    if (!appDir) {
-      throw new Refusal("Run this command from a DeepSpace app Git checkout.", "not_in_app_repo");
-    }
-    assertSyncableRepo(appDir);
-    const envName = typeof args.env === "string" && args.env ? args.env : void 0;
-    const currentAppId = readAppId(appDir, envName) ?? readLegacyAppId(appDir, envName);
-    if (!currentAppId) {
+    const appDir = resolve19(".");
+    if (!hasWranglerConfig(appDir)) {
       throw new Refusal(
-        "wrangler.toml has no unambiguous DeepSpace app identity for this environment.",
-        "missing_app_id"
+        "No wrangler.toml found \u2014 run this from inside a DeepSpace app directory.",
+        "not_in_app_repo"
       );
     }
-    if (!STRICT_APP_ID_RE2.test(currentAppId)) requireTrackedWrangler(appDir);
-    const token = await ensureToken();
-    const deployUrl = deployBaseUrl();
-    const existingMigration = await getIdentityMigration(deployUrl, token, currentAppId);
-    if (recoveryMode) {
-      if (!existingMigration) {
-        if (!args.json) console.log("No reversible identity migration is recorded.");
-        return { data: { status: "no_migration", appId: currentAppId } };
-      }
-      return recoverMigration({
-        mode: recoveryMode,
-        appDir,
-        envName,
-        remoteName: typeof args.remote === "string" ? args.remote : void 0,
-        currentAppId,
-        token,
-        deployUrl,
-        migration: existingMigration,
-        json: args.json
-      });
-    }
-    const sourcePlan = planAppMigrations(appDir);
-    if (sourcePlan.blockers.length > 0) {
-      const first = sourcePlan.blockers[0];
+    assertSyncableRepo(appDir);
+    const currentRaw = readAppSdkVersion(appDir);
+    if (!currentRaw) {
       throw new Refusal(
-        `Migration ${first.migrationId} needs a manual source update at ${first.file}:${first.line}. ${first.message}`,
-        "source_migration_blocked",
-        { extra: { blockers: sourcePlan.blockers } }
+        "This app does not depend on `deepspace` \u2014 nothing to update.",
+        "not_in_app_repo"
       );
     }
-    if (STRICT_APP_ID_RE2.test(currentAppId)) {
-      if (!existingMigration) {
-        if (args["dry-run"] && sourcePlan.pending.length > 0) {
-          reportSourcePlan(sourcePlan, args.json);
-          return {
-            data: {
-              status: "ready",
-              appId: currentAppId,
-              sourceMigrations: sourcePlan.pending
-            }
-          };
-        }
-        if (sourcePlan.pending.length > 0) {
-          requireSourceMigrationWorktree(appDir);
-          applyAppMigrationPlan(appDir, sourcePlan);
-          throw sourceMigrationCommitRequired(appDir, sourcePlan);
-        }
-        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token, {
-          envName,
-          remoteName: typeof args.remote === "string" ? args.remote : void 0
-        });
-        reportUpToDate(currentAppId, args.json);
-        return { data: { status: "up_to_date", appId: currentAppId } };
-      }
-      if (sourcePlan.pending.length === 0 && existingMigration.status === "verified") {
-        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token, {
-          envName,
-          remoteName: typeof args.remote === "string" ? args.remote : void 0
-        });
-      }
-      if (args["dry-run"]) {
-        reportMigration(existingMigration, args.json);
-        reportSourcePlan(sourcePlan, args.json);
-        return {
-          data: {
-            status: existingMigration.status,
-            migration: existingMigration,
-            sourceMigrations: sourcePlan.pending
-          }
-        };
-      }
-      if (sourcePlan.pending.length > 0) {
-        requireSourceMigrationWorktree(appDir, existingMigration.status === "prepared");
-        applyAppMigrationPlan(appDir, sourcePlan);
-        throw existingMigration.status === "prepared" ? commitRequired(appDir, existingMigration, envName, sourcePlan.changedFiles) : sourceMigrationCommitRequired(appDir, sourcePlan);
-      }
-      return continuePreparedMigration({
-        appDir,
-        envName,
-        remoteName: typeof args.remote === "string" ? args.remote : void 0,
-        token,
-        deployUrl,
-        migration: existingMigration,
-        json: args.json
-      });
-    }
-    if (existingMigration && existingMigration.status !== "prepared" && existingMigration.status !== "rolled_back") {
+    const targetRaw = typeof args.to === "string" && args.to.trim() ? args.to.trim() : await latestPublishedVersion();
+    const current = parseVersion(currentRaw);
+    const target2 = parseVersion(targetRaw);
+    if (!current || !target2) {
       throw new Refusal(
-        `The registry already uses ${existingMigration.appId}, but wrangler.toml still uses ${currentAppId}. Restore the migration commit before deploying.`,
-        "migration_config_stale",
-        { extra: { migration: existingMigration } }
+        `Could not read a version to update from ("${currentRaw}") or to ("${targetRaw}").`,
+        "invalid_version"
       );
     }
-    const remote = requireGitHubRemote2(
-      appDir,
-      typeof args.remote === "string" ? args.remote : void 0
-    );
-    const head = requirePublishedHead2(appDir, remote);
-    const proposedAppId = existingMigration?.appId ?? mintAppId();
-    const inventory = await inspectIdentityMigration(deployUrl, token, currentAppId, {
-      destinationAppId: proposedAppId,
-      repository: remote.repository
-    });
-    if (!inventory.ready) {
+    if (gapIsTooWide(current, target2)) {
       throw new Refusal(
-        `Migration preflight is blocked: ${inventory.blockers.map((blocker) => blocker.message).join("; ")}`,
-        "migration_preflight_blocked",
-        { extra: { inventory } }
+        `This app is on deepspace ${currentRaw} and the current release is ${targetRaw}. That gap is too wide to migrate automatically \u2014 the changes between them are structural, not mechanical. Follow the upgrade guide instead: ${DOCS_URL}`,
+        "version_gap_too_wide",
+        { actionRequired: true, extra: { currentVersion: currentRaw, targetVersion: targetRaw } }
       );
     }
-    if (args["dry-run"]) {
-      if (!args.json) {
-        console.log(`Legacy app: ${currentAppId}`);
-        console.log(`GitHub: ${remote.repository} (${head.branch} @ ${head.oid.slice(0, 10)})`);
-        console.log(
-          `Immutable app id: ${proposedAppId}${existingMigration ? "" : " (not reserved)"}`
-        );
-        console.log(
-          `Registry rows to re-key: app=1 routes=${inventory.rekey.routes.length} collaborators=${inventory.rekey.collaborators.length} pendingInvites=${inventory.rekey.pendingCollaborators.length} transfers=${inventory.rekey.transfer ? 1 : 0}`
-        );
-        console.log(
-          `Physical stores retained at ${inventory.app.resourceId}: ${inventory.retainedPhysicalStores.map((store) => store.kind).join(", ")}`
-        );
-        console.log("No changes made.");
-      }
-      reportSourcePlan(sourcePlan, args.json);
-      return {
-        data: {
-          status: "ready",
-          legacyAppId: currentAppId,
-          proposedAppId,
-          resourceId: inventory.app.resourceId,
-          repository: remote.repository,
-          branch: head.branch,
-          commitOid: head.oid,
-          sourceClaimRequired: inventory.app.sourceClaimRequired,
-          sourceMigrations: sourcePlan.pending,
-          inventory
-        }
-      };
-    }
-    const migration = existingMigration?.status === "prepared" ? existingMigration : await prepareIdentityMigration(deployUrl, token, currentAppId, {
-      destinationAppId: proposedAppId,
-      repository: remote.repository,
-      expectedSourceRevision: inventory.app.sourceRevision
-    });
-    applyAppMigrationPlan(appDir, sourcePlan);
-    writeAppId(appDir, migration.appId, { wranglerEnv: envName, force: true });
-    throw commitRequired(appDir, migration, envName, sourcePlan.changedFiles);
-  }
-});
-async function recoverMigration(input) {
-  const { appDir, envName, remoteName, currentAppId, token, deployUrl, migration, json } = input;
-  if (migration.status === "rolled_back") {
-    if (currentAppId !== migration.legacyAppId) {
-      writeAppId(appDir, migration.legacyAppId, { wranglerEnv: envName, force: true });
-      throw restoreLegacyCommitRequired(appDir, migration, envName);
-    }
-    reportMigration(migration, json);
-    return { data: { status: "rolled_back", migration } };
-  }
-  if (migration.status !== "prepared") {
-    throw new Refusal(
-      "This migration is already committed. Complete it by deploying the canonical app.",
-      "forward_recovery_required",
-      { extra: { migration } }
-    );
-  }
-  if (currentAppId !== migration.legacyAppId) {
-    writeAppId(appDir, migration.legacyAppId, { wranglerEnv: envName, force: true });
-    throw restoreLegacyCommitRequired(appDir, migration, envName);
-  }
-  const remote = requireGitHubRemote2(appDir, remoteName, migration.repository);
-  requirePublishedHead2(appDir, remote);
-  await cancelIdentityMigration(deployUrl, token, migration.legacyAppId);
-  if (!json) console.log(`Canceled ${migration.legacyAppId} \u2192 ${migration.appId}.`);
-  return { data: { status: "cancelled", legacyAppId: migration.legacyAppId } };
-}
-async function continuePreparedMigration(input) {
-  const { appDir, envName, remoteName, token, deployUrl, migration, json } = input;
-  if (migration.status === "rolled_back") {
-    throw new Refusal(
-      `This migration was rolled back. Restore DEEPSPACE_APP_ID to ${migration.legacyAppId} before continuing.`,
-      "migration_rolled_back"
-    );
-  }
-  if (migration.status === "verified") {
-    reportMigration(migration, json);
-    return { data: { status: "verified", migration } };
-  }
-  if (migration.status === "committed") {
-    await requireSourceMigrationDeploy(appDir, migration.appId, deployUrl, token, {
-      envName,
-      remoteName,
-      after: migration.committedAt ?? void 0
-    });
-    const verified = await verifyIdentityMigration(deployUrl, token, migration.appId);
-    reportMigration(verified, json);
-    return { data: { status: "verified", migration: verified } };
-  }
-  if (!isWorkTreeClean(appDir)) {
-    const wranglerPath = wranglerRepoPath(appDir);
-    if (statusFiles(repoToplevel(appDir)).includes(wranglerPath)) {
-      throw commitRequired(appDir, migration, envName);
-    }
-    throw new Refusal(
-      "Commit or discard unrelated working-tree changes before completing the migration.",
-      "dirty_worktree"
-    );
-  }
-  const remote = requireGitHubRemote2(appDir, remoteName, migration.repository);
-  const head = requireLocalHead2(appDir);
-  const remoteOid = remoteBranchOid(appDir, remote.name, head.branch);
-  if (remoteOid !== head.oid) {
-    throw new Refusal(
-      `GitHub ${remote.repository} does not have ${head.branch} at ${head.oid.slice(0, 10)}. Push the migration commit, then rerun.`,
-      "github_push_required",
-      {
-        actionRequired: true,
-        action: { cwd: appDir, argv: ["git", "push", remote.name, head.branch] },
-        extra: { appId: migration.appId, repository: remote.repository, ...head }
-      }
-    );
-  }
-  const committed = await commitIdentityMigration(deployUrl, token, migration.appId, {
-    commitOid: head.oid,
-    branch: head.branch
-  });
-  throw deployRequired(appDir, committed, envName);
-}
-function requireGitHubRemote2(appDir, remoteName, repository) {
-  const selected = selectGitHubRemote(appDir, { name: remoteName, repository });
-  if (selected) return selected;
-  throw new Refusal(
-    remoteName ? `Remote "${remoteName}" is not the expected GitHub repository.` : repository ? `No local GitHub remote points at ${repository}. Add one or pass --remote <name>.` : "No unambiguous GitHub remote was found. Add `origin` or pass --remote <name>.",
-    "github_remote_required"
-  );
-}
-function requireLocalHead2(appDir) {
-  const branch = currentBranch(appDir);
-  if (!branch) throw new Refusal("HEAD is detached; switch to a branch first.", "detached_head");
-  const oid = resolveCommit(appDir, "HEAD");
-  if (!oid) throw new Refusal("The repository has no commit to publish.", "no_commits");
-  return { branch, oid };
-}
-function requirePublishedHead2(appDir, remote) {
-  if (!isWorkTreeClean(appDir)) {
-    throw new Refusal(
-      "Commit or discard local changes before preparing migration.",
-      "dirty_worktree"
-    );
-  }
-  const head = requireLocalHead2(appDir);
-  if (remoteBranchOid(appDir, remote.name, head.branch) !== head.oid) {
-    throw new Refusal(
-      `GitHub ${remote.repository} does not have ${head.branch} at ${head.oid.slice(0, 10)}. Push it, then rerun.`,
-      "github_push_required",
-      {
-        actionRequired: true,
-        action: { cwd: appDir, argv: ["git", "push", remote.name, head.branch] },
-        extra: { repository: remote.repository, ...head }
+    const dryRun = args["dry-run"] === true;
+    const plan = planAppMigrations(appDir);
+    const pinned = dryRun ? false : pinSdkVersion(appDir, targetRaw);
+    if (!dryRun && plan.edits.length) applyAppMigrationPlan(appDir, plan);
+    if (!args.json) {
+      p34.log.info(`deepspace ${currentRaw} \u2192 ${targetRaw}`);
+      if (pinned) p34.log.success("package.json now asks for the current SDK");
+      if (!plan.pending.length && !plan.blockers.length) {
+        p34.log.success("No source changes required.");
       }
-    );
-  }
-  return head;
-}
-function commitRequired(appDir, migration, envName, additionalPaths = []) {
-  const wranglerPath = wranglerRepoPath(appDir);
-  const migrationPaths = [.../* @__PURE__ */ new Set([wranglerPath, ...additionalPaths])].sort();
-  return new Refusal(
-    `Prepared ${migration.legacyAppId} \u2192 ${migration.appId}. Commit the deterministic app migration changes, then rerun.`,
-    "migration_commit_required",
-    {
-      actionRequired: true,
-      action: {
-        cwd: repoToplevel(appDir),
-        argv: [
-          "git",
-          "commit",
-          "--only",
-          "--message",
-          `Migrate DeepSpace app identity to ${migration.appId}`,
-          "--",
-          ...migrationPaths
-        ]
-      },
-      extra: { migration, env: envName ?? null }
-    }
-  );
-}
-function sourceMigrationCommitRequired(appDir, plan) {
-  const migrationIds = plan.pending.map((migration) => migration.id);
-  return new Refusal(
-    `Applied ${migrationIds.join(", ")}. Commit the deterministic app migration changes, then rerun.`,
-    "migration_commit_required",
-    {
-      actionRequired: true,
-      action: {
-        cwd: repoToplevel(appDir),
-        argv: [
-          "git",
-          "commit",
-          "--only",
-          "--message",
-          "Apply DeepSpace app migrations",
-          "--",
-          ...plan.changedFiles
-        ]
-      },
-      extra: { sourceMigrations: plan.pending }
+      reportPlan(plan, !dryRun);
     }
-  );
-}
-async function requireSourceMigrationDeploy(appDir, appId, deployUrl, token, options = {}) {
-  const { release: release2 } = await repoApi(deployUrl, token, appId).latestRelease();
-  const deployedIds = releaseMigrationIds(release2?.config);
-  const pendingIds = APP_MIGRATION_DEFINITIONS.map(({ id }) => id).filter(
-    (id) => !deployedIds.has(id)
-  );
-  const releaseAfterCutover = options.after === void 0 || typeof release2?.createdAt === "string" && Number.isFinite(Date.parse(release2.createdAt)) && Date.parse(release2.createdAt) > Date.parse(options.after);
-  if (pendingIds.length === 0 && releaseAfterCutover) return;
-  const sourceState = await getAppSource(deployUrl, token, appId);
-  if (sourceState.source?.provider === "github") {
-    const remote = requireGitHubRemote2(appDir, options.remoteName, sourceState.source.repository);
-    requirePublishedHead2(appDir, remote);
-  }
-  throw new Refusal(
-    pendingIds.length > 0 ? `App migrations ${pendingIds.join(", ")} are not in the live release. Deploy them, then rerun.` : "The canonical app has not been deployed since its identity cutover. Deploy it, then rerun.",
-    "migration_deploy_required",
-    {
-      actionRequired: true,
-      action: {
-        cwd: appDir,
-        argv: ["deepspace", "deploy", ...options.envName ? ["--env", options.envName] : []]
-      },
-      extra: { appId, sourceMigrations: pendingIds, after: options.after ?? null }
-    }
-  );
-}
-function releaseMigrationIds(config) {
-  if (config === null || typeof config !== "object" || Array.isArray(config)) return /* @__PURE__ */ new Set();
-  const validation = validateAppMigrationIds(
-    config.appMigrations ?? []
-  );
-  return new Set(validation.valid ? validation.ids : []);
-}
-function requireSourceMigrationWorktree(appDir, allowDirtyWrangler = false) {
-  if (isWorkTreeClean(appDir)) return;
-  const changed = statusFiles(repoToplevel(appDir));
-  if (allowDirtyWrangler && changed.every((path) => path === wranglerRepoPath(appDir))) return;
-  throw new Refusal(
-    "Commit or discard unrelated working-tree changes before applying app migrations.",
-    "dirty_worktree"
-  );
-}
-function restoreLegacyCommitRequired(appDir, migration, envName) {
-  const wranglerPath = wranglerRepoPath(appDir);
-  return new Refusal(
-    `Restored ${migration.legacyAppId} in wrangler.toml. Commit and push this recovery change, then rerun.`,
-    "migration_restore_commit_required",
-    {
-      actionRequired: true,
-      action: {
-        cwd: repoToplevel(appDir),
-        argv: [
-          "git",
-          "commit",
-          "--only",
-          "--message",
-          `Restore DeepSpace app identity to ${migration.legacyAppId}`,
-          "--",
-          wranglerPath
-        ]
-      },
-      extra: { migration, env: envName ?? null }
+    if (plan.blockers.length) {
+      throw new Refusal(
+        `${plan.blockers.length} change(s) need a human or agent edit; each is listed above with its file, line, and the change required.`,
+        "manual_changes_required",
+        {
+          actionRequired: true,
+          extra: {
+            currentVersion: currentRaw,
+            targetVersion: targetRaw,
+            applied: plan.pending.map((migration) => migration.id),
+            blockers: plan.blockers
+          }
+        }
+      );
     }
-  );
-}
-function wranglerRepoPath(appDir) {
-  return `${gitLine(appDir, ["rev-parse", "--show-prefix"])}wrangler.toml`;
-}
-function requireTrackedWrangler(appDir) {
-  const path = wranglerRepoPath(appDir);
-  if (runGit(repoToplevel(appDir), ["ls-files", "--error-unmatch", "--", path], { allowFail: true }).status !== 0) {
-    throw new Refusal(
-      "Track, commit, and push wrangler.toml before migrating; GitHub must already contain the deployment configuration.",
-      "wrangler_not_tracked"
-    );
-  }
-}
-function deployRequired(appDir, migration, envName) {
-  return new Refusal(
-    `Identity cutover committed; deploy once to verify ${migration.appId} on the existing physical resources.`,
-    "migration_deploy_required",
-    {
-      actionRequired: true,
-      action: {
-        cwd: appDir,
-        argv: ["deepspace", "deploy", ...envName ? ["--env", envName] : []]
+    return {
+      data: {
+        currentVersion: currentRaw,
+        targetVersion: targetRaw,
+        pinned,
+        dryRun,
+        applied: plan.pending.map((migration) => ({
+          id: migration.id,
+          description: migration.description,
+          files: migration.files,
+          replacements: migration.replacements
+        }))
       },
-      extra: { migration, env: envName ?? null }
-    }
-  );
-}
-function reportUpToDate(appId, json) {
-  if (!json) console.log(`No pending DeepSpace app migrations for ${appId}.`);
-}
-function reportSourcePlan(plan, json) {
-  if (json || plan.pending.length === 0) return;
-  for (const migration of plan.pending) {
-    console.log(
-      `Pending source migration: ${migration.id} (${migration.files.length} file${migration.files.length === 1 ? "" : "s"})`
-    );
+      // The dependency is pinned but not installed: installing is the package
+      // manager's job, and guessing which one an app uses is how a CLI breaks
+      // a pnpm or bun project.
+      ...pinned ? { action: cliAction("npm", "install") } : {}
+    };
   }
-}
-function reportMigration(migration, json) {
-  if (json) return;
-  console.log(`Migration: ${migration.legacyAppId} \u2192 ${migration.appId}`);
-  console.log(`Status: ${migration.status}`);
-  console.log(`Physical resources: ${migration.resourceId}`);
-  console.log(`GitHub: ${migration.repository}`);
-}
+});
 
 // src/cli/cli.ts
 var __dirname = dirname10(fileURLToPath3(import.meta.url));
-var pkg = JSON.parse(readFileSync28(join24(__dirname, "..", "package.json"), "utf-8"));
-if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync26("/etc/ssl/certs/ca-certificates.crt")) {
+var pkg = JSON.parse(readFileSync29(join25(__dirname, "..", "package.json"), "utf-8"));
+if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync27("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }
 var create2 = defineCommand14({
@@ -13655,7 +13284,7 @@ var auth = defineCommand14({
 var app = defineCommand14({
   meta: {
     name: "app",
-    description: "The app itself: create, init, list, files, source, migrate, undeploy, transfer, collaborators, domain, usage"
+    description: "The app itself: create, init, list, files, source, update, undeploy, transfer, collaborators, domain, usage"
   },
   subCommands: {
     create: create2,
@@ -13668,7 +13297,7 @@ var app = defineCommand14({
     domain: domain_default,
     usage: usage_default,
     source: source_default,
-    migrate: migrate_default
+    update: update_default
   }
 });
 var devGroup = defineCommand14({