deepspace 0.9.1 → 0.9.3

package/dist/cli.js

@@ -3,7 +3,7 @@
 // src/cli/cli.ts
 import { defineCommand as defineCommand14, runMain, runCommand } from "citty";
 import { sync as spawnSync8 } from "cross-spawn";
-import { readFileSync as readFileSync26, existsSync as existsSync24 } from "fs";
+import { readFileSync as readFileSync26, existsSync as existsSync25 } from "fs";
 import { dirname as dirname10, join as join24 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
@@ -788,7 +788,6 @@ import { parse as parseToml } from "smol-toml";
 // src/server/utils/registry-client.ts
 var APP_ID_RE = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
 var STRICT_APP_ID_RE = APP_ID_RE;
-var LEGACY_APP_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 
 // src/cli/lib/app-identity.ts
 var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
@@ -817,7 +816,7 @@ function mintUlid(now = Date.now()) {
 function mintAppId(now = Date.now()) {
   return `app_${mintUlid(now)}`;
 }
-function readWranglerConfig(cwd) {
+function readWranglerIdentityConfig(cwd) {
   const wranglerPath = join3(resolve(cwd), "wrangler.toml");
   if (!existsSync3(wranglerPath)) return null;
   try {
@@ -830,46 +829,12 @@ function readWranglerConfig(cwd) {
   }
 }
 function readAppId(cwd = process.cwd(), wranglerEnv) {
-  const cfg = readWranglerConfig(cwd);
+  const cfg = readWranglerIdentityConfig(cwd);
   if (!cfg) return null;
   const vars = wranglerEnv ? cfg.env?.[wranglerEnv]?.vars : cfg.vars;
   const id = vars?.DEEPSPACE_APP_ID;
   return typeof id === "string" && APP_ID_RE.test(id) ? id : null;
 }
-function readLegacyAppId(cwd = process.cwd(), wranglerEnv) {
-  const cfg = readWranglerConfig(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"
-    );
-  }
-  const legacyAppId = appName;
-  if (!legacyAppId || !LEGACY_APP_ID_RE.test(legacyAppId) || APP_ID_RE.test(legacyAppId)) {
-    return null;
-  }
-  return legacyAppId;
-}
 function writeAppId(cwd, appId, opts = {}) {
   const wranglerPath = join3(resolve(cwd), "wrangler.toml");
   if (!existsSync3(wranglerPath)) {
@@ -1986,7 +1951,7 @@ function prepareWranglerEnvConfig(appDir, envName, opts = {}) {
   if (!opts.sharedDevVarsCache) return { wranglerEnv: envName, cleanup() {
   } };
   warnIfLegacyEnvDevVarsExists(appDir, envName, opts.warn);
-  const config = readWranglerConfig2(appDir);
+  const config = readWranglerConfig(appDir);
   const resolved = resolveAppNameForEnv(config, envName);
   if (!resolved.ok) throw new Error(resolved.reason);
   const flattened = flattenWranglerEnvConfig(config, envName);
@@ -2050,7 +2015,7 @@ var WranglerConfigError = class extends Error {
     this.name = "WranglerConfigError";
   }
 };
-function readWranglerConfig2(appDir) {
+function readWranglerConfig(appDir) {
   const path = join7(appDir, "wrangler.toml");
   const raw = readFileSync8(path, "utf-8");
   try {
@@ -2465,9 +2430,12 @@ function lintSchema(schema) {
   }
   if (schema.ownerField) {
     const col = schema.columns.find((c) => c.name === schema.ownerField);
-    if (col && !col.userBound) {
+    const spoofableRoles = Object.entries(schema.permissions).filter(
+      ([role, permissions]) => role !== "owner" && role !== "admin" && permissions.create === true
+    ).map(([role]) => role);
+    if (col && !col.userBound && spoofableRoles.length > 0) {
       warnings.push(
-        `[${schema.name}] ownerField is '${schema.ownerField}' but that column is not marked userBound: true. A client can create a row with someone else's id in this field, bypassing 'own' permission checks. Add userBound: true (and ideally immutable: true) to the column.`
+        `[${schema.name}] ownerField is '${schema.ownerField}' but that column is not marked userBound: true. Client role(s) ${spoofableRoles.join(", ")} can create a row with someone else's id in this field, bypassing 'own' permission checks. Add userBound: true (and ideally immutable: true) to the column.`
       );
     }
   }
@@ -3594,8 +3562,298 @@ import { resolve as resolve12 } from "path";
 // src/cli/commands/deploy/build.ts
 import * as p6 from "@clack/prompts";
 import { execSync as execSync2 } from "child_process";
-import { existsSync as existsSync13, readFileSync as readFileSync14, readdirSync as readdirSync4 } from "fs";
-import { dirname as dirname5, join as join14, resolve as resolve10 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync15, readdirSync as readdirSync4 } from "fs";
+import { dirname as dirname5, join as join15, resolve as resolve10 } from "path";
+
+// src/cli/commands/migrate/app-migrations.ts
+import {
+  closeSync,
+  constants,
+  existsSync as existsSync13,
+  fstatSync,
+  ftruncateSync,
+  lstatSync,
+  openSync,
+  readFileSync as readFileSync14,
+  writeSync
+} from "fs";
+import { join as join14 } 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";
+function validateAppMigrationIds(value) {
+  if (!Array.isArray(value)) {
+    return { valid: false, reason: "app migrations must be a JSON string array" };
+  }
+  if (value.length > MAX_APP_MIGRATION_IDS) {
+    return {
+      valid: false,
+      reason: `app migrations cannot contain more than ${MAX_APP_MIGRATION_IDS} entries`
+    };
+  }
+  const ids = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const valueId of value) {
+    if (typeof valueId !== "string" || !APP_MIGRATION_ID_RE.test(valueId)) {
+      return { valid: false, reason: `invalid app migration id: ${String(valueId)}` };
+    }
+    if (seen.has(valueId)) {
+      return { valid: false, reason: `duplicate app migration id: ${valueId}` };
+    }
+    seen.add(valueId);
+    ids.push(valueId);
+  }
+  return { valid: true, ids };
+}
+
+// src/cli/commands/migrate/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
+  }
+];
+var APP_MIGRATION_DEFINITIONS = SOURCE_MIGRATIONS.map(
+  ({ id, description }) => ({ id, description })
+);
+function readAppliedAppMigrations(appDir) {
+  const path = join14(appDir, APP_MIGRATIONS_MANIFEST);
+  if (!existsSync13(path)) return [];
+  const source = readRegularFile(path);
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    throw new Error(`${APP_MIGRATIONS_MANIFEST} must contain valid JSON`);
+  }
+  const validation = validateAppMigrationIds(parsed);
+  if (!validation.valid) {
+    throw new Error(`${APP_MIGRATIONS_MANIFEST}: ${validation.reason}`);
+  }
+  return validation.ids;
+}
+function planAppMigrations(appDir) {
+  const repo = repoToplevel(appDir);
+  const appPrefix = gitLine(appDir, ["rev-parse", "--show-prefix"]);
+  const appliedIds = readAppliedAppMigrations(appDir);
+  const applied = new Set(appliedIds);
+  const pendingMigrations = SOURCE_MIGRATIONS.filter((migration) => !applied.has(migration.id));
+  const tracked = splitNulFields(runGit(repo, ["ls-files", "-z"]).stdout);
+  const perMigration = /* @__PURE__ */ new Map();
+  const blockers = [];
+  const edits = [];
+  for (const repoPath of tracked) {
+    if (!isSourcePath(repoPath, appPrefix)) continue;
+    const absolutePath = join14(repo, repoPath);
+    let stat;
+    try {
+      stat = lstatSync(absolutePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    const before = readRegularFile(absolutePath);
+    let after = before;
+    for (const migration of pendingMigrations) {
+      const result = migration.transform(after);
+      after = result.source;
+      if (result.replacements > 0) {
+        const planned = perMigration.get(migration.id) ?? {
+          id: migration.id,
+          description: migration.description,
+          files: [],
+          replacements: 0
+        };
+        planned.files.push(repoPath);
+        planned.replacements += result.replacements;
+        perMigration.set(migration.id, planned);
+      }
+      blockers.push(...migration.findBlockers(after, repoPath));
+    }
+    if (after !== before) edits.push({ path: repoPath, before, after });
+  }
+  const pending = pendingMigrations.map((migration) => {
+    const planned = perMigration.get(migration.id);
+    return planned ? { ...planned, files: [...new Set(planned.files)].sort() } : { id: migration.id, description: migration.description, files: [], replacements: 0 };
+  });
+  if (pending.length > 0 && blockers.length === 0) {
+    const manifestPath = `${appPrefix}${APP_MIGRATIONS_MANIFEST}`;
+    const absoluteManifestPath = join14(repo, manifestPath);
+    const before = existsSync13(absoluteManifestPath) ? readRegularFile(absoluteManifestPath) : null;
+    const after = `${JSON.stringify([...appliedIds, ...pending.map(({ id }) => id)], null, 2)}
+`;
+    if (before !== after) edits.push({ path: manifestPath, before, after });
+  }
+  return {
+    pending,
+    changedFiles: edits.map((edit) => edit.path).sort(),
+    blockers,
+    edits
+  };
+}
+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 = join14(repo, edit.path);
+    const current = existsSync13(absolutePath) ? readRegularFile(absolutePath) : null;
+    if (current !== edit.before) {
+      throw new Error(`Migration input changed after planning: ${edit.path}`);
+    }
+  }
+  for (const edit of plan.edits) writeRegularFile(join14(repo, edit.path), edit.before, edit.after);
+}
+function readRegularFile(path) {
+  const before = lstatSync(path);
+  if (!before.isFile() || before.isSymbolicLink()) {
+    throw new Error(`Migration input must be a regular file, not a symlink: ${path}`);
+  }
+  const fd = openSync(path, constants.O_RDONLY);
+  try {
+    const opened = fstatSync(fd);
+    const after = lstatSync(path);
+    if (!opened.isFile() || opened.dev !== after.dev || opened.ino !== after.ino) {
+      throw new Error(`Migration input changed while opening: ${path}`);
+    }
+    return readFileSync14(fd, "utf-8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function writeRegularFile(path, before, after) {
+  if (before === null) {
+    const fd2 = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 420);
+    try {
+      writeSync(fd2, after, 0, "utf-8");
+    } finally {
+      closeSync(fd2);
+    }
+    return;
+  }
+  const pathStat = lstatSync(path);
+  if (!pathStat.isFile() || pathStat.isSymbolicLink()) {
+    throw new Error(`Migration input must be a regular file, not a symlink: ${path}`);
+  }
+  const fd = openSync(path, constants.O_RDWR);
+  try {
+    const opened = fstatSync(fd);
+    const currentPath = lstatSync(path);
+    if (!opened.isFile() || opened.dev !== currentPath.dev || opened.ino !== currentPath.ino) {
+      throw new Error(`Migration input changed while opening: ${path}`);
+    }
+    if (readFileSync14(fd, "utf-8") !== before) {
+      throw new Error(`Migration input changed after planning: ${path}`);
+    }
+    ftruncateSync(fd, 0);
+    writeSync(fd, after, 0, "utf-8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function isSourcePath(repoPath, appPrefix) {
+  if (appPrefix && !repoPath.startsWith(appPrefix)) return false;
+  return /\.(?:[cm]?[jt]sx?)$/.test(repoPath);
+}
+function migrateCanonicalIdentityWire(source) {
+  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="
+    );
+  }
+  migrated = migrated.replaceAll(
+    "APP_IDENTITY_TOKEN + APP_NAME",
+    "APP_IDENTITY_TOKEN + DEEPSPACE_APP_ID"
+  );
+  return {
+    source: ensureCanonicalIdentityProperties(migrated),
+    replacements
+  };
+}
+function ensureCanonicalIdentityProperties(source) {
+  const lines = source.split("\n");
+  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}`);
+  }
+  return lines.join("\n");
+}
+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;
+}
+function findLegacyIdentityWireBlockers(source, file) {
+  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;
+    }
+    blockers.push({
+      migrationId: CANONICAL_APP_IDENTITY_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."
+    });
+  }
+  return blockers;
+}
+
+// src/cli/commands/deploy/build.ts
 var RESERVED_RUN_WORKER_FIRST = /* @__PURE__ */ new Set([
   "/api/*",
   "/ws/*",
@@ -3631,19 +3889,19 @@ async function buildDeployBundle(options) {
     preparedWranglerConfig?.cleanup();
   }
   spinner2.stop("Built");
-  const deployConfigPath = join14(appDir, ".wrangler", "deploy", "config.json");
-  if (!existsSync13(deployConfigPath)) {
+  const deployConfigPath = join15(appDir, ".wrangler", "deploy", "config.json");
+  if (!existsSync14(deployConfigPath)) {
     output.die(
       "Build output config not found at .wrangler/deploy/config.json",
       "build_output_missing"
     );
   }
-  const deployConfig = JSON.parse(readFileSync14(deployConfigPath, "utf-8"));
+  const deployConfig = JSON.parse(readFileSync15(deployConfigPath, "utf-8"));
   const outputWranglerPath = resolve10(dirname5(deployConfigPath), deployConfig.configPath);
-  if (!existsSync13(outputWranglerPath)) {
+  if (!existsSync14(outputWranglerPath)) {
     output.die(`Output wrangler.json not found at ${outputWranglerPath}`, "build_output_missing");
   }
-  const outputConfig = JSON.parse(readFileSync14(outputWranglerPath, "utf-8"));
+  const outputConfig = JSON.parse(readFileSync15(outputWranglerPath, "utf-8"));
   if (outputConfig.name && outputConfig.name !== appName) {
     const envHint = envName ? ` (--env ${envName})` : "";
     output.die(
@@ -3652,18 +3910,18 @@ async function buildDeployBundle(options) {
     );
   }
   const workerDir = dirname5(outputWranglerPath);
-  const workerBundlePath = join14(workerDir, outputConfig.main);
+  const workerBundlePath = join15(workerDir, outputConfig.main);
   const clientDir = outputConfig.assets?.directory ? resolve10(workerDir, outputConfig.assets.directory) : null;
-  if (!existsSync13(workerBundlePath)) {
+  if (!existsSync14(workerBundlePath)) {
     output.die(`Worker bundle not found at ${workerBundlePath}`, "build_output_missing");
   }
-  if (!clientDir || !existsSync13(clientDir)) {
+  if (!clientDir || !existsSync14(clientDir)) {
     return output.die(`Client assets not found at ${clientDir}`, "build_output_missing");
   }
   spinner2.start("Collecting assets...");
   const assets = collectAssets(clientDir);
   spinner2.stop(`Collected ${assets.length} assets`);
-  const workerJs = readFileSync14(workerBundlePath, "utf-8");
+  const workerJs = readFileSync15(workerBundlePath, "utf-8");
   const doBindings = outputConfig.durable_objects?.bindings;
   const sqliteClasses = new Set(
     outputConfig.migrations?.flatMap((migration) => migration.new_sqlite_classes ?? []) ?? []
@@ -3689,9 +3947,16 @@ async function buildDeployBundle(options) {
     );
   }
   const extraRoutes = extractRunWorkerFirst(wranglerConfig);
+  let appMigrations = [];
+  try {
+    appMigrations = readAppliedAppMigrations(appDir);
+  } catch (error) {
+    output.die(errorMessage(error), "invalid_migration_manifest");
+  }
   return {
     assets,
     workerJs,
+    appMigrations,
     doManifest,
     customBindings,
     extraRoutes
@@ -3716,14 +3981,14 @@ function collectAssets(dir) {
   const walk = (currentDir, prefix) => {
     for (const entry of readdirSync4(currentDir, { withFileTypes: true })) {
       if (entry.name === ".assetsignore") continue;
-      const fullPath = join14(currentDir, entry.name);
+      const fullPath = join15(currentDir, entry.name);
       const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
         walk(fullPath, relativePath);
       } else {
         assets.push({
           path: `/${relativePath}`,
-          contentBase64: readFileSync14(fullPath).toString("base64")
+          contentBase64: readFileSync15(fullPath).toString("base64")
         });
       }
     }
@@ -3737,18 +4002,18 @@ function errorMessage(error) {
 
 // src/cli/commands/deploy/commerce.ts
 import * as p7 from "@clack/prompts";
-import { existsSync as existsSync14 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync15 } from "fs";
+import { join as join16 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 var API_URL2 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function loadDeclaration(appDir, sourceFile, outputFile, exportName) {
-  const sourcePath = join15(appDir, "src", sourceFile);
-  if (!existsSync14(sourcePath)) return void 0;
+  const sourcePath = join16(appDir, "src", sourceFile);
+  if (!existsSync15(sourcePath)) return void 0;
   const esbuild = await import("esbuild");
-  const outputPath = join15(appDir, ".wrangler", "deploy", outputFile);
+  const outputPath = join16(appDir, ".wrangler", "deploy", outputFile);
   await esbuild.build({
     entryPoints: [sourcePath],
     bundle: true,
@@ -3841,7 +4106,7 @@ Stripe will keep charging them until you cancel. Cancel at the end of their curr
   }
 }
 async function syncSubscriptionPlans(appDir, appName, token, nonInteractive) {
-  if (!existsSync14(join15(appDir, "src", "subscriptions.ts"))) return;
+  if (!existsSync15(join16(appDir, "src", "subscriptions.ts"))) return;
   let plans;
   try {
     plans = await loadDeclaration(
@@ -3896,7 +4161,7 @@ async function syncSubscriptionPlans(appDir, appName, token, nonInteractive) {
   }
 }
 async function syncOneTimeProducts(appDir, appName, token) {
-  if (!existsSync14(join15(appDir, "src", "products.ts"))) return;
+  if (!existsSync15(join16(appDir, "src", "products.ts"))) return;
   let products;
   try {
     products = await loadDeclaration(
@@ -4188,7 +4453,7 @@ function repoApi(deployUrl, token, appId) {
 }
 
 // src/cli/lib/vc-remote.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { tmpdir } from "os";
 import { isAbsolute as isAbsolute3, relative, resolve as resolve11 } from "path";
 var SPACE_REMOTE = "space";
@@ -4229,7 +4494,7 @@ function entryIsTransient(cwd) {
 }
 function helperEntryUsable(command) {
   const match = /^!'([^']*)' '([^']*)' git-credential$/.exec(command);
-  return match !== null && existsSync15(match[1]) && existsSync15(match[2]);
+  return match !== null && existsSync16(match[1]) && existsSync16(match[2]);
 }
 function credentialHelperCommand() {
   const entry = process.argv[1];
@@ -4347,7 +4612,7 @@ function classifyPushTransportFailure(error) {
   if (/(?:HTTP |error: )422\b/i.test(message)) {
     return {
       code: "source_managed_by_github",
-      error: "This app uses GitHub source. Push with normal Git/GitHub, then run `deepspace deploy`."
+      error: "This app uses GitHub source. Manage commits with normal Git/GitHub; `deepspace deploy` ships the local working tree without changing Git."
     };
   }
   if (/(?:HTTP |error: )429\b/i.test(message)) {
@@ -4527,7 +4792,10 @@ async function syncDeployRepository(options) {
   let source = sourceState.source;
   let sourceRevision = sourceState.revision;
   const baseReleaseId = null;
-  if (!push && source?.provider !== "github") {
+  if (source?.provider === "github") {
+    return { commitOid, recoverable, deployKey, source, sourceRevision, baseReleaseId };
+  }
+  if (!push) {
     try {
       assertSyncableRepo(appDir);
       commitOid = resolveCommit(appDir, "HEAD");
@@ -4537,23 +4805,6 @@ async function syncDeployRepository(options) {
   }
   try {
     assertSyncableRepo(appDir);
-    if (source?.provider === "github") {
-      const github = syncGitHubDeploy({
-        deployUrl,
-        appDir,
-        appId,
-        token,
-        source,
-        ignoreStale,
-        output
-      });
-      return await github.then((result) => ({
-        ...result,
-        deployKey,
-        source,
-        sourceRevision
-      }));
-    }
     if (!source && listGitHubRemotes(appDir).length > 0) {
       output.die(
         "This app has a GitHub remote but no claimed source. Choose once with `deepspace app source github` (manual GitHub ownership) or `deepspace app source deepspace` (packaged DeepSpace source), then deploy again.",
@@ -4662,71 +4913,6 @@ async function syncDeployRepository(options) {
   }
   return { commitOid, recoverable, deployKey, source, sourceRevision, baseReleaseId };
 }
-async function syncGitHubDeploy(options) {
-  const { deployUrl, appDir, appId, token, source, ignoreStale, output } = options;
-  if (!isWorkTreeClean(appDir)) {
-    const refusal = dirtyWorktreeRefusal(currentBranch(appDir));
-    output.die(refusal.error, refusal.code);
-  }
-  const branch = currentBranch(appDir);
-  if (!branch) {
-    const refusal = detachedHeadRefusal();
-    output.die(refusal.error, refusal.code);
-    throw new Error(refusal.error);
-  }
-  const tip = resolveCommit(appDir, "HEAD");
-  if (!tip) {
-    output.die("The repository has no commit to deploy.", "no_commits");
-    throw new Error("The repository has no commit to deploy.");
-  }
-  const remote = selectGitHubRemote(appDir, { repository: source.repository });
-  if (!remote) {
-    output.die(
-      `No local GitHub remote points at ${source.repository}. Add one, then deploy again.`,
-      "github_remote_required"
-    );
-    throw new Error(`No local GitHub remote points at ${source.repository}.`);
-  }
-  const secretFiles = trackedSecretFiles(appDir, tip);
-  if (secretFiles.length > 0) {
-    output.die(
-      `Refusing to deploy a GitHub commit that tracks secret file(s): ${secretFiles.join(", ")}. Remove them from Git history, push the repaired branch, then deploy.`,
-      "secret_in_history"
-    );
-  }
-  if (remoteBranchOid(appDir, remote.name, branch) !== tip) {
-    output.die(
-      `GitHub ${source.repository} does not have ${branch} at ${tip.slice(0, 10)}. DeepSpace never pushes GitHub source; publish it manually, then deploy again.`,
-      "github_push_required",
-      {
-        actionRequired: true,
-        action: { cwd: appDir, argv: ["git", "push", remote.name, branch] }
-      }
-    );
-  }
-  const latest = await repoApi(deployUrl, token, appId).latestRelease().then((result) => result.release);
-  if (latest?.commitOid && latest.commitOid !== tip) {
-    const known = resolveCommit(appDir, latest.commitOid) !== null;
-    const containsLive = known && isAncestor(appDir, latest.commitOid, tip);
-    if ((!known || !containsLive) && !ignoreStale) {
-      output.die(
-        known ? `This GitHub branch does not contain live release #${latest.seq} (${latest.commitOid.slice(0, 10)}). Integrate the published GitHub history, then redeploy.` : `The live release commit ${latest.commitOid.slice(0, 10)} is not in this checkout. Fetch ${source.repository}, integrate it, then redeploy.`,
-        "stale_base",
-        {
-          actionRequired: true,
-          action: { cwd: appDir, argv: ["git", "fetch", remote.name] }
-        }
-      );
-    }
-    if (!containsLive) {
-      p9.log.warn(
-        "Deploying GitHub history that does not contain the live release (--ignore-stale)."
-      );
-    }
-  }
-  p9.log.info(`Verified GitHub ${source.repository}:${branch} at ${tip.slice(0, 10)} (no push).`);
-  return { commitOid: tip, recoverable: true, baseReleaseId: latest?.id ?? null };
-}
 function classifyRemoteState(appDir, token, branch, localTip) {
   let remoteTip = null;
   try {
@@ -4882,6 +5068,7 @@ async function deployBuiltBundle(options) {
     );
     form.append("uploadId", uploadId);
     form.append("totalGroups", String(totalGroups));
+    form.append("appMigrations", JSON.stringify(bundle.appMigrations));
     if (bundle.doManifest) form.append("doManifest", JSON.stringify(bundle.doManifest));
     if (bundle.customBindings.length) {
       form.append("bindingManifest", JSON.stringify(bundle.customBindings));
@@ -5047,7 +5234,7 @@ async function postWithRetry(url, makeInit, {
 
 // src/cli/commands/deploy/secrets.ts
 import * as p11 from "@clack/prompts";
-import { existsSync as existsSync16, readFileSync as readFileSync15 } from "fs";
+import { existsSync as existsSync17, readFileSync as readFileSync16 } from "fs";
 function classifyDevVarsSecrets(options) {
   const store = new Set(options.storeSecretNames);
   const strayKeys = options.handEditedDevVarKeys.filter((key) => !store.has(key));
@@ -5141,21 +5328,61 @@ function prepareDeploySecrets(options) {
       );
     }
   }
-  if (names.length) p11.log.info(`App secrets: ${names.join(", ")}`);
-  return { values, names };
-}
-function readCustomDevVars(path, output) {
-  if (!existsSync16(path)) return {};
-  const section = extractCustomDevVars(stripGeneratedSecretsCache(readFileSync15(path, "utf-8")));
-  if (!section) return {};
-  try {
-    return parseDevVars(section);
-  } catch (error) {
-    output.die(`.dev.vars: ${errorMessage5(error)}`, "invalid_dev_vars");
+  if (names.length) p11.log.info(`App secrets: ${names.join(", ")}`);
+  return { values, names };
+}
+function readCustomDevVars(path, output) {
+  if (!existsSync17(path)) return {};
+  const section = extractCustomDevVars(stripGeneratedSecretsCache(readFileSync16(path, "utf-8")));
+  if (!section) return {};
+  try {
+    return parseDevVars(section);
+  } catch (error) {
+    output.die(`.dev.vars: ${errorMessage5(error)}`, "invalid_dev_vars");
+  }
+}
+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 errorMessage5(error) {
-  return error instanceof Error ? error.message : String(error);
+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
@@ -5190,7 +5417,7 @@ var deploy_default = defineCommand3({
     // Citty maps --no-push to the negation of an argument named `push`.
     push: {
       type: "boolean",
-      description: "Sync DeepSpace source before deploying. The legacy --no-push escape hatch skips recoverable source lineage; GitHub apps are verified and never pushed automatically.",
+      description: "Sync DeepSpace source before deploying. GitHub source always deploys the local working tree without Git operations; --no-push opts DeepSpace source out of sync.",
       default: true
     },
     "ignore-stale": {
@@ -5224,7 +5451,7 @@ var deploy_default = defineCommand3({
     }
     p12.intro("Deploying DeepSpace app");
     output.showIntro();
-    const wranglerConfig = readWranglerConfig2(appDir);
+    const wranglerConfig = readWranglerConfig(appDir);
     const nameResult = resolveAppNameForEnv(wranglerConfig, envName);
     if (!nameResult.ok) return output.die(nameResult.reason, "invalid_app_name");
     const declaredName = envName ? wranglerConfig.env?.[envName]?.name : wranglerConfig.name;
@@ -5238,13 +5465,8 @@ var deploy_default = defineCommand3({
     const appName = nameResult.name;
     let appId = readAppId(appDir, envName);
     if (!appId) {
-      const legacyAppId = readLegacyAppId(appDir, envName);
-      if (legacyAppId) {
-        output.die(
-          `This checkout still uses legacy app identity ${legacyAppId}. Run \`deepspace app migrate --dry-run\`, then complete \`deepspace app migrate\` before deploying.`,
-          "legacy_app_migration_required"
-        );
-      }
+      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);
@@ -6026,20 +6248,20 @@ var usage_default = defineDeepspaceCommand({
 });
 
 // src/cli/commands/add.ts
-import { existsSync as existsSync18, readFileSync as readFileSync17, realpathSync as realpathSync3 } from "fs";
-import { dirname as dirname7, join as join17, resolve as resolve14 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync18, realpathSync as realpathSync3 } from "fs";
+import { dirname as dirname7, join as join18, resolve as resolve14 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/commands/feature-installer.ts
 import {
-  closeSync,
+  closeSync as closeSync2,
   copyFileSync,
-  existsSync as existsSync17,
-  fstatSync,
+  existsSync as existsSync18,
+  fstatSync as fstatSync2,
   mkdirSync as mkdirSync6,
   mkdtempSync,
-  openSync,
-  readFileSync as readFileSync16,
+  openSync as openSync2,
+  readFileSync as readFileSync17,
   readSync,
   readdirSync as readdirSync5,
   rmSync as rmSync4,
@@ -6047,16 +6269,16 @@ import {
 } from "fs";
 import { spawnSync as spawnSync6 } from "child_process";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname6, isAbsolute as isAbsolute4, join as join16, resolve as resolve13 } from "path";
+import { dirname as dirname6, isAbsolute as isAbsolute4, join as join17, resolve as resolve13 } from "path";
 import { fileURLToPath } from "url";
 var NAV_MARKER = "// \u2500\u2500 Features add nav items below this line \u2500\u2500";
 function featurePackageRoot(moduleUrl = import.meta.url) {
   let dir = dirname6(fileURLToPath(moduleUrl));
   for (; ; ) {
-    const packagePath = join16(dir, "package.json");
-    if (existsSync17(packagePath)) {
+    const packagePath = join17(dir, "package.json");
+    if (existsSync18(packagePath)) {
       try {
-        const pkg2 = JSON.parse(readFileSync16(packagePath, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync17(packagePath, "utf-8"));
         if (pkg2.name === "deepspace") return dir;
       } catch {
       }
@@ -6067,13 +6289,13 @@ function featurePackageRoot(moduleUrl = import.meta.url) {
   }
 }
 function hasFeatureCatalog(packageRoot = featurePackageRoot()) {
-  return existsSync17(join16(packageRoot, "features"));
+  return existsSync18(join17(packageRoot, "features"));
 }
 function readFeatureConfig(id, packageRoot = featurePackageRoot()) {
-  const configPath = join16(packageRoot, "features", id, "feature.json");
-  if (!existsSync17(configPath)) return null;
+  const configPath = join17(packageRoot, "features", id, "feature.json");
+  if (!existsSync18(configPath)) return null;
   try {
-    const config = JSON.parse(readFileSync16(configPath, "utf-8"));
+    const config = JSON.parse(readFileSync17(configPath, "utf-8"));
     if (typeof config.id !== "string" || typeof config.name !== "string" || !Array.isArray(config.files)) {
       return null;
     }
@@ -6083,8 +6305,8 @@ function readFeatureConfig(id, packageRoot = featurePackageRoot()) {
   }
 }
 function listFeatureConfigs(packageRoot = featurePackageRoot()) {
-  const featuresDir = join16(packageRoot, "features");
-  if (!existsSync17(featuresDir)) return [];
+  const featuresDir = join17(packageRoot, "features");
+  if (!existsSync18(featuresDir)) return [];
   return readdirSync5(featuresDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => readFeatureConfig(entry.name, packageRoot)).filter((config) => config !== null && !config.internal).sort((a, b) => a.id.localeCompare(b.id));
 }
 function featureCatalog(packageRoot = featurePackageRoot()) {
@@ -6138,7 +6360,7 @@ function copyFile(src, dest) {
 function copyFileWithImportShift(src, dest, levels) {
   mkdirSync6(dirname6(dest), { recursive: true });
   const prefix = "../".repeat(levels);
-  const shifted = readFileSync16(src, "utf-8").replace(
+  const shifted = readFileSync17(src, "utf-8").replace(
     /(from\s+|import\s+|import\()(['"])(\.\.\/)/g,
     `$1$2${prefix}$3`
   );
@@ -6151,12 +6373,12 @@ function installFiles(packageRoot, config, targetDir, emit) {
   const preexisting = [];
   const missing = [];
   for (const file of config.files) {
-    const srcPath = join16(packageRoot, "features", config.id, file.src);
+    const srcPath = join17(packageRoot, "features", config.id, file.src);
     const resolvedDest = resolveFeatureDestPath(file.dest, config.route);
-    const destPath = join16(targetDir, resolvedDest);
-    const existed = existsSync17(destPath);
+    const destPath = join17(targetDir, resolvedDest);
+    const existed = existsSync18(destPath);
     if (existed) preexisting.push(resolvedDest);
-    if (!existsSync17(srcPath)) {
+    if (!existsSync18(srcPath)) {
       emit(`   Warning: source not found: ${file.src}`, "stderr");
       if (!existed) missing.push(resolvedDest);
       continue;
@@ -6193,11 +6415,11 @@ function unresolvedSchema(schema, reason, emit) {
 }
 function integrateSchema(config, targetDir, emit) {
   if (!config.schema) return [];
-  const schemasPath = join16(targetDir, "src", "schemas.ts");
-  if (!existsSync17(schemasPath)) {
+  const schemasPath = join17(targetDir, "src", "schemas.ts");
+  if (!existsSync18(schemasPath)) {
     return [unresolvedSchema(config.schema, "src/schemas.ts was not found.", emit)];
   }
-  let content = readFileSync16(schemasPath, "utf-8");
+  let content = readFileSync17(schemasPath, "utf-8");
   const { exportName, importPath, spreadOperator } = config.schema;
   const importPattern = new RegExp(`^import\\s+\\{[^}]*\\b${exportName}\\b`, "m");
   if (importPattern.test(content)) {
@@ -6250,11 +6472,11 @@ function unresolvedActions(actions, reason, emit) {
 }
 function integrateActions(config, targetDir, emit) {
   if (!config.actions?.length) return [];
-  const actionsPath = join16(targetDir, "src", "actions", "index.ts");
-  if (!existsSync17(actionsPath)) {
+  const actionsPath = join17(targetDir, "src", "actions", "index.ts");
+  if (!existsSync18(actionsPath)) {
     return [unresolvedActions(config.actions, "src/actions/index.ts was not found.", emit)];
   }
-  let content = readFileSync16(actionsPath, "utf-8");
+  let content = readFileSync17(actionsPath, "utf-8");
   const registryPattern = /export const actions:\s*Record<string,\s*ActionHandler(?:<[^>]*>)?>\s*=\s*\{/;
   if (!registryPattern.test(content)) {
     const reason = "src/actions/index.ts has an unexpected structure.";
@@ -6299,8 +6521,8 @@ ${registryEntry}`);
 }
 function integrateCss(packageRoot, config, targetDir, emit) {
   if (!config.css?.length) return [];
-  const stylesPath = join16(targetDir, "src", "styles.css");
-  if (!existsSync17(stylesPath)) {
+  const stylesPath = join17(targetDir, "src", "styles.css");
+  if (!existsSync18(stylesPath)) {
     emit("   Warning: Cannot integrate CSS \u2014 src/styles.css not found");
     return [
       {
@@ -6312,12 +6534,12 @@ function integrateCss(packageRoot, config, targetDir, emit) {
       }
     ];
   }
-  let styles = readFileSync16(stylesPath, "utf-8");
+  let styles = readFileSync17(stylesPath, "utf-8");
   let integrated = 0;
   const unresolved = [];
   for (const cssFile of config.css) {
-    const srcPath = join16(packageRoot, "features", config.id, cssFile);
-    if (!existsSync17(srcPath)) {
+    const srcPath = join17(packageRoot, "features", config.id, cssFile);
+    if (!existsSync18(srcPath)) {
       emit(`   Warning: CSS source not found: ${cssFile}`, "stderr");
       unresolved.push({
         area: "css",
@@ -6326,7 +6548,7 @@ function integrateCss(packageRoot, config, targetDir, emit) {
       });
       continue;
     }
-    const css = readFileSync16(srcPath, "utf-8");
+    const css = readFileSync17(srcPath, "utf-8");
     const fingerprint = css.match(/\.([\w-]+)\s*\{|@keyframes\s+([\w-]+)/);
     const marker = fingerprint?.[1] ?? fingerprint?.[2];
     if (marker && styles.includes(marker)) {
@@ -6353,11 +6575,11 @@ function unresolvedRoute(route, config, reason, emit) {
 }
 function integrateRoute(config, targetDir, emit) {
   if (!config.route) return [];
-  const navPath = join16(targetDir, "src", "nav.ts");
-  if (!existsSync17(navPath)) {
+  const navPath = join17(targetDir, "src", "nav.ts");
+  if (!existsSync18(navPath)) {
     return [unresolvedRoute(config.route, config, "src/nav.ts was not found.", emit)];
   }
-  let content = readFileSync16(navPath, "utf-8");
+  let content = readFileSync17(navPath, "utf-8");
   const routePath = config.route.path;
   if (content.includes(`'${routePath}'`)) {
     emit(`   Nav already present: ${routePath}`);
@@ -6385,7 +6607,7 @@ ${entry}`);
 }
 var INSTALL_DIAGNOSTIC_BYTES = 16 * 1024;
 function readDiagnosticTail(outputFd) {
-  const size = fstatSync(outputFd).size;
+  const size = fstatSync2(outputFd).size;
   if (size === 0) return void 0;
   const length = Math.min(size, INSTALL_DIAGNOSTIC_BYTES);
   const buffer = Buffer.alloc(length);
@@ -6404,10 +6626,10 @@ function runPackageInstall(packageManager, targetDir, outputVisible) {
     const child = spawnSync6(packageManager, ["install"], { ...options, stdio: "inherit" });
     return { error: child.error, status: child.status };
   }
-  const captureDir = mkdtempSync(join16(tmpdir2(), "deepspace-add-install-"));
+  const captureDir = mkdtempSync(join17(tmpdir2(), "deepspace-add-install-"));
   let outputFd;
   try {
-    outputFd = openSync(join16(captureDir, "output.log"), "w+");
+    outputFd = openSync2(join17(captureDir, "output.log"), "w+");
     const child = spawnSync6(packageManager, ["install"], {
       ...options,
       stdio: ["ignore", outputFd, outputFd]
@@ -6418,7 +6640,7 @@ function runPackageInstall(packageManager, targetDir, outputVisible) {
       diagnosticTail: readDiagnosticTail(outputFd)
     };
   } finally {
-    if (outputFd !== void 0) closeSync(outputFd);
+    if (outputFd !== void 0) closeSync2(outputFd);
     rmSync4(captureDir, { recursive: true, force: true });
   }
 }
@@ -6431,14 +6653,14 @@ function integrateDependencies(config, targetDir, runInstall, outputVisible, emi
   if (declarations.every(({ values }) => !values || Object.keys(values).length === 0)) {
     return { added: [], installRan: false, packageManager };
   }
-  const packagePath = join16(targetDir, "package.json");
-  if (!existsSync17(packagePath)) {
+  const packagePath = join17(targetDir, "package.json");
+  if (!existsSync18(packagePath)) {
     emit("   Could not patch package.json (file not found)");
     return { added: [], installRan: false, packageManager };
   }
   let pkg2;
   try {
-    pkg2 = JSON.parse(readFileSync16(packagePath, "utf-8"));
+    pkg2 = JSON.parse(readFileSync17(packagePath, "utf-8"));
   } catch (error) {
     emit(
       `   Could not patch package.json (parse error: ${error instanceof Error ? error.message : String(error)})`
@@ -6498,7 +6720,7 @@ ${child.diagnosticTail}` : "";
 }
 function dependencySnapshot(targetDir) {
   try {
-    const pkg2 = JSON.parse(readFileSync16(join16(targetDir, "package.json"), "utf-8"));
+    const pkg2 = JSON.parse(readFileSync17(join17(targetDir, "package.json"), "utf-8"));
     return {
       dependencies: pkg2.dependencies ?? {},
       devDependencies: pkg2.devDependencies ?? {}
@@ -6510,7 +6732,7 @@ function dependencySnapshot(targetDir) {
 function installedNavFeatures(packageRoot, targetDir) {
   return listFeatureConfigs(packageRoot).filter((feature) => feature.category === "nav" && feature.files.length > 0).filter((feature) => {
     const signature = resolveFeatureDestPath(feature.files[0].dest, feature.route);
-    return existsSync17(join16(targetDir, signature));
+    return existsSync18(join17(targetDir, signature));
   }).map((feature) => feature.id);
 }
 function warnNavConflicts(packageRoot, config, targetDir, emit) {
@@ -6739,11 +6961,11 @@ function renderFeatureInfo(config) {
   return lines.join("\n");
 }
 function isDeepSpaceApp(dir) {
-  if (existsSync18(join17(dir, "wrangler.toml"))) return true;
-  const packagePath = join17(dir, "package.json");
-  if (!existsSync18(packagePath)) return false;
+  if (existsSync19(join18(dir, "wrangler.toml"))) return true;
+  const packagePath = join18(dir, "package.json");
+  if (!existsSync19(packagePath)) return false;
   try {
-    const pkg2 = JSON.parse(readFileSync17(packagePath, "utf-8"));
+    const pkg2 = JSON.parse(readFileSync18(packagePath, "utf-8"));
     return Boolean(pkg2.dependencies?.deepspace || pkg2.devDependencies?.deepspace);
   } catch {
     return false;
@@ -6752,8 +6974,8 @@ function isDeepSpaceApp(dir) {
 function installedPackageRoot(fromDir) {
   let dir = fromDir;
   for (; ; ) {
-    const candidate = join17(dir, "node_modules", "deepspace");
-    if (existsSync18(join17(candidate, "package.json"))) return candidate;
+    const candidate = join18(dir, "node_modules", "deepspace");
+    if (existsSync19(join18(candidate, "package.json"))) return candidate;
     const parent = dirname7(dir);
     if (parent === dir) return null;
     dir = parent;
@@ -6770,9 +6992,9 @@ async function targetInstaller(appDir) {
   if (realpathSync3(installedRoot) === realpathSync3(featurePackageRoot())) {
     return { installFeature };
   }
-  const entry = join17(installedRoot, "dist", "feature-installer.js");
-  const catalog = join17(installedRoot, "features");
-  if (!existsSync18(entry) || !existsSync18(catalog)) {
+  const entry = join18(installedRoot, "dist", "feature-installer.js");
+  const catalog = join18(installedRoot, "features");
+  if (!existsSync19(entry) || !existsSync19(catalog)) {
     throw new Refusal(
       `The app's installed deepspace package does not contain the typed feature installer.
 Expected: ${entry}
@@ -6865,7 +7087,7 @@ var add_default = defineDeepspaceCommand({
       return { data: { features: featureCatalog(root) } };
     }
     const appDir = resolve14(args.dir ?? ".");
-    if (!existsSync18(appDir)) {
+    if (!existsSync19(appDir)) {
       throw new Refusal(
         `Target directory not found: ${appDir}
 Create a new app first: deepspace app create <name>`,
@@ -7526,7 +7748,7 @@ var transfer_default = defineCommand7({
 import { defineCommand as defineCommand8 } from "citty";
 
 // src/cli/commands/_invoke-impl.ts
-import { readFileSync as readFileSync18 } from "fs";
+import { readFileSync as readFileSync19 } from "fs";
 import * as p15 from "@clack/prompts";
 var API_URL7 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -7567,7 +7789,7 @@ function resolveBody(opts) {
   if (opts.body != null) {
     raw = opts.body;
   } else if (opts.bodyFile != null) {
-    raw = opts.bodyFile === "-" ? readFileSync18(0, "utf-8") : readFileSync18(opts.bodyFile, "utf-8");
+    raw = opts.bodyFile === "-" ? readFileSync19(0, "utf-8") : readFileSync19(opts.bodyFile, "utf-8");
   } else {
     return "{}";
   }
@@ -7846,8 +8068,8 @@ var integrations_default = defineCommand8({
 
 // src/cli/commands/library.ts
 import { defineCommand as defineCommand9 } from "citty";
-import { existsSync as existsSync19, readFileSync as readFileSync19 } from "fs";
-import { join as join18, resolve as resolve15 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync20 } from "fs";
+import { join as join19, resolve as resolve15 } from "path";
 import { parse as parseToml4 } from "smol-toml";
 import * as p16 from "@clack/prompts";
 var DEFAULT_LIBRARY_APP = "deepdotspace-site";
@@ -7918,14 +8140,14 @@ var publish = defineDeepspaceCommand({
     let appName = str(args.app)?.trim();
     if (!appName) {
       const appDir = resolve15(str(args.dir) ?? ".");
-      const wranglerPath = join18(appDir, "wrangler.toml");
-      if (!existsSync19(wranglerPath)) {
+      const wranglerPath = join19(appDir, "wrangler.toml");
+      if (!existsSync20(wranglerPath)) {
         throw new Refusal(
           "No --app provided and no wrangler.toml found. Either pass --app <name> or run from your app's directory.",
           "not_in_app_repo"
         );
       }
-      const cfg = parseToml4(readFileSync19(wranglerPath, "utf-8"));
+      const cfg = parseToml4(readFileSync20(wranglerPath, "utf-8"));
       const nameRes = resolveAppName(cfg.name);
       if (!nameRes.ok) throw new Refusal(`wrangler.toml: ${nameRes.reason}`, "invalid_config");
       appName = nameRes.name;
@@ -8063,8 +8285,8 @@ var library_default = defineCommand9({
 
 // src/cli/commands/feedback.ts
 import * as p17 from "@clack/prompts";
-import { existsSync as existsSync20, readFileSync as readFileSync20 } from "fs";
-import { dirname as dirname8, join as join19 } from "path";
+import { existsSync as existsSync21, readFileSync as readFileSync21 } from "fs";
+import { dirname as dirname8, join as join20 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { release } from "os";
 var API_URL8 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
@@ -8087,12 +8309,12 @@ function readCliVersion() {
   try {
     const here = dirname8(fileURLToPath2(import.meta.url));
     const candidates = [
-      join19(here, "..", "package.json"),
-      join19(here, "..", "..", "..", "package.json")
+      join20(here, "..", "package.json"),
+      join20(here, "..", "..", "..", "package.json")
     ];
     for (const path of candidates) {
-      if (!existsSync20(path)) continue;
-      const pkg2 = JSON.parse(readFileSync20(path, "utf-8"));
+      if (!existsSync21(path)) continue;
+      const pkg2 = JSON.parse(readFileSync21(path, "utf-8"));
       if (pkg2.name === "deepspace" && pkg2.version) return pkg2.version;
     }
   } catch {
@@ -8103,7 +8325,7 @@ function detectAppName2() {
   try {
     const cwd = process.cwd();
     if (!hasWranglerConfig(cwd)) return void 0;
-    const config = readWranglerConfig2(cwd);
+    const config = readWranglerConfig(cwd);
     return typeof config.name === "string" ? config.name : void 0;
   } catch {
     return void 0;
@@ -8288,7 +8510,7 @@ Context: deepspace ${payload.cliVersion} \xB7 ${payload.nodeVersion} \xB7 ${payl
 
 // src/cli/commands/secrets.ts
 import { defineCommand as defineCommand10 } from "citty";
-import { readFileSync as readFileSync21 } from "fs";
+import { readFileSync as readFileSync22 } from "fs";
 
 // src/cli/lib/citty-args.ts
 function dedupePositionals(bound, rest) {
@@ -8558,7 +8780,7 @@ var upload = defineCommand10({
   async run({ args }) {
     try {
       const t = await resolveTarget(args);
-      const content = args.file === "-" ? readFileSync21(0, "utf-8") : readFileSync21(args.file, "utf-8");
+      const content = args.file === "-" ? readFileSync22(0, "utf-8") : readFileSync22(args.file, "utf-8");
       const secrets = parseSecretsUpload(content);
       if (Object.keys(secrets).length === 0)
         fail(new InputError("No secrets found in the input.", "empty_input"));
@@ -8814,7 +9036,7 @@ var init_default = defineDeepspaceCommand({
 // src/cli/commands/status.ts
 import { defineCommand as defineCommand11 } from "citty";
 import * as p18 from "@clack/prompts";
-import { existsSync as existsSync21, readFileSync as readFileSync22 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync23 } from "fs";
 function timeAgo(iso) {
   const ms = Date.now() - Date.parse(iso);
   if (!Number.isFinite(ms) || ms < 0) return iso;
@@ -8883,7 +9105,7 @@ var status_default = defineCommand11({
       json.services = urls;
       if (urlOverrides.length > 0) json.urlOverrides = urlOverrides;
     }
-    facts.loggedIn = existsSync21(SESSION_PATH);
+    facts.loggedIn = existsSync22(SESSION_PATH);
     let userId = null;
     if (!facts.loggedIn) {
       lines.push(["Session", "not logged in"]);
@@ -8892,7 +9114,7 @@ var status_default = defineCommand11({
       let who = "logged in";
       try {
         const payload = decodeJwtPayload(
-          readFileSync22(TOKEN_PATH, "utf-8").trim()
+          readFileSync23(TOKEN_PATH, "utf-8").trim()
         );
         if (payload.email) who = payload.email;
         userId = payload.sub ?? null;
@@ -9555,18 +9777,18 @@ var pull_default = defineDeepspaceCommand({
 
 // src/cli/commands/clone.ts
 import * as p21 from "@clack/prompts";
-import { existsSync as existsSync22, readdirSync as readdirSync6, rmSync as rmSync5 } from "fs";
-import { resolve as resolve16, basename as basename3, join as join20 } from "path";
+import { existsSync as existsSync23, readdirSync as readdirSync6, rmSync as rmSync5 } from "fs";
+import { resolve as resolve16, basename as basename3, join as join21 } from "path";
 function cleanFailedCloneDir(dir) {
   let entries;
   try {
     entries = readdirSync6(dir);
   } catch {
-    return existsSync22(dir) ? ["<unreadable>"] : [];
+    return existsSync23(dir) ? ["<unreadable>"] : [];
   }
   if (entries.length === 1 && entries[0] === ".git") {
     try {
-      rmSync5(join20(dir, ".git"), { recursive: true, force: true });
+      rmSync5(join21(dir, ".git"), { recursive: true, force: true });
       return [];
     } catch {
       return entries;
@@ -9575,7 +9797,7 @@ function cleanFailedCloneDir(dir) {
   return entries;
 }
 function validateCloneTarget(dir) {
-  if (!existsSync22(dir)) return false;
+  if (!existsSync23(dir)) return false;
   let entries;
   try {
     entries = readdirSync6(dir);
@@ -9989,8 +10211,8 @@ function printOverlaps(overlaps, json) {
 
 // src/cli/commands/workspace/local.ts
 import * as p25 from "@clack/prompts";
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync23, realpathSync as realpathSync5, renameSync as renameSync2, statSync, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname9, isAbsolute as isAbsolute5, join as join21, relative as relative2, sep as sep2 } from "path";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync24, realpathSync as realpathSync5, renameSync as renameSync2, statSync, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname9, isAbsolute as isAbsolute5, join as join22, relative as relative2, sep as sep2 } from "path";
 var WORKSPACE_MARKER = "deepspace-workspace.json";
 function excludeWorktreeDir(appDir, dir) {
   try {
@@ -10011,7 +10233,7 @@ function worktreeMarkerPath(worktreeRoot) {
     const result = runGit(worktreeRoot, ["rev-parse", "--absolute-git-dir"], { allowFail: true });
     if (result.status !== 0) return null;
     const gitDir = result.stdout.toString("utf-8").trim();
-    return isAbsolute5(gitDir) ? join21(gitDir, WORKSPACE_MARKER) : null;
+    return isAbsolute5(gitDir) ? join22(gitDir, WORKSPACE_MARKER) : null;
   } catch {
     return null;
   }
@@ -10047,7 +10269,7 @@ function isManagedWorkspaceWorktree(worktreeRoot, workspaceId) {
   const markerPath = worktreeMarkerPath(worktreeRoot);
   if (!markerPath) return false;
   try {
-    const marker = JSON.parse(readFileSync23(markerPath, "utf-8"));
+    const marker = JSON.parse(readFileSync24(markerPath, "utf-8"));
     return marker.version === 1 && marker.workspaceId === workspaceId && marker.mode === "managed-linked";
   } catch {
     return false;
@@ -10056,11 +10278,11 @@ function isManagedWorkspaceWorktree(worktreeRoot, workspaceId) {
 function defaultWorkspaceRoot(appDir, workspaceId) {
   const primary = listWorktrees(appDir)[0];
   if (!primary) throw new Error("Git did not report a primary worktree");
-  return join21(primary.path, ".deepspace", "ws", workspaceId.slice(3).toLowerCase());
+  return join22(primary.path, ".deepspace", "ws", workspaceId.slice(3).toLowerCase());
 }
 function appDirInWorktree(appDir, worktreeRoot) {
   const appRelative = relative2(realpathSync5(repoToplevel(appDir)), realpathSync5(appDir));
-  return appRelative ? join21(worktreeRoot, appRelative) : worktreeRoot;
+  return appRelative ? join22(worktreeRoot, appRelative) : worktreeRoot;
 }
 function materializeWorkspaceWorktree(appDir, worktreeRoot, branch, startPoint, workspaceId, options = {}) {
   const createdOid = resolveCommit(appDir, startPoint);
@@ -10078,11 +10300,41 @@ function materializeWorkspaceWorktree(appDir, worktreeRoot, branch, startPoint,
 function inOwnLinkedWorktree(appDir, id) {
   if (workspaceIdFromBranch(currentBranch(appDir)) !== id) return false;
   try {
-    return statSync(join21(repoToplevel(appDir), ".git")).isFile();
+    return statSync(join22(repoToplevel(appDir), ".git")).isFile();
   } catch {
     return false;
   }
 }
+function inspectWorkspaceCleanup(appDir, id) {
+  const branch = workspaceBranchName(id);
+  const branchOid = resolveCommit(appDir, `refs/heads/${branch}`);
+  const worktrees = listWorktrees(appDir);
+  const checkoutIndex = worktrees.findIndex((worktree) => worktree.branch === branch);
+  if (checkoutIndex < 0) {
+    return {
+      branch,
+      branchOid,
+      checkout: { kind: "none", dir: null },
+      willDeleteBranch: branchOid !== null
+    };
+  }
+  const dir = worktrees[checkoutIndex].path;
+  if (checkoutIndex === 0) {
+    return {
+      branch,
+      branchOid,
+      checkout: { kind: "primary", dir },
+      willDeleteBranch: branchOid !== null
+    };
+  }
+  const managed = isManagedWorkspaceWorktree(dir, id);
+  return {
+    branch,
+    branchOid,
+    checkout: { kind: managed ? "managed-linked" : "external-linked", dir },
+    willDeleteBranch: branchOid !== null && managed
+  };
+}
 function cleanupJson(outcome) {
   return {
     worktreeRemoved: outcome.worktreeRemoved,
@@ -10092,11 +10344,27 @@ function cleanupJson(outcome) {
     ...outcome.error ? { error: outcome.error } : {}
   };
 }
-function deleteWsBranch(cwd, branch, out) {
-  const del3 = runGit(cwd, ["branch", "-D", branch], { allowFail: true });
-  if (del3.status === 0) out.branchDeleted = branch;
-  else
-    out.error ??= `git branch -D ${branch} failed: ${del3.stderr.toString("utf-8").trim() || "unknown git error"}`;
+function deleteWsBranch(cwd, branch, expectedOid, out) {
+  const ref = `refs/heads/${branch}`;
+  const currentOid = resolveCommit(cwd, ref);
+  if (!currentOid) return;
+  const approvedOid = expectedOid ?? currentOid;
+  if (currentOid !== approvedOid) {
+    out.error ??= `branch ${branch} advanced from ${approvedOid.slice(0, 10)} to ${currentOid.slice(0, 10)} during cleanup; retained the branch`;
+    return;
+  }
+  const del3 = runGit(cwd, ["update-ref", "-d", ref, approvedOid], { allowFail: true });
+  if (del3.status === 0) {
+    out.branchDeleted = branch;
+    runGit(cwd, ["config", "--remove-section", `branch.${branch}`], { allowFail: true });
+    return;
+  }
+  const afterOid = resolveCommit(cwd, ref);
+  if (afterOid && afterOid !== approvedOid) {
+    out.error ??= `branch ${branch} advanced from ${approvedOid.slice(0, 10)} to ${afterOid.slice(0, 10)} during cleanup; retained the branch`;
+  } else if (afterOid) {
+    out.error ??= `could not delete branch ${branch}: ${del3.stderr.toString("utf-8").trim() || "unknown git error"}`;
+  }
 }
 function switchOffWsBranch(mainDir, trunkBranch) {
   if (trunkBranch) {
@@ -10110,8 +10378,10 @@ function switchOffWsBranch(mainDir, trunkBranch) {
   }
   return runGit(mainDir, ["switch", "--quiet", "--detach"], { allowFail: true }).status === 0;
 }
-function cleanupWorkspaceLocal(appDir, id, trunkBranch) {
-  const branch = workspaceBranchName(id);
+function cleanupWorkspaceLocal(appDir, id, trunkBranch, options = {}) {
+  const inspection = inspectWorkspaceCleanup(appDir, id);
+  const { branch } = inspection;
+  const expectedBranchOid = options.expectedBranchOid ?? inspection.branchOid;
   const out = {
     worktreeRemoved: null,
     worktreeRetained: null,
@@ -10119,6 +10389,10 @@ function cleanupWorkspaceLocal(appDir, id, trunkBranch) {
     worktreeDir: null,
     branch
   };
+  if (options.retainLocal) {
+    out.worktreeRetained = inspection.checkout.dir;
+    return out;
+  }
   try {
     const worktrees = listWorktrees(appDir);
     const mainDir = worktrees[0]?.path ?? repoToplevel(appDir);
@@ -10145,14 +10419,15 @@ function cleanupWorkspaceLocal(appDir, id, trunkBranch) {
         return out;
       }
       out.worktreeRemoved = linked.path;
-      deleteWsBranch(mainDir, branch, out);
+      out.worktreeDir = null;
+      deleteWsBranch(mainDir, branch, expectedBranchOid, out);
       return out;
     }
     if (currentBranch(mainDir) === branch && !switchOffWsBranch(mainDir, trunkBranch)) {
       out.error = `could not switch off ${branch} to delete it`;
       return out;
     }
-    if (resolveCommit(mainDir, `refs/heads/${branch}`)) deleteWsBranch(mainDir, branch, out);
+    deleteWsBranch(mainDir, branch, expectedBranchOid, out);
     return out;
   } catch (err) {
     out.error = err instanceof Error ? err.message : String(err);
@@ -10409,7 +10684,7 @@ var newWorkspaceCommand = defineDeepspaceCommand({
 
 // src/cli/commands/workspace/attach.ts
 import * as p27 from "@clack/prompts";
-import { existsSync as existsSync23, readdirSync as readdirSync7, rmSync as rmSync6 } from "fs";
+import { existsSync as existsSync24, readdirSync as readdirSync7, rmSync as rmSync6 } from "fs";
 import { isAbsolute as isAbsolute7, resolve as resolve18 } from "path";
 function finishedWorkspaceMessage(id, view) {
   const workspace = view.workspace;
@@ -10419,7 +10694,7 @@ function finishedWorkspaceMessage(id, view) {
   return `Workspace ${id} is ${workspace.status} \u2014 its ref is retained briefly (fetch ${workspace.ref} to inspect), but attach only works on active workspaces.`;
 }
 function cleanFailedFreshAttachDir(dir) {
-  if (!existsSync23(dir)) return [];
+  if (!existsSync24(dir)) return [];
   let entries;
   try {
     entries = readdirSync7(dir);
@@ -10537,7 +10812,7 @@ var attachWorkspaceCommand = defineDeepspaceCommand({
       process.cwd(),
       (typeof args.dir === "string" ? args.dir.trim() : "") || `ws-${id.slice(3).toLowerCase()}`
     );
-    if (existsSync23(dir)) {
+    if (existsSync24(dir)) {
       spinner2?.stop("Target exists.");
       throw new Refusal(`${dir} already exists \u2014 pass a different directory.`, "dir_exists");
     }
@@ -10854,13 +11129,13 @@ import * as p31 from "@clack/prompts";
 
 // src/cli/lib/validation.ts
 import { sync as spawnSync7 } from "cross-spawn";
-import { readFileSync as readFileSync24 } from "fs";
-import { join as join22 } from "path";
+import { readFileSync as readFileSync25 } from "fs";
+import { join as join23 } from "path";
 var MAX_SUMMARY_CHARS = 4e3;
 var MAX_OUTPUT_BUFFER = 64 * 1024 * 1024;
 function configuredCommand(appDir) {
   try {
-    const pkg2 = JSON.parse(readFileSync24(join22(appDir, "package.json"), "utf-8"));
+    const pkg2 = JSON.parse(readFileSync25(join23(appDir, "package.json"), "utf-8"));
     if (pkg2.scripts?.validate) return `${detectPackageManager(appDir)} run --silent validate`;
   } catch {
   }
@@ -11122,7 +11397,7 @@ var landWorkspaceCommand = defineDeepspaceCommand({
     }
     await api4.landWorkspace(id, { landedOid, intoRef });
     spinner2?.stop(`Landed ${id} into ${intoBranch} at ${landedOid.slice(0, 10)}.`);
-    const cleanup = keepWorktree ? null : cleanupWorkspaceLocal(appDir, id, intoBranch);
+    const cleanup = keepWorktree ? null : cleanupWorkspaceLocal(appDir, id, intoBranch, { expectedBranchOid: landedOid });
     const inOwnWorktree = !cleanup && inOwnLinkedWorktree(appDir, id);
     const retainedWorktree = cleanup?.worktreeRetained ?? (keepWorktree || inOwnWorktree ? appDir : null);
     const data = {
@@ -11159,6 +11434,24 @@ var landWorkspaceCommand = defineDeepspaceCommand({
 
 // src/cli/commands/workspace/drop.ts
 import * as p32 from "@clack/prompts";
+function isWorkspaceTipPublished(appDir, localTip, publishedOids) {
+  return publishedOids.some(
+    (publishedOid) => publishedOid === localTip || isAncestor(appDir, localTip, publishedOid)
+  );
+}
+function workspaceUnsyncedRefusal(args) {
+  const syncArgv = ["deepspace", "workspace", "sync", "--app", args.appId, "--workspace", args.id];
+  const dropArgv = ["deepspace", "workspace", "drop", args.id, "--app", args.appId];
+  const publish2 = args.workspaceDir ? `Publish them first with \`${humanCommand(syncArgv)}\`, then re-run \`${humanCommand(dropArgv)}\`.` : `Recreate a worktree from the branch (\`git worktree add <dir> ${args.branch}\`), publish from there with \`${humanCommand(syncArgv)}\`, then re-run \`${humanCommand(dropArgv)}\`.`;
+  return new Refusal(
+    `${args.id} has committed work that isn't published yet. ${publish2} Alternatively, pass \`--keep-worktree\` to drop the cloud workspace while retaining the local branch/worktree for manual disposal. Nothing was dropped.`,
+    "workspace_unsynced",
+    {
+      ...args.workspaceDir ? { action: { cwd: args.workspaceDir, argv: syncArgv } } : {},
+      extra: { workspaceId: args.id }
+    }
+  );
+}
 var dropWorkspaceCommand = defineDeepspaceCommand({
   meta: { name: "drop", description: "Abandon a workspace (ref retained briefly, then GC)" },
   args: {
@@ -11192,24 +11485,44 @@ var dropWorkspaceCommand = defineDeepspaceCommand({
       }
       return { data: { workspaceId: explicitId, status: view2.workspace.status } };
     }
-    const { appDir, api: api4 } = await resolveTarget2(appArg);
+    const { appDir, appId, api: api4 } = await resolveTarget2(appArg);
     const id = inferWorkspaceId(appDir, explicitId);
-    const ownLinkedWorktree = inOwnLinkedWorktree(appDir, id);
-    const cleanupOwnsCheckout = !ownLinkedWorktree || isManagedWorkspaceWorktree(appDir, id);
-    if (!keepWorktree && cleanupOwnsCheckout && !isWorkTreeClean(appDir)) {
-      const dropArgv = ["deepspace", "workspace", "drop", ...explicitId ? [explicitId] : []];
+    const inspection = inspectWorkspaceCleanup(appDir, id);
+    let approvedBranchOid;
+    if (!keepWorktree && inspection.willDeleteBranch && inspection.branchOid) {
+      const { view: before } = await api4.getWorkspace(id);
+      const publishedOids = [
+        before.tipOid,
+        before.workspace.landedOid,
+        before.workspace.baseOid
+      ].filter((oid) => oid !== null);
+      if (!isWorkspaceTipPublished(appDir, inspection.branchOid, publishedOids)) {
+        throw workspaceUnsyncedRefusal({
+          appId,
+          id,
+          branch: inspection.branch,
+          workspaceDir: inspection.checkout.dir
+        });
+      }
+      approvedBranchOid = inspection.branchOid;
+    }
+    const cleanupDir = inspection.willDeleteBranch ? inspection.checkout.dir : null;
+    if (!keepWorktree && cleanupDir && !isWorkTreeClean(cleanupDir)) {
+      const dropArgv = ["deepspace", "workspace", "drop", id, "--app", appId];
       const dropNext = humanCommand(dropArgv);
       throw new Refusal(
-        `The worktree has uncommitted changes and cleanup would remove it. Commit them to the workspace branch and re-run \`${dropNext}\`, or pass \`--keep-worktree\` to drop while keeping the worktree. Nothing was dropped.`,
+        `The workspace checkout has uncommitted changes and cleanup would remove it or switch it off ${inspection.branch}. Commit them and re-run \`${dropNext}\`, or pass \`--keep-worktree\` to drop while retaining the checkout. Nothing was dropped.`,
         "dirty_worktree",
         { extra: { workspaceId: id } }
       );
     }
     const { view } = await api4.dropWorkspace(id);
     spinner2?.message(`Cleaning up ${id} locally\u2026`);
-    const cleanup = keepWorktree ? null : cleanupWorkspaceLocal(appDir, id, null);
-    const inOwnWorktree = !cleanup && ownLinkedWorktree;
-    const retainedWorktree = cleanup?.worktreeRetained ?? (keepWorktree || inOwnWorktree ? appDir : null);
+    const cleanup = keepWorktree ? null : cleanupWorkspaceLocal(appDir, id, null, {
+      expectedBranchOid: approvedBranchOid,
+      retainLocal: !inspection.willDeleteBranch
+    });
+    const retainedWorktree = cleanup?.worktreeRetained ?? (keepWorktree ? inspection.checkout.dir : null);
     const data = {
       workspaceId: id,
       status: view.workspace.status,
@@ -11783,178 +12096,7 @@ function sameRefs(left, right) {
   return left.every((ref) => expected.get(ref.name) === ref.oid);
 }
 
-// src/cli/lib/app-migrations.ts
-import { lstatSync, readFileSync as readFileSync25, writeFileSync as writeFileSync10 } from "fs";
-import { join as join23 } from "path";
-var CANONICAL_IDENTITY_WIRE_ID = "2026-08-canonical-app-identity-wire";
-var SOURCE_MIGRATIONS = [
-  {
-    id: CANONICAL_IDENTITY_WIRE_ID,
-    description: "Use the immutable app id for authenticated platform requests",
-    transform: migrateCanonicalIdentityWire,
-    findBlockers: findLegacyIdentityWireBlockers
-  }
-];
-var APP_MIGRATION_DEFINITIONS = SOURCE_MIGRATIONS.map(
-  ({ id, description }) => ({ id, description })
-);
-function planAppMigrations(appDir) {
-  const repo = repoToplevel(appDir);
-  const appPrefix = gitLine(appDir, ["rev-parse", "--show-prefix"]);
-  const tracked = splitNulFields(runGit(repo, ["ls-files", "-z"]).stdout);
-  const perMigration = /* @__PURE__ */ new Map();
-  const blockers = [];
-  const edits = [];
-  for (const repoPath of tracked) {
-    if (!isSourcePath(repoPath, appPrefix)) continue;
-    const absolutePath = join23(repo, repoPath);
-    let stat;
-    try {
-      stat = lstatSync(absolutePath);
-    } catch {
-      continue;
-    }
-    if (!stat.isFile() || stat.isSymbolicLink()) continue;
-    const before = readFileSync25(absolutePath, "utf-8");
-    let after = before;
-    for (const migration of SOURCE_MIGRATIONS) {
-      const result = migration.transform(after);
-      after = result.source;
-      if (result.replacements > 0) {
-        const planned = perMigration.get(migration.id) ?? {
-          id: migration.id,
-          description: migration.description,
-          files: [],
-          replacements: 0
-        };
-        planned.files.push(repoPath);
-        planned.replacements += result.replacements;
-        perMigration.set(migration.id, planned);
-      }
-      blockers.push(...migration.findBlockers(after, repoPath));
-    }
-    if (after !== before) edits.push({ path: repoPath, before, after });
-  }
-  return {
-    pending: SOURCE_MIGRATIONS.flatMap((migration) => {
-      const planned = perMigration.get(migration.id);
-      return planned ? [{ ...planned, files: [...new Set(planned.files)].sort() }] : [];
-    }),
-    changedFiles: edits.map((edit) => edit.path).sort(),
-    blockers,
-    edits
-  };
-}
-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 = join23(repo, edit.path);
-    if (readFileSync25(absolutePath, "utf-8") !== edit.before) {
-      throw new Error(`Migration input changed after planning: ${edit.path}`);
-    }
-  }
-  for (const edit of plan.edits) writeFileSync10(join23(repo, edit.path), edit.after);
-}
-function isSourcePath(repoPath, appPrefix) {
-  if (appPrefix && !repoPath.startsWith(appPrefix)) return false;
-  return /\.(?:[cm]?[jt]sx?)$/.test(repoPath);
-}
-function migrateCanonicalIdentityWire(source) {
-  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="
-    );
-  }
-  migrated = migrated.replaceAll(
-    "APP_IDENTITY_TOKEN + APP_NAME",
-    "APP_IDENTITY_TOKEN + DEEPSPACE_APP_ID"
-  );
-  return {
-    source: ensureCanonicalIdentityProperties(migrated),
-    replacements
-  };
-}
-function ensureCanonicalIdentityProperties(source) {
-  const lines = source.split("\n");
-  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}`);
-  }
-  return lines.join("\n");
-}
-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;
-}
-function findLegacyIdentityWireBlockers(source, file) {
-  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;
-    }
-    blockers.push({
-      migrationId: CANONICAL_IDENTITY_WIRE_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."
-    });
-  }
-  return blockers;
-}
-
-// src/cli/lib/identity-migration-api.ts
+// src/cli/commands/migrate/identity-api.ts
 async function getIdentityMigration(deployUrl, token, appId) {
   try {
     const result = await apiFetch(
@@ -12003,11 +12145,11 @@ async function cancelIdentityMigration(deployUrl, token, appId) {
     { method: "DELETE" }
   );
 }
-async function rollbackIdentityMigration(deployUrl, token, appId) {
+async function verifyIdentityMigration(deployUrl, token, appId) {
   const result = await apiFetch(
     deployUrl,
     token,
-    `/api/apps/${encodeURIComponent(appId)}/identity-migration/rollback`,
+    `/api/apps/${encodeURIComponent(appId)}/identity-migration/verify`,
     { method: "POST" }
   );
   return result.migration;
@@ -12041,21 +12183,13 @@ var migrate_default = defineDeepspaceCommand({
       type: "boolean",
       description: "Cancel a prepared migration after restoring and publishing the legacy id",
       default: false
-    },
-    rollback: {
-      type: "boolean",
-      description: "Roll back a committed migration before any canonical deploy starts",
-      default: false
     }
   },
   async run({ args }) {
-    const recoveryMode = args.cancel === true ? "cancel" : args.rollback === true ? "rollback" : null;
-    const exclusiveModes = [args["dry-run"], args.cancel, args.rollback].filter(Boolean).length;
+    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, --cancel, or --rollback.",
-        "conflicting_migration_mode"
-      );
+      throw new Refusal("Use only one of --dry-run or --cancel.", "conflicting_migration_mode");
     }
     const appDir = findAppDir();
     if (!appDir) {
@@ -12117,12 +12251,18 @@ var migrate_default = defineDeepspaceCommand({
           applyAppMigrationPlan(appDir, sourcePlan);
           throw sourceMigrationCommitRequired(appDir, sourcePlan);
         }
-        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token);
+        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);
+        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token, {
+          envName,
+          remoteName: typeof args.remote === "string" ? args.remote : void 0
+        });
       }
       if (args["dry-run"]) {
         reportMigration(existingMigration, args.json);
@@ -12216,14 +12356,7 @@ var migrate_default = defineDeepspaceCommand({
   }
 });
 async function recoverMigration(input) {
-  const { mode, appDir, envName, remoteName, currentAppId, token, deployUrl, migration, json } = input;
-  if (migration.status === "verified" || migration.deployStartedAt) {
-    throw new Refusal(
-      "A canonical deployment has started. Registry rollback is no longer safe; use the forward-recovery procedure to repair or redeploy the canonical app.",
-      "forward_recovery_required",
-      { extra: { migration } }
-    );
-  }
+  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 });
@@ -12232,17 +12365,10 @@ async function recoverMigration(input) {
     reportMigration(migration, json);
     return { data: { status: "rolled_back", migration } };
   }
-  if (mode === "cancel" && migration.status !== "prepared") {
-    throw new Refusal(
-      "This migration is committed. Use --rollback before any canonical deploy starts.",
-      "migration_rollback_required",
-      { extra: { migration } }
-    );
-  }
-  if (mode === "rollback" && migration.status !== "committed") {
+  if (migration.status !== "prepared") {
     throw new Refusal(
-      "This migration is only prepared. Use --cancel instead.",
-      "migration_cancel_required",
+      "This migration is already committed. Complete it by deploying the canonical app.",
+      "forward_recovery_required",
       { extra: { migration } }
     );
   }
@@ -12252,14 +12378,9 @@ async function recoverMigration(input) {
   }
   const remote = requireGitHubRemote2(appDir, remoteName, migration.repository);
   requirePublishedHead2(appDir, remote);
-  if (mode === "cancel") {
-    await cancelIdentityMigration(deployUrl, token, migration.legacyAppId);
-    if (!json) console.log(`Canceled ${migration.legacyAppId} \u2192 ${migration.appId}.`);
-    return { data: { status: "cancelled", legacyAppId: migration.legacyAppId } };
-  }
-  const rolledBack = await rollbackIdentityMigration(deployUrl, token, migration.appId);
-  reportMigration(rolledBack, json);
-  return { data: { status: "rolled_back", migration: rolledBack } };
+  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;
@@ -12274,7 +12395,14 @@ async function continuePreparedMigration(input) {
     return { data: { status: "verified", migration } };
   }
   if (migration.status === "committed") {
-    throw deployRequired(appDir, migration, envName);
+    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);
@@ -12381,8 +12509,6 @@ function sourceMigrationCommitRequired(appDir, plan) {
           "--only",
           "--message",
           "Apply DeepSpace app migrations",
-          "--message",
-          `DeepSpace-Migrations: ${migrationIds.join(",")}`,
           "--",
           ...plan.changedFiles
         ]
@@ -12391,61 +12517,39 @@ function sourceMigrationCommitRequired(appDir, plan) {
     }
   );
 }
-async function requireSourceMigrationDeploy(appDir, appId, deployUrl, token) {
-  if (!isWorkTreeClean(appDir)) {
-    throw new Refusal(
-      "Commit or discard local changes before checking app migration deployment state.",
-      "dirty_worktree"
-    );
-  }
-  const head = resolveCommit(appDir, "HEAD");
-  if (!head) return;
-  const repo = repoToplevel(appDir);
-  const knownIds = new Set(APP_MIGRATION_DEFINITIONS.map((migration) => migration.id));
-  const migrationCommits = splitNulFields(
-    runGit(repo, [
-      "log",
-      "--format=%H%x00",
-      "--extended-regexp",
-      "--grep",
-      `^DeepSpace-Migrations:.*(${[...knownIds].join("|")})`
-    ]).stdout
-  ).map((oid) => oid.trim()).filter((oid) => /^[0-9a-f]{40}$/.test(oid));
-  if (migrationCommits.length === 0) return;
+async function requireSourceMigrationDeploy(appDir, appId, deployUrl, token, options = {}) {
   const { release: release2 } = await repoApi(deployUrl, token, appId).latestRelease();
-  if (release2?.commitOid === head) return;
-  const liveCommit = release2?.commitOid ?? null;
-  if (liveCommit && (resolveCommit(appDir, liveCommit) === null || !isAncestor(appDir, liveCommit, head))) {
-    throw new Refusal(
-      `The live release commit ${liveCommit.slice(0, 10)} is not an ancestor of this checkout, so migration deployment state cannot be proven. Fetch and integrate the live source history first.`,
-      "migration_lineage_unknown",
-      { extra: { appId, liveCommitOid: liveCommit, commitOid: head } }
-    );
-  }
-  const undeployedMigrationCommits = migrationCommits.filter(
-    (oid) => !liveCommit || oid !== liveCommit && isAncestor(appDir, liveCommit, oid)
+  const deployedIds = releaseMigrationIds(release2?.config);
+  const pendingIds = APP_MIGRATION_DEFINITIONS.map(({ id }) => id).filter(
+    (id) => !deployedIds.has(id)
   );
-  const pendingIds = [
-    ...new Set(
-      undeployedMigrationCommits.flatMap((oid) => {
-        const message = runGit(repo, ["show", "-s", "--format=%B", oid]).stdout.toString("utf-8");
-        return [...message.matchAll(/^DeepSpace-Migrations:\s*(.+)$/gm)].flatMap(
-          (match) => (match[1] ?? "").split(",").map((id) => id.trim()).filter((id) => knownIds.has(id))
-        );
-      })
-    )
-  ];
-  if (pendingIds.length === 0) return;
+  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(
-    `App migrations ${pendingIds.join(", ")} are committed but are not in the live release. Deploy them, then rerun.`,
+    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"] },
-      extra: { appId, sourceMigrations: pendingIds, commitOid: head }
+      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));
@@ -12526,7 +12630,7 @@ function reportMigration(migration, json) {
 // src/cli/cli.ts
 var __dirname = dirname10(fileURLToPath3(import.meta.url));
 var pkg = JSON.parse(readFileSync26(join24(__dirname, "..", "package.json"), "utf-8"));
-if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync24("/etc/ssl/certs/ca-certificates.crt")) {
+if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync25("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }
 var create2 = defineCommand14({